Jump to content

DosPeekNPipe: Difference between revisions

From EDM2
← Older editNewer edit →
Ak120 (talk | contribs)
35,819 edits
Ak120 (talk | contribs)
35,819 edits
mNo edit summary
Line 1: Line 1:
=== Syntax ===
DosPeekNPipe will examine the content and status of the pipe, without changing the pipe in any way (contents and state remain).
  rc = DosPeekNPipe( ''hpipeHandle'',  
 
                    ''pBuffer'',  
== Syntax ==
                    ''ulBufferLen'',  
  DosPeekNPipe(''hpipeHandle'', ''pBuffer'', ''ulBufferLen'', ''pBytesRead'', ''pBytesAvail'', ''pPipeState'')
                    ''pBytesRead'',
                    ''pBytesAvail'',  
                    ''pPipeState'' );


=== Parameters ===
=== Parameters ===
Line 12: Line 9:
;ULONG ''ulBufferLen'' (input):The number of bytes to read.
;ULONG ''ulBufferLen'' (input):The number of bytes to read.
;PULONG ''pBytesRead'' (output):A pointer to a variable that will contain the number of bytes actually read.
;PULONG ''pBytesRead'' (output):A pointer to a variable that will contain the number of bytes actually read.
;PAVAILDATA ''pBytesAvail'' (output):This is a pointer to a 4-byte buffer. Upon return the bits will be structured as:
;[[PAVAILDATA]] ''pBytesAvail'' (output):This is a pointer to a 4-byte buffer. Upon return the bits will be structured as:
:* '''32-16''' The number of bytes that were in the pipe. This includes message-header bytes and bytes that have been examined.
:* '''32-16''' The number of bytes that were in the pipe. This includes message-header bytes and bytes that have been examined.
:* '''15-0''' The number of bytes in the current message. This will be 0 for a byte-stream pipe.
:* '''15-0''' The number of bytes in the current message. This will be 0 for a byte-stream pipe.
Line 25: Line 22:
A pipe is in the listening state after the server has called [[DosConnectNPipe]]. [[DosOpen]] may be called on a pipe that is listening.
A pipe is in the listening state after the server has called [[DosConnectNPipe]]. [[DosOpen]] may be called on a pipe that is listening.


A pipe is connected when a client has used [[DosOpen]] on it. This will allow, providing they
A pipe is connected when a client has used [[DosOpen]] on it. This will allow, providing they have valid handles, the client and the server to read and write data to the pipe.
have valid handles, the client and the server to read and write data to the pipe.


A pipe is closing when all client ends have been closed, using [[DosClose]]. The server end should then acknowledge this (the pipe is now in closing state) by issuing [[DosDisConnectNPipe]] or [[DosClose]].
A pipe is closing when all client ends have been closed, using [[DosClose]]. The server end should then acknowledge this (the pipe is now in closing state) by issuing [[DosDisConnectNPipe]] or [[DosClose]].


=== Returns ===
=== Returns ===
APIRET rc
;APIRET rc:The following values can be returned:
The following values can be returned    
*0 NO_ERROR
{| border="1"
*230 ERROR_BAD_PIPE
|0
*231 ERROR_PIPE_BUSY
|NO_ERROR
*233 ERROR_PIPE_NOT_CONNECTED
|-
|230
|ERROR_BAD_PIPE
|-
|231
|ERROR_PIPE_BUSY
|-
|233
|ERROR_PIPE_NOT_CONNECTED
|}
 
=== Include Info ===
#define INCL_DOSNMPIPES
#include <os2.h>


=== Usage Explanation ===
=== Usage Explanation ===
DosPeekNPipe will examine the content and status of the pipe, without changing the pipe in any way (contents and state remain).
DosPeekNPipe will never block. If DosPeekNPipe can't get access to the pipe at once, it will return ERROR_PIPE_BUSY. Because of this it will return what's currently in the buffer, even though this might not be a complete message.
DosPeekNPipe will never block. If DosPeekNPipe can't get access to the pipe at once, it will return ERROR_PIPE_BUSY. Because of this it will return what's currently in the buffer, even though this might not be a complete message.


=== Sample Code ===
==Sample Code==
<pre>  
<pre>  
#define INCL_DOSNMPIPES
#define INCL_DOSNMPIPES
#include  
#include <os2.h>


HPIPE Handle;      /* The pipe handle. */
HPIPE Handle;      /* The pipe handle. */
Line 69: Line 49:


ULONG PipeState; /* The returned pipestate. */
ULONG PipeState; /* The returned pipestate. */
APIRET rc;      /* Just to take care of the return code. */
APIRET rc;      /* Just to take care of the return code. */
Bufferlen = 800; /* Length of the buffer we read into. */
Bufferlen = 800; /* Length of the buffer we read into. */


Line 83: Line 61:
</pre>
</pre>


=== See Also ===
==See Also==
*[[DosConnectNPipe]]
*[[DosConnectNPipe]]
*[[DosCreateNPipe]]
*[[DosCreateNPipe]]

Revision as of 11:56, 12 October 2018

DosPeekNPipe will examine the content and status of the pipe, without changing the pipe in any way (contents and state remain).

Syntax

DosPeekNPipe(hpipeHandle, pBuffer, ulBufferLen, pBytesRead, pBytesAvail, pPipeState)

Parameters

HPIPE hpipeHandle (input)
Handle of the named pipe to examine. It is returned by DosCreateNPipe (for the server) or DosOpen (for the client).
PVOID pBuffer (output)
This is a pointer to a output buffer.
ULONG ulBufferLen (input)
The number of bytes to read.
PULONG pBytesRead (output)
A pointer to a variable that will contain the number of bytes actually read.
PAVAILDATA pBytesAvail (output)
This is a pointer to a 4-byte buffer. Upon return the bits will be structured as:
  • 32-16 The number of bytes that were in the pipe. This includes message-header bytes and bytes that have been examined.
  • 15-0 The number of bytes in the current message. This will be 0 for a byte-stream pipe.
PULONG pPipeState (input)
This is a pointer to a value, representing the state of the named pipe.
  • A value of 1 (NP_STATE_DISCONNECTED) means disconnected.
  • A value of 2 (NP_STATE_LISTENING) means listening.
  • A value of 3 (NP_STATE_CONNECTED) means connected.
  • A value of 4 (NP_STATE_CLOSING) means closing.

A pipe is in disconnected state immediately after DosCreateNPipe or DosDisConnectNPipe. A pipe that is disconnected can not be opened using DosOpen.

A pipe is in the listening state after the server has called DosConnectNPipe. DosOpen may be called on a pipe that is listening.

A pipe is connected when a client has used DosOpen on it. This will allow, providing they have valid handles, the client and the server to read and write data to the pipe.

A pipe is closing when all client ends have been closed, using DosClose. The server end should then acknowledge this (the pipe is now in closing state) by issuing DosDisConnectNPipe or DosClose.

Returns

APIRET rc
The following values can be returned:
  • 0 NO_ERROR
  • 230 ERROR_BAD_PIPE
  • 231 ERROR_PIPE_BUSY
  • 233 ERROR_PIPE_NOT_CONNECTED

Usage Explanation

DosPeekNPipe will never block. If DosPeekNPipe can't get access to the pipe at once, it will return ERROR_PIPE_BUSY. Because of this it will return what's currently in the buffer, even though this might not be a complete message.

Sample Code

 
#define INCL_DOSNMPIPES
#include <os2.h>

HPIPE Handle;       /* The pipe handle. */
UCHAR Buffer[800];  /* The user buffer. */
ULONG BufferLen;    /* The length of the buffer. */
ULONG BytesRead;    /* The actual number of bytes read. */

struct _AVAILDATA BytesAvail; /* Bytes available. */

ULONG PipeState; /* The returned pipestate. */
APIRET rc;       /* Just to take care of the return code. */
Bufferlen = 800; /* Length of the buffer we read into. */

rc = DosPeekNPipe( Handle, Buffer, BufferLen, &BytesRead,
         &BytesAvail, &PipeState);

if (rc != 0)
{
   /* We have an error we must take care of. */
}

See Also

Retrieved from "https://www.edm2.com/index.php?title=DosPeekNPipe&oldid=59090"