DosDisConnectNPipe: Difference between revisions
No edit summary |
|||
| Line 1: | Line 1: | ||
=== Syntax === | === Syntax === | ||
rc = DosDisConnectNPipe( ''hpipeHandle'' ); | rc = DosDisConnectNPipe( ''hpipeHandle'' ); | ||
=== Parameters === | === Parameters === | ||
HPIPE ''hpipeHandle'' (input) | |||
The handle to the named-pipe, as returned by [[DosCreateNPipe]]. | The handle to the named-pipe, as returned by [[DosCreateNPipe]]. | ||
=== Returns === | === Returns === | ||
APIRET rc | |||
The following values can be returned | |||
{|class="wikitable" | |||
The following values can be returned | |||
{| | |||
|0 | |0 | ||
|NO_ERROR | |NO_ERROR | ||
| Line 26: | Line 19: | ||
|230 | |230 | ||
|ERROR_BAD_PIPE | |ERROR_BAD_PIPE | ||
|} | |} | ||
=== Include Info === | === Include Info === | ||
#define INCL_DOSNMPIPES | #define INCL_DOSNMPIPES | ||
#include | #include <os2.h> | ||
=== Usage Explanation === | === Usage Explanation === | ||
A server process uses DosDisConnectNPipe to acknowledge that a client process has closed a named pipe. Any attempt by a client process to use DosDisConnectNPipe will result in the ERROR_BAD_PIPE error returned to the child process. Until the server has issued DosDisConnectNPipe followed by [[OS2 API:CPI:DosConnectNPipe|CPI:DosConnectNPipe]] another child process can't open the pipe. | |||
Between the child closing its end of the pipe, and the server disconnecting the pipe, any attempt by the server to read from the pipe will result in a value of 0 returned to it. An attempt to write to it will result in ERROR_BROKEN_PIPE error returned. ERROR_PIPE_BUSY will be returned to all clients trying to open the pipe. | |||
Between the child closing its end of the pipe, and the server disconnecting | |||
the pipe, any attempt by the server to read from the pipe will result in a | |||
value of 0 returned to it. An attempt to write to it will result in | |||
ERROR_BROKEN_PIPE error returned. ERROR_PIPE_BUSY will be returned to all | |||
clients trying to open the pipe | |||
If the client's end is still open when the server issues DosDisConnectNPipe, it will result in the pipe being disconnected from the server, closed on the client side. There are two things to note about the client here. It does not specifically get a message that the pipe has been | |||
closed for it, instead it will recieve an error next time it tries to access the pipe. The other thing to note is that since the server forced closing of the client side, data that has not yet been read by the client will be lost. | |||
Blocked threads are awakened by DosDisConnectNPipe. A thread blocked by [[OS2 API:CPI:DosRead|CPI:DosRead]] will receive a value of zero for bytes read. A thread blocked by [[OS2 API:CPI:DosWrite|CPI:DosWrite]] will receive the ERROR_BROKEN_PIPE error. | Blocked threads are awakened by DosDisConnectNPipe. A thread blocked by [[OS2 API:CPI:DosRead|CPI:DosRead]] will receive a value of zero for bytes read. A thread blocked by [[OS2 API:CPI:DosWrite|CPI:DosWrite]] will receive the ERROR_BROKEN_PIPE error. | ||
The client's handle becomes invalid by the server calling DosDisConnectNPipe, but it does not free the handle. Therefore the client must issue [[OS2 API:CPI:DosClose|CPI:DosClose]] in order to free the resources used. | The client's handle becomes invalid by the server calling DosDisConnectNPipe, but it does not free the handle. Therefore the client must issue [[OS2 API:CPI:DosClose|CPI:DosClose]] in order to free the resources used. | ||
=== Relevant Structures === | === Relevant Structures === | ||
| Line 75: | Line 46: | ||
#include | #include | ||
HPIPE Handle; | HPIPE Handle; /* The pipe handle. */ | ||
APIRET rc; /* Just to take care of the return code */ | |||
APIRET rc; | |||
rc = DosDisConnectNPipe( Handle); | rc = DosDisConnectNPipe( Handle); | ||
| Line 88: | Line 56: | ||
} | } | ||
</pre> | </pre> | ||
=== See Also === | === See Also === | ||
[[OS2 API:CPI:DosConnectNPipe|DosConnectNPipe]], | [[OS2 API:CPI:DosConnectNPipe|DosConnectNPipe]], | ||
Revision as of 12:24, 2 October 2016
Syntax
rc = DosDisConnectNPipe( hpipeHandle );
Parameters
HPIPE hpipeHandle (input)
The handle to the named-pipe, as returned by DosCreateNPipe.
Returns
APIRET rc
The following values can be returned
| 0 | NO_ERROR |
| 109 | ERROR_BROKEN_PIPE |
| 230 | ERROR_BAD_PIPE |
Include Info
#define INCL_DOSNMPIPES #include <os2.h>
Usage Explanation
A server process uses DosDisConnectNPipe to acknowledge that a client process has closed a named pipe. Any attempt by a client process to use DosDisConnectNPipe will result in the ERROR_BAD_PIPE error returned to the child process. Until the server has issued DosDisConnectNPipe followed by CPI:DosConnectNPipe another child process can't open the pipe.
Between the child closing its end of the pipe, and the server disconnecting the pipe, any attempt by the server to read from the pipe will result in a value of 0 returned to it. An attempt to write to it will result in ERROR_BROKEN_PIPE error returned. ERROR_PIPE_BUSY will be returned to all clients trying to open the pipe.
If the client's end is still open when the server issues DosDisConnectNPipe, it will result in the pipe being disconnected from the server, closed on the client side. There are two things to note about the client here. It does not specifically get a message that the pipe has been closed for it, instead it will recieve an error next time it tries to access the pipe. The other thing to note is that since the server forced closing of the client side, data that has not yet been read by the client will be lost.
Blocked threads are awakened by DosDisConnectNPipe. A thread blocked by CPI:DosRead will receive a value of zero for bytes read. A thread blocked by CPI:DosWrite will receive the ERROR_BROKEN_PIPE error.
The client's handle becomes invalid by the server calling DosDisConnectNPipe, but it does not free the handle. Therefore the client must issue CPI:DosClose in order to free the resources used.
Relevant Structures
Gotchas
Sample Code
#define INCL_DOSNMPIPES
#include
HPIPE Handle; /* The pipe handle. */
APIRET rc; /* Just to take care of the return code */
rc = DosDisConnectNPipe( Handle);
if (rc != 0)
{
/* We have an error we must take care of. */
}
See Also
DosConnectNPipe, DosCreateNPipe, DosDisConnectNPipe, DosPeekNPipe, DosQueryNPHState, DosQueryNPipeInfo, DosQueryNPipeSemState, DosSetNPHState, DosSetNPipeSem, DosTransactNPipe, DosWaitNPipe, DosClose, DosDupHandle, DosOpen, DosRead, DosResetBuffer, DosWrite