DosReadMailslot or Dos32ReadMailslot

The DosReadMailslot API reads and then removes the next available message of a mailslot.

Messages are stored in a mailslot based on their priority (0-9). An incoming message with a higher priority might be stored ahead of a previously stored message with the same or lower priority.

Restrictions

This API can be called from DLS and OS/2 workstations. A call to this API must be issued locally.

#include <netcons.h>
#include <mailslot.h>
 
DosReadMailslot(mailslothandle, buf, pusBytesReturned,
         nextsize, nextpriority, timeout);     /* 16 bit */
 
Dos32ReadMailslot(mailslothandle, buf, pulBytesReturned,
         nextsize, nextpriority, timeout);     /* 32 bit */

See Common Parameter Definitions for descriptions of parameters not defined here.

mailslothandle

(unsigned long) specifies (by its handle) the mailslot to read.

nextsize

(16-bit unsigned short LSFAR * or 32-bit unsigned long LSFAR *) points to an unsigned short integer indicating the size (in bytes) of the next message in the mailslot. If 0, no message is available.

nextpriority

nextsize

timeout

(long) specifies the number of milliseconds to wait if a message is not available immediately. If 0, DosReadMailslot does not wait; if -1, DosReadMailslot waits indefinitely.

The following table lists the return codes most significant to this API. (See API Return Codes for a complete list of return codes.) ┌────────────────────┬───────┬─────────────────────────────────────────────────┐│SYMBOLICCONSTANT │VALUE│MEANING │
├────────────────────┼───────┼─────────────────────────────────────────────────┤
│ NERR_Success │ 0 │ No errors were encountered. │
├────────────────────┼───────┼─────────────────────────────────────────────────┤
│ ERROR_INVALID_HANDL│ 6 │ The specified handle is not valid. │
├────────────────────┼───────┼─────────────────────────────────────────────────┤
│ ERROR_INTERRUPT │ 95 │ A system call has been interrupted. │
├────────────────────┼───────┼─────────────────────────────────────────────────┤
│ ERROR_BROKEN_PIPE │ 109 │ Write on pipe that is not being read. │
├────────────────────┼───────┼─────────────────────────────────────────────────┤
│ ERROR_SEM_TIMEOUT │ 121 │ A timeout happened from the semaphore API func- │
│ │ │ tions. │
└────────────────────┴───────┴─────────────────────────────────────────────────┘

Other codes could be returned by the DosSemRequest function.

For information about:

Reading a message without removing it, see Mailslot - DosPeekMailslot.
Writing a message to a mailslot, see Mailslot - DosWriteMailslot.

[Back: DosPeekMailslot or Dos32PeekMailslot]

[Next: DosWriteMailslot or Dos32WriteMailslot]