DosWriteMailslot or Dos32WriteMailslot

The DosWriteMailslot API writes a message to a particular mailslot.

To send a message to all computers on the primary domain that have a local mailslot with the same name, an application must pass the name parameter \\*\mailslot\name and the class parameter 2 to DosWriteMailslot.

Restrictions

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

Second-class messages must be 400 bytes or smaller when written to remote requesters; they can be any size when written to local computers or remote servers.

Syntax

#include <netcons.h>
#include <mailslot.h>
 
DosWriteMailslot(pMailslotName, message, size,
               priority, class, timeout);      /* 16 bit */
 
Dos32WriteMailslot(pMailslotName, message, size,
               priority, class, timeout);      /* 32 bit */

Parameters

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

pMailslotName

(const unsigned char LSFAR *) points to an ASCIIZ string containing the name of the mailslot to which the message is to be written. This parameter cannot be a null pointer, but can point to a null string.

For the name of a local mailslot, use the format \mailslot\name.

For a remote mailslot, use \\computername\mailslot\ name.

For all mailslots with the same name, but on different computers in the primary domain, use \\*\mailslot\ name.

message
(const unsigned char LSFAR *) points to an ASCIIZ string containing the message to be written to the mailslot.
size
(16-bit unsigned short or 32-bit unsigned long) specifies the size (in bytes) of the message to be written.
priority
(16-bit unsigned short or 32-bit unsigned long) assigns a priority to the message. The priority of a message ranges from 0 (lowest) to 9 (highest). High-priority messages generally are placed ahead of previously stored messages with lower priority, except when the mailslot already is full.
class
(16-bit unsigned short or 32-bit unsigned long) specifies the class of mail service to be provided, where:

• First-class mail (class is 1) forces DosWriteMailslot to wait until a mailslot has enough room to accept message or until timeout is reached. First-class mail can be delivered only to remote servers or local computers.

• Second-class mail (class is 2) causes DosWriteMailslot to fail if there is not enough room to write the message in the mailslot. Second-class mail can be delivered to requesters or servers.
timeout
(long) specifies the number of milliseconds to wait before discontinuing the attempt to write the message. A value of 0 means only one attempt is made. A value of -1 means DosWriteMailslot repeats the attempt until the message is written (or an error occurs).
Return Codes

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_PATH_NOT_FOUND │ 3 │ The path was not found. │
├─────────────────────────────┼────────────┼───────────────────────────────────┤
│ ERROR_NOT_SUPPORTED │ 50 │ This request is not supported by │
│ │ │ the network. │
├─────────────────────────────┼────────────┼───────────────────────────────────┤
│ ERROR_INVALID_PARAMETER │ 87 │ At least one parameter value is │
│ │ │ not valid. │
├─────────────────────────────┼────────────┼───────────────────────────────────┤
│ ERROR_INTERRUPT │ 95 │ A system call has been inter- │
│ │ │ rupted. │
├─────────────────────────────┼────────────┼───────────────────────────────────┤
│ ERROR_BROKEN_PIPE │ 109 │ Write on pipe that is not being │
│ │ │ read. │
├─────────────────────────────┼────────────┼───────────────────────────────────┤
│ ERROR_BUFFER_OVERFLOW │ 111 │ The buffer passed to the system │
│ │ │ call is too small to hold return │
│ │ │ data. │
├─────────────────────────────┼────────────┼───────────────────────────────────┤
│ ERROR_SEM_TIMEOUT │ 121 │ A timeout happened from the │
│ │ │ semaphore API functions. │
├─────────────────────────────┼────────────┼───────────────────────────────────┤
│ NERR_NetNotStarted │ 2102 │ The redirector NETWKSTA.200 has │
│ │ │ not been started. │
└─────────────────────────────┴────────────┴───────────────────────────────────┘


Other codes could be returned from the following functions:

• DosAllocSeg
  
• DosDevIOCtl
  
• DosFsCtl
  
• DosGetShrSeg
  
• DosSemRequest
Related Information

For information about:

• Creating a mailslot, see Mailslot - DosMakeMailslot. 
  Reading a message, see Mailslot - DosReadMailslot.

  ---

  [Back: DosReadMailslot or Dos32ReadMailslot]
  [Next: Message Category]