 |
Pipe9x
Pipes with overlapped-style I/O on Windows 9x
|
|
Pipe9x
Pipes with overlapped-style I/O on Windows 9x
|
#include <windows.h>Go to the source code of this file.
Typedefs | |
| typedef struct _PipeWriteHandle * | PipeWriteHandle |
| typedef struct _PipeReadHandle * | PipeReadHandle |
Functions | |
| DWORD | pipe9x_create (PipeReadHandle *prh_out, size_t read_size, BOOL read_inherit, PipeWriteHandle *pwh_out, size_t write_size, BOOL write_inherit) |
| Create a pair of connected pipe handles. More... | |
| void | pipe9x_read_close (PipeReadHandle prh) |
| Closes the read end of a pipe created by pipe9x_create(). More... | |
| DWORD | pipe9x_read_initiate (PipeReadHandle prh) |
| Start a read in the background. More... | |
| DWORD | pipe9x_read_result (PipeReadHandle prh, void **data_out, size_t *data_size_out, BOOL wait) |
| Get the result from a read operation. More... | |
| BOOL | pipe9x_read_pending (PipeReadHandle prh) |
| Check if a read operation is pending. More... | |
| HANDLE | pipe9x_read_pipe (PipeReadHandle prh) |
| Get the underlying Windows HANDLE of the pipe. More... | |
| HANDLE | pipe9x_read_event (PipeReadHandle prh) |
| Get an event object for detecting I/O completion. More... | |
| void | pipe9x_write_close (PipeWriteHandle pwh) |
| Closes the write end of a pipe created by pipe9x_create(). More... | |
| DWORD | pipe9x_write_initiate (PipeWriteHandle prh, const void *data, size_t data_size) |
| Start a write in the background. More... | |
| DWORD | pipe9x_write_result (PipeWriteHandle pwh, size_t *data_written_out, BOOL wait) |
| Get the result from a write operation. More... | |
| BOOL | pipe9x_write_pending (PipeWriteHandle pwh) |
| Check if a write operation is pending. More... | |
| HANDLE | pipe9x_write_pipe (PipeWriteHandle pwh) |
| Get the underlying Windows HANDLE of the pipe. More... | |
| HANDLE | pipe9x_write_event (PipeWriteHandle prh) |
| Get an event object for detecting I/O completion. More... | |
| DWORD pipe9x_create | ( | PipeReadHandle * | prh_out, |
| size_t | read_size, | ||
| BOOL | read_inherit, | ||
| PipeWriteHandle * | pwh_out, | ||
| size_t | write_size, | ||
| BOOL | write_inherit | ||
| ) |
Create a pair of connected pipe handles.
| prh_out | Pointer to PipeReadHandle to receive read handle. |
| read_size | Size of pipe read buffer. |
| read_inherit | Whether the pipe read handle is inherited by new processes. |
| pwh_out | Pointer to PipeWriteHandle to receive write handle. |
| write_size | Size of pipe write buffer. |
| write_inherit | Whether the pipe write handle is inherited by new processes. |
This function creates a pair of connected pipe handles and other supporting handles/structures wrapped in a PipeReadHandle and PipeWriteHandle object.
On success, ERROR_SUCCESS is returned and *prh_out and *pwh_out are both initialised to non-NULL values.
On error, a win32 error code is returned and *prh_out and *pwh_out are both initialised to NULL.
The buffer size parameters specify the size of the internal read/write buffers to allocate and set the upper size limit for read/write operations.
| void pipe9x_read_close | ( | PipeReadHandle | prh | ) |
Closes the read end of a pipe created by pipe9x_create().
| prh | PipeReadHandle object to destroy (may be NULL). |
| HANDLE pipe9x_read_event | ( | PipeReadHandle | prh | ) |
Get an event object for detecting I/O completion.
This function obtains a HANDLE to an event object which can be used to detect when a read operation has finished.
The returned handle may be waited on, but must not be manually reset, set or otherwise altered.
| DWORD pipe9x_read_initiate | ( | PipeReadHandle | prh | ) |
Start a read in the background.
This function will initiate an asynchronous read from the pipe into the internal buffer of the PipeReadHandle object.
On success, this function returns ERROR_IO_PENDING (for consistensy with Win32 API functions) and completion can be polled using the pipe9x_read_result() function or waited on using the event object returned by pipe9x_read_event().
Only one read operation can be pending at a time, attempting to start a second read before the first one is completed using pipe9x_read_result() will return ERROR_IO_INCOMPLETE.
On Windows NT, this function uses overlapped I/O, on Windows 9x, a blocking read is performed in a background thread instead.
| BOOL pipe9x_read_pending | ( | PipeReadHandle | prh | ) |
Check if a read operation is pending.
This function checks if a read operation is pending. It will return true from the point pipe9x_read_initiate() is called until a call to pipe9x_read_result() which does not return ERROR_IO_PENDING is made.
| HANDLE pipe9x_read_pipe | ( | PipeReadHandle | prh | ) |
Get the underlying Windows HANDLE of the pipe.
This function obtains the underlying Windows HANDLE of the pipe, this is intended for passing one end of the pipe into another process or library.
Once the handle has been passed into a child process or duplicated, the original PipeReadHandle object may be destroyed with pipe9x_read_close().
| DWORD pipe9x_read_result | ( | PipeReadHandle | prh, |
| void ** | data_out, | ||
| size_t * | data_size_out, | ||
| BOOL | wait | ||
| ) |
Get the result from a read operation.
| prh | PipeReadHandle object to check status of. |
| data_out | Pointer to receive pointer to read data. |
| data_size_out | Pointer to receive read data size. |
| wait | Whether to wait for completion before returning. |
This function gets the result of a read operation previous started using the pipe9x_read_initiate() function.
If the read completed successfully, ERROR_SUCCESS is returned, *data_out is initialised with a pointer to the read data and *data_size_out contains the number of bytes. The data remains valid until the PipeReadHandle object is destroyed or pipe9x_read_initiate() is called again.
If no data has been read yet, and wait is FALSE, ERROR_IO_INCOMPLETE will be returned.
If any other error occurs, the relevant Win32 error code is returned.
| void pipe9x_write_close | ( | PipeWriteHandle | pwh | ) |
Closes the write end of a pipe created by pipe9x_create().
| pwh | PipeWriteHandle object to destroy (may be NULL). |
| HANDLE pipe9x_write_event | ( | PipeWriteHandle | prh | ) |
Get an event object for detecting I/O completion.
This function obtains a HANDLE to an event object which can be used to detect when a write operation has finished.
The returned handle may be waited on, but must not be manually reset, set or otherwise altered.
| DWORD pipe9x_write_initiate | ( | PipeWriteHandle | prh, |
| const void * | data, | ||
| size_t | data_size | ||
| ) |
Start a write in the background.
| pwh | PipeWriteHandle to write to. |
| data | Pointer to data buffer. |
| data_size | Size of data buffer. |
This function will initiate an asynchronous write to the pipe from the internal buffer of the PipeWriteHandle object. The provided data is copied into the internal buffer before the function returns.
On success, this function returns ERROR_IO_PENDING (for consistensy with Win32 API functions) and completion can be polled using the pipe9x_write_result() function or waited on using the event object returned by pipe9x_write_event().
Only one write operation can be pending at a time, attempting to start a second write before the first one is completed using pipe9x_write_result() will return ERROR_IO_INCOMPLETE.
On Windows NT, this function uses overlapped I/O, on Windows 9x, a blocking write is performed in a background thread instead.
| BOOL pipe9x_write_pending | ( | PipeWriteHandle | pwh | ) |
Check if a write operation is pending.
This function checks if a write operation is pending. It will return true from the point pipe9x_write_initiate() is called until a call to pipe9x_write_result() which does not return ERROR_IO_PENDING is made.
| HANDLE pipe9x_write_pipe | ( | PipeWriteHandle | pwh | ) |
Get the underlying Windows HANDLE of the pipe.
This function obtains the underlying Windows HANDLE of the pipe, this is intended for passing one end of the pipe into another process or library.
Once the handle has been passed into a child process or duplicated, the original PipeWriteHandle object may be destroyed with pipe9x_write_close().
| DWORD pipe9x_write_result | ( | PipeWriteHandle | pwh, |
| size_t * | data_written_out, | ||
| BOOL | wait | ||
| ) |
Get the result from a write operation.
| prw | PipeWriteHandle object to check status of. |
| data_written_out | Pointer to receive number of bytes written (on success). |
| wait | Whether to wait for completion before returning. |
This function gets the result of a write operation previous started using the pipe9x_write_initiate() function.
If the write completed successfully, ERROR_SUCCESS is returned and *data_written_out is initialised with the number of bytes successfully written to the pipe.
If the write is still in progress and wait is FALSE, ERROR_IO_INCOMPLETE will be returned.
If any other error occurs, the relevant Win32 error code is returned.
1.9.4