Addressing and I/O interface for messages. More...

#include <sofia-sip/msg.h>
#include <sofia-sip/su.h>

Include dependency graph for msg_addr.h:

Defines
#define	MSG_ADDR_H
	Defined when <sofia-sip/msg_addr.h> has been included.
Typedefs
typedef struct su_iovec_s	msg_iovec_t
	I/O vector type.
Enumerations
enum	{ msg_min_size, msg_min_block, msg_n_fragments }
Functions
void	msg_addr_zero (msg_t *msg)
	Zero the message address.
su_addrinfo_t *	msg_addrinfo (msg_t *msg)
	Get addrinfo structure.
su_sockaddr_t *	msg_addr (msg_t *msg)
	Get pointer to socket address structure.
int	msg_get_address (msg_t msg, su_sockaddr_t , socklen_t *)
	Get message address.
int	msg_set_address (msg_t msg, su_sockaddr_t const , socklen_t)
	Set message address.
void	msg_addr_copy (msg_t dst, msg_t const src)
	Copy message address.
int	msg_errno (msg_t const *msg)
	Get error number associated with message.
void	msg_set_errno (msg_t *msg, int err)
	Set error number associated with message.
isize_t	msg_iovec (msg_t *msg, msg_iovec_t vec[], isize_t veclen)
	Fill an I/O vector with message contents.
issize_t	msg_recv_iovec (msg_t *msg, msg_iovec_t vec[], isize_t veclen, usize_t n, int exact)
	Obtain I/O vector for receiving the data.
isize_t	msg_recv_commit (msg_t *msg, usize_t n, int eos)
	Commit n bytes of buffers.
issize_t	msg_recv_buffer (msg_t msg, void *return_buffer)
	Obtain a buffer for receiving data.
msg_t *	msg_next (msg_t *msg)
	Get a next message of the stream.
int	msg_set_next (msg_t msg, msg_t next)
	Set next message of the stream.
void	msg_clear_committed (msg_t *msg)
	Clear committed data.
issize_t	msg_buf_external (msg_t *msg, usize_t N, usize_t blocksize)
	Allocate a list of external buffers.

Detailed Description

Addressing and I/O interface for messages.

Author:: Pekka Pessi <Pekka.Pessi@nokia-email.address.hidden>

Date:: Created: Thu Jun 8 19:28:55 2000 ppessi

Define Documentation

#define MSG_ADDR_H

Defined when <sofia-sip/msg_addr.h> has been included.

Typedef Documentation

typedef struct su_iovec_s msg_iovec_t

I/O vector type.

See also:: msg_recv_iovec(), msg_iovec(), su_iovec_s, su_vsend(), su_vrecv().

Enumeration Type Documentation

anonymous enum

Enumerator:

msg_min_size	Minimum size of a message buffer.
msg_min_block	Minimum size of external buffer.
msg_n_fragments	Number of external buffers.

Function Documentation

su_sockaddr_t * msg_addr ( msg_t * msg )

Get pointer to socket address structure.

Deprecated:: Use msg_get_address() or msg_set_address() instead.

void msg_addr_copy	(	msg_t *	dst,
		msg_t const *	src
	)

Copy message address.

Copy the addrinfo and socket address structures from src to the dst message object.

Parameters:

	dst	pointer to destination message object
	src	pointer to source message object

See also:: msg_addrinfo(), msg_get_address(), msg_set_address(), msg_addr_zero().

void msg_addr_zero ( msg_t * msg )

Zero the message address.

Zero the address and addressinfo structures associated with the message.

See also:: msg_addrinfo(), msg_set_address(), msg_get_address(), msg_addr_copy().

su_addrinfo_t * msg_addrinfo ( msg_t * msg )

Get addrinfo structure.

Get pointer to the addrinfo structure associated with the message.

Parameters:

msg

pointer to msg object

Return values:

	pointer	to addrinfo structure
	NULL	if msg is NULL

See also:: msg_get_address(), msg_set_address(), msg_addr_zero(), msg_addr_copy().

issize_t msg_buf_external	(	msg_t *	msg,
		usize_t	N,
		usize_t	blocksize
	)

Allocate a list of external buffers.

The function msg_buf_external() allocates at most msg_n_fragments external buffers for the message body.

Returns:: The function msg_buf_external() returns number of allocated buffers, or -1 upon an error.

int msg_errno ( msg_t const * msg )

Get error number associated with message.

Parameters:

msg

pointer to msg object

int msg_get_address	(	msg_t *	msg,
		su_sockaddr_t *	su,
		socklen_t *	return_len
	)

Get message address.

Copy the socket address associated with the message to the supplied socket address struture.

Parameters:

	msg	pointer to msg object
	su	pointer to socket address structure
	return_len	return parameter value for length of socket address structure

See also:: msg_addrinfo(), msg_set_address(), msg_addr_zero(), msg_addr_copy().

isize_t msg_iovec	(	msg_t *	msg,
		msg_iovec_t	vec[],
		isize_t	veclen
	)

Fill an I/O vector with message contents.

Calculate number of entries in the I/O vector required to send a message msg. It also fills in the I/O vector array, if it is provided by the caller and it is large enough.

Parameters:

	msg	pointer to message object
	vec	I/O vector (may be NULL)
	veclen	length of I/O vector in vec

Returns:: Number of entries of I/O vector required by msg, or 0 upon an error.

Note:: The caller should check that the I/O vector vec has enough entries. If the vec is too short, it should allocate big enough vector and re-invoke msg_iovec().

See also:: msg_recv_iovec(), su_vsend()

msg_t * msg_next ( msg_t * msg )

Get a next message of the stream.

When parsing a transport stream, only the first message in the stream is created with msg_create(). The rest of the messages should be created with msg_next() after previous message has been completely received and parsed.

isize_t msg_recv_commit	(	msg_t *	msg,
		usize_t	n,
		int	eos
	)

Commit n bytes of buffers.

The function msg_recv_commit() is called after n bytes of data has been received to the message buffers and the parser can extract the received data.

Parameters:

	msg	pointer to message object
	n	number of bytes received
	eos	true if stream is complete

Note:: The eos should be always true for message-based transports. It should also be true when a stram oin stream-based transport ends, for instance, when TCP FIN is received.

Return values:

	0	when successful
	-1	upon an error.

issize_t msg_recv_iovec	(	msg_t *	msg,
		msg_iovec_t	vec[],
		isize_t	veclen,
		usize_t	n,
		int	exact
	)

Obtain I/O vector for receiving the data.

Allocate buffers for receiving n bytes of data available from network. Function returns the buffers in the I/O vector vec. The vec is allocated by the caller, the available length is given as veclen. If the protocol is message-oriented like UDP or SCTP and the available data ends at message boundary, the caller should set the exact as 1. Otherwise some extra buffer (known as slack) is allocated).

Currently, the msg_recv_iovec() allocates receive buffers in at most two blocks, so the caller should allocate at least two elements for the I/O vector vec.

Parameters:

`[in]`	msg	message object
`[out]`	vec	I/O vector
`[in]`	veclen	available length of vec
`[in]`	n	number of possibly available bytes�
`[in]`	exact	true if data ends at message boundary

Returns:: The length of I/O vector to receive data, 0 if there are not enough buffers, or -1 upon an error.

See also:: msg_iovec(), su_vrecv()

int msg_set_address	(	msg_t *	msg,
		su_sockaddr_t const *	su,
		socklen_t	sulen
	)

Set message address.

Copy the supplied socket address to the socket address structure associated with the message.

Parameters:

	msg	pointer to msg object
	su	pointer to socket address structure
	sulen	length of socket address structure

See also:: msg_addrinfo(), msg_get_address(), msg_addr_zero(), msg_addr_copy().

void msg_set_errno	(	msg_t *	msg,
		int	err
	)

Set error number associated with message.

Parameters:

	msg	pointer to msg object
	err	error value (as defined in <sofia-sip/su_errno.h>).

sofia-sip/msg_addr.h File Reference

Defines

Typedefs

Enumerations

Functions

Detailed Description

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation