Message object. More...
#include <msg.h>
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_t * | m_object |
| Public view to parsed message. | |
| size_t | m_maxsize |
| Maximum size. | |
| size_t | m_size |
| Total size of fragments. | |
| msg_header_t * | m_chain |
| Fragment chain. | |
| msg_header_t ** | m_tail |
| Tail of fragment chain. | |
| msg_payload_t * | m_chunk |
| Incomplete payload fragment. | |
| msg_buffer_t * | m_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_t * | m_next |
| Next message. | |
| msg_t * | m_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 Functions | |
(Note that these are not member functions.) | |
| msg_t * | msg_create (msg_mclass_t const *mc, int flags) |
| Create a message. | |
| msg_t * | msg_ref_create (msg_t *msg) |
| Increment a message 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) |
| Deinitialize and free a message. | |
| msg_pub_t * | msg_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_t * | msg_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_t * | msg_copy (msg_t *original) |
| Copy a message shallowly. | |
| msg_t * | msg_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_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. | |
| 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. | |
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()).
| su_sockaddr_t * msg_addr | ( | msg_t * | msg | ) | [related] |
Get pointer to socket address structure.
Copy message address.
Copy the addrinfo and socket address structures from src to the dst message object.
| dst | pointer to destination message object | |
| src | pointer to source message object |
| void msg_addr_zero | ( | msg_t * | msg | ) | [related] |
Zero the message address.
Zero the address and addressinfo structures associated with the message.
| su_addrinfo_t * msg_addrinfo | ( | msg_t * | msg | ) | [related] |
Get addrinfo structure.
Get pointer to the addrinfo structure associated with the message.
| msg | pointer to msg object |
| pointer | to addrinfo structure | |
| NULL | if msg is NULL |
Allocate a list of external buffers.
The function msg_buf_external() allocates at most msg_n_fragments external buffers for the message body.
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.
| original | message to be copied |
| pointer | to newly copied message object when successful | |
| NULL | upon an error |
| msg_t * msg_create | ( | msg_mclass_t const * | mc, | |
| int | flags | |||
| ) | [related] |
Create a message.
| mc | message class | |
| flags | message control flags |
| void msg_destroy | ( | msg_t * | msg | ) | [related] |
Deinitialize and free a message.
| msg | message to be destroyed |
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.
| original | message to be duplicated |
| pointer | to newly duplicated message object when successful | |
| NULL | upon an error |
| int msg_errno | ( | msg_t const * | msg | ) | [related] |
Get error number associated with message.
| msg | pointer to msg object |
| 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.
| msg | message to be parsed |
| positive | if a complete message was parsed | |
| 0 | if message was incomplete | |
| negative | if an error occurred |
| 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.
| 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.
| msg | pointer to msg object | |
| su | pointer to socket address structure | |
| return_len | return parameter value for length of socket address structure |
| 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.
| msg | pointer to message object | |
| vec | I/O vector (may be NULL) | |
| veclen | length of I/O vector in vec |
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_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).
| msg | pointer to msg object |
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.
| 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.
Retrieve public message structure of given type.
Get a pointer to the public message structure of the given protocol.
| msg | pointer to msg object | |
| tag | tag of public message structure |
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.
| msg | pointer to message object | |
| n | number of bytes received | |
| eos | true if stream is complete |
| 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 | |||
| ) | [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.
| [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 |
Increment a message reference count.
Creates a reference to a message. The referenced message is not freed until all the references have been destroyed.
| msg | message of which a reference is created |
| void msg_ref_destroy | ( | msg_t * | ref | ) | [related] |
Destroy a reference to a message.
| ref | pointer to msg object |
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().
| msg | pointer to message object | |
| pub | public message structure |
| 0 | when successful | |
| -1 | upon an error |
| 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.
| msg | pointer to msg object | |
| su | pointer to socket address structure | |
| sulen | length of socket address structure |
| void msg_set_errno | ( | msg_t * | msg, | |
| int | err | |||
| ) | [related] |
Set error number associated with message.
| msg | pointer to msg object | |
| err | error value (as defined in <sofia-sip/su_errno.h>). |
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.
| kid | child message | |
| dad | parent message |
Set the size of next fragment.
The function msg_streaming_size() sets the size of the message body for streaming.
