Group PJSIP_MSG_BODY

group PJSIP_MSG_BODY

SIP message body structures and manipulation.

Functions

int pjsip_print_text_body(pjsip_msg_body *msg_body, char *buf, pj_size_t size)

General purpose function to textual data in a SIP body. Attach this function in a SIP message body only if the data in pjsip_msg_body is a textual message ready to be embedded in a SIP message. If the data in the message body is not a textual body, then application must supply a custom function to print that body.

Parameters:

  • msg_body – The message body.

  • buf – Buffer to copy the message body to.

  • size – The size of the buffer.

Returns:

The length copied to the buffer, or -1.

void *pjsip_clone_text_data(pj_pool_t *pool, const void *data, unsigned len)

General purpose function to clone textual data in a SIP body. Attach this function as “clone_data” member of the SIP body only if the data type is a text (i.e. C string, not pj_str_t), and the length indicates the length of the text.

Parameters:

  • pool – Pool used to clone the data.

  • data – Textual data.

  • len – The length of the string.

Returns:

New text duplicated from the original text.

pj_status_t pjsip_msg_body_copy(pj_pool_t *pool, pjsip_msg_body *dst_body, const pjsip_msg_body *src_body)

Clone the message body in src_body to the dst_body. This will duplicate the contents of the message body using the clone_data member of the source message body.

Parameters:

  • pool – Pool to use to duplicate the message body.

  • dst_body – Destination message body.

  • src_body – Source message body to duplicate.

Returns:

PJ_SUCCESS on success.

pjsip_msg_body *pjsip_msg_body_clone(pj_pool_t *pool, const pjsip_msg_body *body)

Create cloned message body. This will duplicate the contents of the message body using the clone_data member of the source message body.

Parameters:

  • pool – Pool to use to duplicate the message body.

  • body – Source message body to duplicate.

Returns:

The cloned message body on successfull.

pjsip_msg_body *pjsip_msg_body_create(pj_pool_t *pool, const pj_str_t *type, const pj_str_t *subtype, const pj_str_t *text)

Create a text message body. Use this function to create message body when the content is a simple text. For non-text message body (e.g. pjmedia_sdp_session or pj_xml_node), application must construct the message manually.

Parameters:

  • pool – Pool to allocate message body and its contents.

  • type – MIME type (e.g. “text”).

  • subtype – MIME subtype (e.g. “plain”).

  • text – The text content to be put in the message body.

Returns:

A new message body with the specified Content-Type and text.

struct pjsip_msg_body
#include <sip_msg.h>

Generic abstraction to message body. When an incoming message is parsed (pjsip_parse_msg()), the parser fills in all members with the appropriate value. The ‘data’ and ‘len’ member will describe portion of incoming packet which denotes the message body. When application needs to attach message body to outgoing SIP message, it must fill in all members of this structure.

Forward declaration for message body (sip_msg.h).

Public Members

pjsip_media_type content_type

MIME content type. For incoming messages, the parser will fill in this member with the content type found in Content-Type header.

For outgoing messages, application may fill in this member with appropriate value, because the stack will generate Content-Type header based on the value specified here.

If the content_type is empty, no Content-Type AND Content-Length header will be added to the message. The stack assumes that application adds these headers themselves.

void *data

Pointer to buffer which holds the message body data. For incoming messages, the parser will fill in this member with the pointer to the body string.

When sending outgoing message, this member doesn’t need to point to the actual message body string. It can be assigned with arbitrary pointer, because the value will only need to be understood by the print_body() function. The stack itself will not try to interpret this value, but instead will always call the print_body() whenever it needs to get the actual body string.

unsigned len

The length of the data. For incoming messages, the parser will fill in this member with the actual length of message body.

When sending outgoing message, again just like the “data” member, the “len” member doesn’t need to point to the actual length of the body string.

int (*print_body)(struct pjsip_msg_body *msg_body, char *buf, pj_size_t size)

Pointer to function to print this message body. Application must set a proper function here when sending outgoing message.

Param msg_body:

This structure itself.

Param buf:

The buffer.

Param size:

The buffer size.

Return:

The length of the string printed, or -1 if there is not enough space in the buffer to print the whole message body.

void *(*clone_data)(pj_pool_t *pool, const void *data, unsigned len)

Clone the data part only of this message body. Note that this only duplicates the data part of the body instead of the whole message body. If application wants to duplicate the entire message body structure, it must call pjsip_msg_body_clone().

Param pool:

Pool used to clone the data.

Param data:

The data inside message body, to be cloned.

Param len:

The length of the data.

Return:

New data duplicated from the original data.