pipes.h File Reference

Pipe channel communication utilities. More...

#include "gate/io/gate_io_api.h"
#include "gate/gatetypes.h"
#include "gate/strings.h"
#include "gate/streams.h"

Macros
#define	GATE_PIPE_FLAG_CREATE   0x0001
#define	GATE_PIPE_FLAG_READ   0x0002
#define	GATE_PIPE_FLAG_WRITE   0x0004

Typedefs
typedef void *	gate_pipe_t

Functions
GATE_IO_API gate_result_t	gate_pipe_create (gate_pipe_t *readpipe, gate_pipe_t *writepipe)
	Creates a new anonymous pipe and returns and read and write handles to it.
GATE_IO_API gate_result_t	gate_pipe_open (gate_string_t *name, gate_enumint_t flags, gate_pipe_t *readpipe, gate_pipe_t *writepipe)
	Creates or opens a named pipe and returns.
GATE_IO_API gate_result_t	gate_pipe_close (gate_pipe_t pipe)
	Closes a pipe handle.
GATE_IO_API gate_result_t	gate_pipe_data_available (gate_pipe_t pipe, gate_bool_t *data_available)
	Returns the read status of the pipe to indicate if a non-block read is possible.
GATE_IO_API gate_result_t	gate_pipe_read (gate_pipe_t pipe, char *buffer, gate_size_t bufferlen, gate_size_t *returned)
	Reads data from a pipe handle into a buffer.
GATE_IO_API gate_result_t	gate_pipe_write (gate_pipe_t pipe, char const *buffer, gate_size_t bufferlen, gate_size_t *written)
	Writes data from a buffer into a pipe.
GATE_IO_API gate_result_t	gate_pipe_duplicate (gate_pipe_t src, gate_pipe_t *dst)
	Creates a duplicate of the pipe handle.
GATE_IO_API gate_result_t	gate_pipe_export (gate_pipe_t pipe, gate_string_t *pipeid)
	Exports a pipe handle as a string to be used for process-inheritance.
GATE_IO_API gate_result_t	gate_pipe_import (gate_string_t const *pipeid, gate_pipe_t *pipe)
	Imports a pipe handle from a string-id from process-inheritance.
GATE_IO_API gate_result_t	gate_pipe_open_stream (gate_string_t *name, gate_enumint_t flags, gate_stream_t **ptr_stream)
	Opens a pipe as a gate-stream object.

Variables
GATE_IO_API gate_pipe_t const	gate_pipe_invalid

Detailed Description

Pipe channel communication utilities.

Macro Definition Documentation

GATE_PIPE_FLAG_CREATE

#define GATE_PIPE_FLAG_CREATE   0x0001

Create a new pipe (with read and write access)

GATE_PIPE_FLAG_READ

#define GATE_PIPE_FLAG_READ   0x0002

Open an existing pipe for read access

GATE_PIPE_FLAG_WRITE

#define GATE_PIPE_FLAG_WRITE   0x0004

Open an existing pipe for write access

Typedef Documentation

gate_pipe_t

typedef void* gate_pipe_t

native pipe handle

Function Documentation

gate_pipe_create()

GATE_IO_API gate_result_t gate_pipe_create	(	gate_pipe_t *	readpipe,
		gate_pipe_t *	writepipe )

Creates a new anonymous pipe and returns and read and write handles to it.

Parameters

[out]	readpipe	pointer to pipe-handle of read-side
[out]	writepipe	pointer to pipe-handle of write-side

Returns

GATE_RESULT_* result code

gate_pipe_open()

GATE_IO_API gate_result_t gate_pipe_open	(	gate_string_t *	name,
		gate_enumint_t	flags,
		gate_pipe_t *	readpipe,
		gate_pipe_t *	writepipe )

Creates or opens a named pipe and returns.

Parameters

[in,out]	name	pointer to string to be filled with generated pipe name for creation OR name of pipe to be opened
[in]	flags	GATE_PIPE_FLAG_* identifier
[out]	readpipe	pointer to pipe-handle of read-side
[out]	writepipe	pointer to pipe-handle of write-side

Returns

GATE_RESULT_* result code

gate_pipe_close()

GATE_IO_API gate_result_t gate_pipe_close

(

gate_pipe_t

pipe

)

Closes a pipe handle.

Parameters

[in]

pipe

handle to pipe to be closed

Returns

GATE_RESULT_* result code

gate_pipe_data_available()

GATE_IO_API gate_result_t gate_pipe_data_available	(	gate_pipe_t	pipe,
		gate_bool_t *	data_available )

Returns the read status of the pipe to indicate if a non-block read is possible.

Parameters

[in]	pipe	handle to pipe to be accessed
[out]	data_available	pointer to boolean to receive available-state

Returns

GATE_RESULT_* result code

gate_pipe_read()

GATE_IO_API gate_result_t gate_pipe_read	(	gate_pipe_t	pipe,
		char *	buffer,
		gate_size_t	bufferlen,
		gate_size_t *	returned )

Reads data from a pipe handle into a buffer.

Parameters

[in]	pipe	handle to pipe to be accessed
[out]	buffer	pointer to buffer to be filled with retrieved bytes
[in]	bufferlen	maximum capacity of buffer in bytes
[out]	returned	pointer to field that receives retrieved amount of bytes

Returns

GATE_RESULT_* result code

gate_pipe_write()

GATE_IO_API gate_result_t gate_pipe_write	(	gate_pipe_t	pipe,
		char const *	buffer,
		gate_size_t	bufferlen,
		gate_size_t *	written )

Writes data from a buffer into a pipe.

Parameters

[in]	pipe	handle to pipe to be accessed
[in]	buffer	pointer to buffer with data to be written to pipe
[in]	bufferlen	amount of bytes in buffer to be written
[out]	returned	pointer to field that receives actual written amount of bytes

Returns

GATE_RESULT_* result code

gate_pipe_duplicate()

GATE_IO_API gate_result_t gate_pipe_duplicate	(	gate_pipe_t	src,
		gate_pipe_t *	dst )

Creates a duplicate of the pipe handle.

Parameters

[in]	src	handle to pipe to be accessed
[out]	dst	pointer to new pipe-handle to be filled

Returns

GATE_RESULT_* result code

gate_pipe_export()

GATE_IO_API gate_result_t gate_pipe_export	(	gate_pipe_t	pipe,
		gate_string_t *	pipeid )

Exports a pipe handle as a string to be used for process-inheritance.

Parameters

[in]	pipe	handle to pipe to be accessed
[out]	pipeid	pointer to string to be created with serialized pipe-ID

Returns

GATE_RESULT_* result code

gate_pipe_import()

GATE_IO_API gate_result_t gate_pipe_import	(	gate_string_t const *	pipeid,
		gate_pipe_t *	pipe )

Imports a pipe handle from a string-id from process-inheritance.

Parameters

[in]	pipeid	pointer to string with serialized pipe-ID
[out]	pipe	pointer to output pipe-handle to be filled

Returns

GATE_RESULT_* result code

gate_pipe_open_stream()

GATE_IO_API gate_result_t gate_pipe_open_stream	(	gate_string_t *	name,
		gate_enumint_t	flags,
		gate_stream_t **	ptr_stream )

Opens a pipe as a gate-stream object.

Parameters

[in]	name	pointer to string to be created with new pipe-name OR string with pipe-name to be opened
[in]	flags	GATE_PIPE_FLAG_* option
[out]	ptr_stream	pointer to stream-pointer which gets new created object

Returns

GATE_RESULT_* result code

Variable Documentation

gate_pipe_invalid

GATE_IO_API gate_pipe_t const gate_pipe_invalid

extern

special ID identifying an invalid pipe