msg 1.12.11devel
Loading...
Searching...
No Matches
Data Fields | Related Symbols
msg_s Class Reference

Message object. More...

#include <msg.h>

Collaboration diagram for msg_s:
Collaboration graph
[legend]

Data Fields

su_home_t m_home [1]
 Memory home.
 
msg_mclass_t const * m_class
 Message class.
 
int m_oflags
 Original flags.
 
msg_pub_tm_object
 Public view to parsed message.
 
size_t m_maxsize
 Maximum size.
 
size_t m_size
 Total size of fragments.
 
msg_header_tm_chain
 Fragment chain.
 
msg_header_t ** m_tail
 Tail of fragment chain.
 
msg_payload_tm_chunk
 Incomplete payload fragment.
 
msg_buffer_tm_stream
 User-provided buffers.
 
size_t m_ssize
 Stream size.
 
unsigned short m_extract_err
 Bitmask of erroneous headers.
 
unsigned m_set_buffer:1
 Buffer has been set.
 
unsigned m_streaming:1
 Use streaming with message.
 
unsigned m_prepared:1
 Prepared/not.
 
msg_tm_next
 Next message.
 
msg_tm_parent
 Reference to a parent message.
 
int m_refs
 Number of references to this message.
 
su_addrinfo_t m_addrinfo
 Message addressing info (protocol)
 
su_sockaddr_t m_addr [1]
 Message address.
 
int m_errno
 Errno.
 

Related Symbols

(Note that these are not member symbols.)

msg_tmsg_ref (msg_t *msg)
 Increment the reference count.
 
void msg_unref (msg_t *msg)
 Decrease the reference count.
 
msg_tmsg_create (msg_mclass_t const *mc, int flags)
 Create a message.
 
msg_tmsg_ref_create (msg_t *msg)
 Increment the reference count.
 
void msg_set_parent (msg_t *kid, msg_t *dad)
 Set a message parent.
 
void msg_ref_destroy (msg_t *ref)
 Destroy a reference to a message.
 
void msg_destroy (msg_t *msg)
 Destroy a reference to a message.
 
msg_pub_tmsg_public (msg_t const *msg, void *tag)
 Retrieve public message structure of given type.
 
msg_mclass_t const * msg_mclass (msg_t const *msg)
 Retrieve message class.
 
void msg_addr_zero (msg_t *msg)
 Zero the message address.
 
su_sockaddr_t * msg_addr (msg_t *msg)
 Get pointer to socket address structure.
 
int msg_get_address (msg_t *msg, su_sockaddr_t *su, socklen_t *return_len)
 Get message address.
 
int msg_set_address (msg_t *msg, su_sockaddr_t const *su, socklen_t sulen)
 Set message address.
 
su_addrinfo_tmsg_addrinfo (msg_t *msg)
 Get addrinfo structure.
 
void msg_addr_copy (msg_t *dst, msg_t const *src)
 Copy message address.
 
unsigned msg_extract_errors (msg_t const *msg)
 Get error classification flags.
 
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.
 
msg_tmsg_copy (msg_t *original)
 Copy a message shallowly.
 
msg_tmsg_dup (msg_t const *original)
 Deep copy a message.
 
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.
 
issize_t msg_recv_buffer (msg_t *msg, void **return_buffer)
 Obtain a buffer for receiving data.
 
isize_t msg_recv_commit (msg_t *msg, usize_t n, int eos)
 Commit n bytes of buffers.
 
msg_tmsg_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.
 
unsigned msg_mark_as_complete (msg_t *msg, unsigned mask)
 Mark message as complete.
 
int msg_is_complete (msg_t const *msg)
 Return true if message is complete.
 
int msg_has_error (msg_t const *msg)
 Return true if message has parsing errors.
 
usize_t msg_size (msg_t const *msg)
 Total size of message.
 
usize_t msg_maxsize (msg_t *msg, usize_t maxsize)
 Set the maximum size of a message.
 
int msg_streaming_size (msg_t *msg, usize_t ssize)
 Set the size of next fragment.
 
issize_t msg_buf_external (msg_t *msg, usize_t N, usize_t blocksize)
 Allocate a list of external buffers.
 
int msg_extract (msg_t *msg)
 Extract and parse a message from internal buffer.
 
int msg_prepare (msg_t *msg)
 Encode all message fragments.
 
int msg_serialize (msg_t *msg, msg_pub_t *pub)
 Serialize headers into the fragment chain.
 
isize_t msg_iovec (msg_t *msg, msg_iovec_t vec[], isize_t veclen)
 Fill an I/O vector with message contents.
 

Detailed Description

Message object.

The message object is used by Sofia parsers for SIP and HTTP protocols. The message object has an abstract, protocol-independent inteface type msg_t, and a separate public protocol-specific interface msg_pub_t (which is typedef'ed to sip_t or http_t depending on the protocol).

The main interface to abstract messages is defined in <sofia-sip/msg.h>. The network I/O interface used by transport protocols is defined in <sofia-sip/msg_addr.h>. The protocol-specific parser table, also known as message class, is defined in <sofia-sip/msg_mclass.h>. (The message class is used as a factory object when a message object is created with msg_create()).

Friends And Related Symbol Documentation

◆ msg_addr()

su_sockaddr_t * msg_addr ( msg_t msg)
related

Get pointer to socket address structure.

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

◆ msg_addr_copy()

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

Copy message address.

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

Parameters
dstpointer to destination message object
srcpointer to source message object
See also
msg_addrinfo(), msg_get_address(), msg_set_address(), msg_addr_zero().

◆ msg_addr_zero()

void msg_addr_zero ( msg_t msg)
related

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().

◆ msg_addrinfo()

su_addrinfo_t * msg_addrinfo ( msg_t msg)
related

Get addrinfo structure.

Get pointer to the addrinfo structure associated with the message.

Parameters
msgpointer to msg object
Return values
pointerto addrinfo structure
NULLif msg is NULL
See also
msg_get_address(), msg_set_address(), msg_addr_zero(), msg_addr_copy().

◆ msg_buf_external()

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

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.

◆ msg_copy()

msg_t * msg_copy ( msg_t original)
related

Copy a message shallowly.

Copy a message and the header structures. The copied message will share all the strings with the original message. It will keep a reference to the original message, and the original message is not destroyed until all the copies have been destroyed.

Parameters
originalmessage to be copied
Return values
pointerto newly copied message object when successful
NULLupon an error

◆ msg_create()

msg_t * msg_create ( msg_mclass_t const *  mc,
int  flags 
)
related

Create a message.

Parameters
mcmessage class
flagsmessage control flags

◆ msg_destroy()

void msg_destroy ( msg_t msg)
related

Destroy a reference to a message.

Parameters
msgmessage to be destroyed

◆ msg_dup()

msg_t * msg_dup ( msg_t const *  original)
related

Deep copy a message.

Copy a message, the header structures and all the related strings. The duplicated message does not share any (non-const) data with original. Note that the cached representation (in h_data) is not copied.

Parameters
originalmessage to be duplicated
Return values
pointerto newly duplicated message object when successful
NULLupon an error

◆ msg_errno()

int msg_errno ( msg_t const *  msg)
related

Get error number associated with message.

Parameters
msgpointer to msg object

◆ msg_extract()

int msg_extract ( msg_t msg)
related

Extract and parse a message from internal buffer.

This function parses the internal buffer and adds the parsed fragments to the message object. It marks the successfully parsed data as extracted.

Parameters
msgmessage to be parsed
Return values
positiveif a complete message was parsed
0if message was incomplete
negativeif an error occurred

◆ msg_extract_errors()

unsigned msg_extract_errors ( msg_t const *  msg)
related

Get error classification flags.

If the message parser fails to parse certain headers in the message, it sets the corresponding extract error flags. The flags corresponding to each header are stored in the message parser (msg_mclass_t) structure. They are set when the header is added to the parser table.

The SIP flags are defined in <sofia-sip/sip_headers.h>. For well-known SIP headers, the flags for each header are listed in a separate text file (sip_bad_mask) read by msg_parser.awk.

The flags can be used directly by NTA (the mask triggering 400 response is set with NTATAG_BAD_REQ_MASK(), the mask triggering response messages to be dropped is set with NTATAG_BAD_RESP_MASK()). Alternatively the application can check them based on the method or required SIP features.

See also
msg_mclass_insert_with_mask(), NTATAG_BAD_REQ_MASK(), NTATAG_BAD_RESP_MASK().

◆ msg_get_address()

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

Get message address.

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

Parameters
msgpointer to msg object
supointer to socket address structure
return_lenreturn parameter value for length of socket address structure
See also
msg_addrinfo(), msg_set_address(), msg_addr_zero(), msg_addr_copy().

◆ msg_iovec()

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

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
msgpointer to message object
vecI/O vector (may be NULL)
veclenlength 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_maxsize()

usize_t msg_maxsize ( msg_t msg,
usize_t  maxsize 
)
related

Set the maximum size of a message.

The function msg_maxsize() sets the maximum buffer size of a message. It returns the previous maximum size. If the maxsize is 0, maximum size is not set, but the current maximum size is returned.

If the message size exceeds maxsize, msg_errno() returns ENOBUFS, MSG_FLG_TOOLARGE and MSG_FLG_ERROR flags are set.

◆ msg_mclass()

msg_mclass_t const * msg_mclass ( msg_t const *  msg)
related

Retrieve message class.

Get a pointer to the message class object (factory object for the message).

Parameters
msgpointer to msg object
Returns
A pointer to the message class, or NULL if none.

◆ msg_next()

msg_t * msg_next ( msg_t msg)
related

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.

◆ msg_prepare()

int msg_prepare ( msg_t msg)
related

Encode all message fragments.

The function msg_prepare() prepares a message for sending. It encodes all serialized fragments in the message. You have to call msg_serialize() before calling msg_headers_prepare() in order to make sure that all the heades and other message fragments are included in the chain.

After encoding, the msg_common_s::h_data field will point to the encoding result of size msg_common_s::h_len bytes in in each fragment.

When multiple header fields are represented as a comma-separated list within a single header line, the first fragment in the header will contain all the text belonging to the header. The rest of the header fields will have zero-length encoding with msg_common_s::h_data that points to the end of the line.

Returns
Total size of the encoded message in bytes, or -1 upon an error.
See also
msg_extract(), msg_serialize()

◆ msg_public()

msg_pub_t * msg_public ( msg_t const *  msg,
void *  tag 
)
related

Retrieve public message structure of given type.

Get a pointer to the public message structure of the given protocol.

Parameters
msgpointer to msg object
tagtag of public message structure
Returns
A pointer to the public message structure, or NULL if there is none or the message is not for desired protocol.

◆ msg_recv_commit()

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

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
msgpointer to message object
nnumber of bytes received
eostrue 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
0when successful
-1upon an error.

◆ msg_recv_iovec()

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

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]msgmessage object
[out]vecI/O vector
[in]veclenavailable length of vec
[in]nnumber of possibly available bytes 
[in]exacttrue 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()

◆ msg_ref()

msg_t * msg_ref ( msg_t msg)
related

Increment the reference count.

Increases the reference count of a message. The message is not freed until all the references have been destroyed.

Parameters
msgmessage of which a reference is created
Returns
A pointer to a message

◆ msg_ref_create()

msg_t * msg_ref_create ( msg_t msg)
related

Increment the reference count.

Increases the reference count of a message. The message is not freed until all the references have been destroyed.

Parameters
msgmessage of which a reference is created
Returns
A pointer to a message

◆ msg_ref_destroy()

void msg_ref_destroy ( msg_t ref)
related

Destroy a reference to a message.

Parameters
refpointer to msg object
Deprecated:
Use msg_destroy() instead.

◆ msg_serialize()

int msg_serialize ( msg_t msg,
msg_pub_t pub 
)
related

Serialize headers into the fragment chain.

The msg_serialize() collects the headers and other message components in the fragment chain. It should be called before msg_prepare().

Parameters
msgpointer to message object
pubpublic message structure
Return values
0when successful
-1upon an error

◆ msg_set_address()

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

Set message address.

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

Parameters
msgpointer to msg object
supointer to socket address structure
sulenlength of socket address structure
See also
msg_addrinfo(), msg_get_address(), msg_addr_zero(), msg_addr_copy().

◆ msg_set_errno()

void msg_set_errno ( msg_t msg,
int  err 
)
related

Set error number associated with message.

Parameters
msgpointer to msg object
errerror value (as defined in <sofia-sip/su_errno.h>).

◆ msg_set_parent()

void msg_set_parent ( msg_t kid,
msg_t dad 
)
related

Set a message parent.

Set a parent for a message. The parent message is not destroyed until all its kids have been destroyed - each kid keeps a reference to its parent message.

Parameters
kidchild message
dadparent message

◆ msg_streaming_size()

int msg_streaming_size ( msg_t msg,
usize_t  ssize 
)
related

Set the size of next fragment.

The function msg_streaming_size() sets the size of the message body for streaming.

◆ msg_unref()

void msg_unref ( msg_t msg)
related

Decrease the reference count.

Decreases the reference count of a message. The message is freed if the reference count reaches zero.

Parameters
msgmessage of which a reference is created
Returns
A pointer to a message

Sofia-SIP 1.12.11devel - Copyright (C) 2006 Nokia Corporation. All rights reserved. Licensed under the terms of the GNU Lesser General Public License.