Base message interface. More...
#include <sofia-sip/msg_types.h>#include <sofia-sip/su_alloc.h>
Go to the source code of this file.
Defines | |
| #define | MSG_H |
| Defined when <sofia-sip/msg.h> has been included. | |
| #define | msg_home(h) |
| Cast a msg_t pointer to a su_home_t pointer. | |
| #define | MSG_FLAGS(f, v) |
| Test if all the flags in v are set in f. | |
Enumerations | |
| enum | msg_streaming_status { msg_stop_streaming, msg_start_streaming } |
Streaming state of a msg_t object. More... | |
| enum | msg_flg_user { MSG_FLG_COMPACT, MSG_FLG_CANONIC, MSG_FLG_EXTRACT_COPY, MSG_FLG_COMMA_LISTS, MSG_FLG_MAILBOX, MSG_FLG_CHUNKING, MSG_FLG_STREAMING, MSG_FLG_THRDSAFE } |
Flags controlling parser/printer. More... | |
| enum | msg_flg_parser { MSG_FLG_HEADERS, MSG_FLG_BODY, MSG_FLG_CHUNKS, MSG_FLG_TRAILERS, MSG_FLG_FRAGS, MSG_FLG_COMPLETE, MSG_FLG_ERROR, MSG_FLG_TOOLARGE, MSG_FLG_TRUNC, MSG_FLG_TIMEOUT } |
Flags used by parser. More... | |
Functions | |
| msg_t * | msg_create (msg_mclass_t const *mc, int flags) |
| Create a message. | |
| void | msg_destroy (msg_t *) |
| Deinitialize and free a message. | |
| msg_t * | msg_copy (msg_t *) |
| Copy a message shallowly. | |
| msg_t * | msg_dup (msg_t const *) |
| Deep copy a message. | |
| msg_t * | msg_make (msg_mclass_t const *mc, int flags, void const *data, ssize_t len) |
| Parse a message. | |
| char * | msg_as_string (su_home_t *home, msg_t *msg, msg_pub_t *pub, int flags, size_t *return_len) |
| Convert a message to a string. | |
| void | msg_set_parent (msg_t *kid, msg_t *dad) |
| Set a message parent. | |
| msg_t * | msg_ref_create (msg_t *) |
| Increment a message reference count. | |
| void | msg_ref_destroy (msg_t *) |
| Destroy a reference to a message. | |
| msg_pub_t * | msg_public (msg_t const *msg, void *tag) |
| Retrieve public message structure of given type. | |
| msg_pub_t * | msg_object (msg_t const *msg) |
| Retrieve public message structure. | |
| msg_mclass_t const * | msg_mclass (msg_t const *msg) |
| Retrieve message class. | |
| int | msg_extract (msg_t *msg) |
| Extract and parse a message from internal buffer. | |
| unsigned | msg_extract_errors (msg_t const *msg) |
| Get error classification flags. | |
| 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. | |
| msg_header_t ** | msg_chain_head (msg_t const *msg) |
| Return head of the fragment chain. | |
| int | msg_serialize (msg_t *msg, msg_pub_t *mo) |
| Serialize headers into the fragment chain. | |
| int | msg_prepare (msg_t *msg) |
| Encode all message fragments. | |
| void | msg_unprepare (msg_t *msg) |
| Clear 'prepared' flag. | |
| int | msg_is_prepared (msg_t const *msg) |
| Return true if message is prepared. | |
| 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_is_streaming (msg_t const *msg) |
| Test if streaming is in progress. | |
| void | msg_set_streaming (msg_t *msg, enum msg_streaming_status what) |
| Enable/disable streaming. | |
| unsigned | msg_mark_as_complete (msg_t *msg, unsigned mask) |
| Mark message as complete. | |
| unsigned | msg_get_flags (msg_t const *msg, unsigned mask) |
| Get message flags. | |
| unsigned | msg_set_flags (msg_t *msg, unsigned mask) |
| Set message flags. | |
| unsigned | msg_zap_flags (msg_t *msg, unsigned mask) |
| Clear message flags. | |
Base message interface.
| #define MSG_FLAGS | ( | f, | ||
| v | ||||
| ) |
Test if all the flags in v are set in f.
| enum msg_flg_parser |
Flags used by parser.
| enum msg_flg_user |
Flags controlling parser/printer.
| enum msg_streaming_status |
Streaming state of a msg_t object.
| char* msg_as_string | ( | su_home_t * | home, | |
| msg_t * | msg, | |||
| msg_pub_t * | pub, | |||
| int | flags, | |||
| size_t * | return_len | |||
| ) |
Convert a message to a string.
A message is encoded and the encoding result is returned as a string. Because the message may contain binary payload (or NUL in headers), the message length is returned separately in *return_len, too.
Note that the message is serialized as a side effect.
| home | memory home used to allocate the string | |
| msg | message to encode | |
| pub | message object to encode (may be NULL) | |
| flags | flags used when encoding | |
| return_len | return-value parameter for encoded message length |
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 | |||
| ) |
Create a message.
| mc | message class | |
| flags | message control flags |
| void msg_destroy | ( | msg_t * | msg | ) |
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_extract | ( | msg_t * | msg | ) |
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 | ) |
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.
| unsigned msg_get_flags | ( | msg_t const * | msg, | |
| unsigned | mask | |||
| ) |
Get message flags.
| int msg_is_prepared | ( | msg_t const * | msg | ) |
Return true if message is prepared.
| int msg_is_streaming | ( | msg_t const * | msg | ) |
Test if streaming is in progress.
| msg_t* msg_make | ( | msg_mclass_t const * | mc, | |
| int | flags, | |||
| void const * | data, | |||
| ssize_t | len | |||
| ) |
Parse a message.
Parse a text message with parser mc. The data is copied and it is not modified or referenced by the parsed message.
msg_t *m = msg_make(sip_default_mclass(), 0, pl->pl_data, pl->pl_len); sip_t *frag = sip_object(m);
| mc | message class (parser table) | |
| flags | message flags (see msg_flg_user) | |
| data | message text | |
| len | size of message text (if -1, use strlen(data)) |
| A | pointer to a freshly allocated and parsed message. |
Upon parsing error, the header structure may be left incomplete. The MSG_FLG_ERROR is set in msg_object(msg)->msg_flags.
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 | ) |
Retrieve message class.
Get a pointer to the message class object (factory object for the message).
| msg | pointer to msg object |
Retrieve public message structure.
Get a pointer to the public message structure.
| msg | pointer to msg object |
| int msg_prepare | ( | msg_t * | msg | ) |
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 |
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 | ) |
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 |
| unsigned msg_set_flags | ( | msg_t * | msg, | |
| unsigned | mask | |||
| ) |
Set message flags.
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 |
| void msg_unprepare | ( | msg_t * | msg | ) |
Clear 'prepared' flag.
| unsigned msg_zap_flags | ( | msg_t * | msg, | |
| unsigned | mask | |||
| ) |
Clear message flags.