DosConnectNmPipe: Difference between revisions
No edit summary |
mNo edit summary |
||
| Line 1: | Line 1: | ||
This call is issued by the server process and enables the named pipe to be opened by a client. | This call is issued by the server process and enables the named pipe to be opened by a client. | ||
| Line 9: | Line 5: | ||
==Parameters== | ==Parameters== | ||
;Handle (HPIPE) - input : Handle of the named pipe that is returned by [[DosMakeNmPipe]]. | ;Handle (HPIPE) - input: Handle of the named pipe that is returned by [[DosMakeNmPipe]]. | ||
==Return Code== | ==Return Code== | ||
;rc (USHORT) - return:Return code descriptions are: | |||
Return code descriptions are: | * 0 NO_ERROR | ||
* 0 | * 95 ERROR_INTERRUPT | ||
* 95 | * 109 ERROR_BROKEN_PIPE | ||
* 109 | * 230 ERROR_BAD_PIPE | ||
* 230 | * 233 ERROR_PIPE_NOT_CONNECTED | ||
* 233 | |||
==Remarks== | ==Remarks== | ||
The server process, which creates the named pipe with DosMakeNmPipe, prepares the pipe so that it can accept a DosOpen from a client. To prepare the pipe for its first client, the server issues DosConnectNmPipe. To prepare the pipe for the next client, the server issues DosDisConnectNmPipe followed by DosConnectNmPipe. | The server process, which creates the named pipe with DosMakeNmPipe, prepares the pipe so that it can accept a [[DosOpen]] from a client. To prepare the pipe for its first client, the server issues DosConnectNmPipe. To prepare the pipe for the next client, the server issues [[DosDisConnectNmPipe]] followed by DosConnectNmPipe. | ||
When DosConnectNmPipe returns, the pipe is in a listening state. A DosOpen to a pipe that is not in a listening state fails. A client can determine the pipe's state by issuing DosPeekNmPipe. | When DosConnectNmPipe returns, the pipe is in a listening state. A DosOpen to a pipe that is not in a listening state fails. A client can determine the pipe's state by issuing [[DosPeekNmPipe]]. | ||
If the client end of the pipe is currently open, DosConnectNmPipe returns immediately and has no effect. If the client end is not open, DosConnectNmPipe either waits until it is open (if blocking mode is set) or else returns immediately with ERROR_PIPE_NOT_CONNECTED (if non-blocking mode is set). In the case where ERROR_PIPE_NOT_CONNECTED is returned, the pipe enters a listening state, permitting a client to issue a successful DosOpen. | If the client end of the pipe is currently open, DosConnectNmPipe returns immediately and has no effect. If the client end is not open, DosConnectNmPipe either waits until it is open (if blocking mode is set) or else returns immediately with ERROR_PIPE_NOT_CONNECTED (if non-blocking mode is set). In the case where ERROR_PIPE_NOT_CONNECTED is returned, the pipe enters a listening state, permitting a client to issue a successful DosOpen. | ||
| Line 29: | Line 24: | ||
If the pipe has been closed by a previous client but is not disconnected by the server, DosConnectNmPipe always returns ERROR_BROKEN_PIPE. Multiple DosConnectNmPipe calls can be issued in non-blocking mode; the first one puts the pipe into a listening state (if it is not already open or closing), and subsequent ones simply test the pipe state. | If the pipe has been closed by a previous client but is not disconnected by the server, DosConnectNmPipe always returns ERROR_BROKEN_PIPE. Multiple DosConnectNmPipe calls can be issued in non-blocking mode; the first one puts the pipe into a listening state (if it is not already open or closing), and subsequent ones simply test the pipe state. | ||
If DosConnectNmPipe is called by the client end of the pipe, ERROR_BAD_PIPE is returned. If the wait (in blocking mode only) for the client open is interrupted, the ERROR_INTERRUPT is returned. | If DosConnectNmPipe is called by the client end of the pipe, ERROR_BAD_PIPE is returned. If the wait (in blocking mode only) for the client open is interrupted, the ERROR_INTERRUPT is returned. | ||
==Example Code== | ==Example Code== | ||
| Line 37: | Line 32: | ||
USHORT rc = DosConnectNmPipe(Handle); | USHORT rc = DosConnectNmPipe(Handle); | ||
HPIPE Handle; /* Pipe handle */ | HPIPE Handle; /* Pipe handle */ | ||
USHORT rc; /* return code */ | USHORT rc; /* return code */ | ||
</PRE> | </PRE> | ||
Revision as of 15:15, 25 May 2018
This call is issued by the server process and enables the named pipe to be opened by a client.
Syntax
DosConnectNmPipe (Handle)
Parameters
- Handle (HPIPE) - input
- Handle of the named pipe that is returned by DosMakeNmPipe.
Return Code
- rc (USHORT) - return
- Return code descriptions are:
- 0 NO_ERROR
- 95 ERROR_INTERRUPT
- 109 ERROR_BROKEN_PIPE
- 230 ERROR_BAD_PIPE
- 233 ERROR_PIPE_NOT_CONNECTED
Remarks
The server process, which creates the named pipe with DosMakeNmPipe, prepares the pipe so that it can accept a DosOpen from a client. To prepare the pipe for its first client, the server issues DosConnectNmPipe. To prepare the pipe for the next client, the server issues DosDisConnectNmPipe followed by DosConnectNmPipe.
When DosConnectNmPipe returns, the pipe is in a listening state. A DosOpen to a pipe that is not in a listening state fails. A client can determine the pipe's state by issuing DosPeekNmPipe.
If the client end of the pipe is currently open, DosConnectNmPipe returns immediately and has no effect. If the client end is not open, DosConnectNmPipe either waits until it is open (if blocking mode is set) or else returns immediately with ERROR_PIPE_NOT_CONNECTED (if non-blocking mode is set). In the case where ERROR_PIPE_NOT_CONNECTED is returned, the pipe enters a listening state, permitting a client to issue a successful DosOpen.
If the pipe has been closed by a previous client but is not disconnected by the server, DosConnectNmPipe always returns ERROR_BROKEN_PIPE. Multiple DosConnectNmPipe calls can be issued in non-blocking mode; the first one puts the pipe into a listening state (if it is not already open or closing), and subsequent ones simply test the pipe state.
If DosConnectNmPipe is called by the client end of the pipe, ERROR_BAD_PIPE is returned. If the wait (in blocking mode only) for the client open is interrupted, the ERROR_INTERRUPT is returned.
Example Code
C Binding
#define INCL_DOSNMPIPES USHORT rc = DosConnectNmPipe(Handle); HPIPE Handle; /* Pipe handle */ USHORT rc; /* return code */
MASM Binding
EXTRN DosConnectNmPipe:FAR INCL_DOSNMPIPES EQU 1 PUSH WORD Handle ;Pipe handle CALL DosConnectNmPipe Returns WORD