Stream common
[Socket streams]

---

Detailed Description

Creation methods and other common methods for socket streams.

Functions
peak_stream	peak_stream_socket_create (struct sockaddr *name, int namelen, uint32_t opt, peak_stream_event_callback cb, void *context)
	Creates a new socket stream from a socket address.
peak_stream	peak_stream_accept_create (peak_stream ss, uint32_t opt, peak_stream_event_callback cb, void *context)
	Creates a new socket stream from a incoming connection on a listening stream.
peak_stream	peak_stream_raw_create (int fd, uint32_t opt, peak_stream_event_callback cb, void *context)
	Creates a new socket stream from a "raw" file descriptor (which must be a valid opened socket).
int	peak_stream_is_open (peak_stream s)
	Test is a socket stream is open.
int	peak_stream_get_error (peak_stream s)
	Get last stream system error code.
int	peak_stream_get_address (peak_stream s, struct sockaddr *name, int *namelen)
	Get peer's name (address).
int	peak_stream_set_address (peak_stream s, struct sockaddr *name, int namelen)
	Assign a name (address) to an unnamed socket.
int	peak_stream_connect (peak_stream s)
	Connect the stream.
void	peak_stream_disconnect (peak_stream s)
	Disconnect the stream.
void *	peak_stream_get_context (peak_stream s)
	Get the context pointer of a stream.
void	peak_stream_set_context (peak_stream s, void *context)
	Change the context pointer of a stream.
size_t	peak_stream_get_read_count (peak_stream s)
	Get amount of bytes actually read from the stream.
size_t	peak_stream_get_write_count (peak_stream s)
	Get amount of bytes actually written to the stream.
void	peak_stream_set_timeout (peak_stream s, int timeout)
	Configure event timeout checking for a specified stream.

---

Function Documentation

peak_stream peak_stream_accept_create (  peak_stream  ss, uint32_t  opt, peak_stream_event_callback  cb, void *  context )

Creates a new socket stream from a incoming connection on a listening stream. Parameters: ss  The server's socket stream that got a PEAK_STREAM_EVT_ACCEPT event. opt  Stream creation options. cb  A pointer to your notification callback function that handles events that will occur on this stream once scheduled. context  An extra application-defined pointer that will be passed to your event callback function (it's not used by the library). Returns: A newly allocated peak_stream reference or NULL if the stream cannot be created.

int peak_stream_connect (  peak_stream  s  )

Connect the stream. Parameters: s  The stream reference. Return values: 0  if the operation is successful. -1  if the connection to the remote host failed.

void peak_stream_disconnect (  peak_stream  s  )

Disconnect the stream. Parameters: s  The stream reference.

int peak_stream_get_address (  peak_stream  s, struct sockaddr *  name, int *  namelen )

Get peer's name (address). Parameters: s  The stream reference. name  A pointer to an allocated space for the address, enough to hold it (eg. a struct sockaddr_in for an IPv4 address). namelen  Input/output argument, should be initialized to indicate the amount of size pointed to by name. On return it contains the actual size of the name returned (in bytes). Return values: 0  if the operation is successful. -1  if the buffer name is too small.

void* peak_stream_get_context (  peak_stream  s  )

Get the context pointer of a stream. Parameters: s  The stream reference. Returns: The application-defined pointer.

int peak_stream_get_error (  peak_stream  s  )

Get last stream system error code. Returns the last socket or system error code as defined in sys/errno.h. Parameters: s  The stream reference. Returns: The error code.

size_t peak_stream_get_read_count (  peak_stream  s  )

Get amount of bytes actually read from the stream. Statistical function. Parameters: s  The stream reference. Returns: Number of bytes read since the stream's creation.

size_t peak_stream_get_write_count (  peak_stream  s  )

Get amount of bytes actually written to the stream. Statistical function. Parameters: s  The stream reference. Returns: Number of bytes written since the stream's creation.

int peak_stream_is_open (  peak_stream  s  )

Test is a socket stream is open. An open stream is a connected socket for connection oriented streams. Parameters: s  The stream reference. Return values: 0  Stream not open. 1  Stream open.

peak_stream peak_stream_raw_create (  int  fd, uint32_t  opt, peak_stream_event_callback  cb, void *  context )

Creates a new socket stream from a "raw" file descriptor (which must be a valid opened socket). Parameters: fd  The socket file descriptor. opt  Stream creation options. cb  A pointer to your notification callback function that handles events that will occur on this stream once scheduled. context  An extra application-defined pointer that will be passed to your event callback function (it's not used by the library). Returns: A newly allocated peak_stream reference or NULL if the stream cannot be created.

int peak_stream_set_address (  peak_stream  s, struct sockaddr *  name, int  namelen )

Assign a name (address) to an unnamed socket. This function allow you to bind the stream to a local address which is not the default (eg. for a vhost). Not for use with streams with the PEAK_STREAM_OPT_LISTEN option flag. Parameters: s  The stream reference. name  A pointer to a structure describing the name (address) to assign to the stream socket. namelen  The length of the pointed structure by name. Return values: 0  if the operation is successful. -1  otherwise.

void peak_stream_set_context (  peak_stream  s, void *  context )

Change the context pointer of a stream. Parameters: s  The stream reference. context  An extra application-defined pointer that will be passed to your event callback function (it's not used by the library).

void peak_stream_set_timeout (  peak_stream  s, int  timeout )

Configure event timeout checking for a specified stream. This is a convenience feature. First, because an explicit timer isn't needed to check stream's timeout in your application anymore. But for thread safety too: when peak is not explicitely configured to use only one thread, an independant timer might be processed at the same time with an event on the stream, so you need to add mutual exclusive region (implementation is possible with peak_task_exclusivity()), and verify all it's well synchronized. With peak_stream_set_timeout() however, the timeout event acts like a normal stream events and cannot be processed at the same time with another on the same stream. Parameters: s  The stream reference. timeout  Time in seconds until an event of type PEAK_STREAM_EVT_TIMEDOUT will be sent. Use 0 to disable timeout checking.

peak_stream peak_stream_socket_create (  struct sockaddr *  name, int  namelen, uint32_t  opt, peak_stream_event_callback  cb, void *  context )

Creates a new socket stream from a socket address. Parameters: name  Pointer to a socket's name/address. For listening sockets, this is the name/local address of the socket, but for outgoing sockets this is the name/address of the other socket. Several socket protocol types are supported (PF_INET, PF_INET6). namelen  Length of the structure pointed by name. opt  Stream creation options. cb  A pointer to your notification callback function that handles events that will occur on this stream once scheduled. context  An extra application-defined pointer that will be passed to your event callback function (it's not used by the library). Returns: A newly allocated peak_stream reference or NULL if the stream cannot be created.

---