Message Structure
[Messaging Elements]

SIP message (request and response) structure and operations.

Data Structures
struct	pjsip_msg
Defines
#define	PJSIP_MSG_CID_HDR(msg)   ((pjsip_cid_hdr*)pjsip_msg_find_hdr(msg, PJSIP_H_CALL_ID, NULL))
#define	PJSIP_MSG_CSEQ_HDR(msg)   ((pjsip_cseq_hdr*)pjsip_msg_find_hdr(msg, PJSIP_H_CSEQ, NULL))
#define	PJSIP_MSG_FROM_HDR(msg)   ((pjsip_from_hdr*)pjsip_msg_find_hdr(msg, PJSIP_H_FROM, NULL))
#define	PJSIP_MSG_TO_HDR(msg)   ((pjsip_to_hdr*)pjsip_msg_find_hdr(msg, PJSIP_H_TO, NULL))
Enumerations
enum	pjsip_msg_type_e { PJSIP_REQUEST_MSG, PJSIP_RESPONSE_MSG }
Functions
pjsip_msg *	pjsip_msg_create (pj_pool_t *pool, pjsip_msg_type_e type)
pjsip_msg *	pjsip_msg_clone (pj_pool_t *pool, const pjsip_msg *msg)
void *	pjsip_msg_find_hdr (const pjsip_msg *msg, pjsip_hdr_e type, const void *start)
void *	pjsip_msg_find_hdr_by_name (const pjsip_msg *msg, const pj_str_t *name, const void *start)
void *	pjsip_msg_find_hdr_by_names (const pjsip_msg *msg, const pj_str_t *name, const pj_str_t *sname, const void *start)
void *	pjsip_msg_find_remove_hdr (pjsip_msg *msg, pjsip_hdr_e hdr, void *start)
void	pjsip_msg_add_hdr (pjsip_msg *msg, pjsip_hdr *hdr)
void	pjsip_msg_insert_first_hdr (pjsip_msg *msg, pjsip_hdr *hdr)
pj_ssize_t	pjsip_msg_print (const pjsip_msg *msg, char *buf, pj_size_t size)

---

Define Documentation

#define PJSIP_MSG_CID_HDR

(

msg

)

((pjsip_cid_hdr*)pjsip_msg_find_hdr(msg, PJSIP_H_CALL_ID, NULL))

Find Call-ID header.

Parameters:

msg

The message.

Returns:

Call-ID header instance.

#define PJSIP_MSG_CSEQ_HDR

(

msg

)

((pjsip_cseq_hdr*)pjsip_msg_find_hdr(msg, PJSIP_H_CSEQ, NULL))

Find CSeq header.

Parameters:

msg

The message.

Returns:

CSeq header instance.

#define PJSIP_MSG_FROM_HDR

(

msg

)

((pjsip_from_hdr*)pjsip_msg_find_hdr(msg, PJSIP_H_FROM, NULL))

Find From header.

Parameters:

msg

The message.

Returns:

From header instance.

#define PJSIP_MSG_TO_HDR

(

msg

)

((pjsip_to_hdr*)pjsip_msg_find_hdr(msg, PJSIP_H_TO, NULL))

Find To header.

Parameters:

msg

The message.

Returns:

To header instance.

---

Enumeration Type Documentation

enum pjsip_msg_type_e

Message type (request or response).

Enumerator:

PJSIP_REQUEST_MSG	Indicates request message.
PJSIP_RESPONSE_MSG	Indicates response message.

---

Function Documentation

pjsip_msg* pjsip_msg_create	(	pj_pool_t *	pool,
		pjsip_msg_type_e	type
	)

Create new request or response message.

Parameters:

	pool	The pool.
	type	Message type.

Returns:

New message, or THROW exception if failed.

pjsip_msg* pjsip_msg_clone	(	pj_pool_t *	pool,
		const pjsip_msg *	msg
	)

Perform a deep clone of a SIP message.

Parameters:

	pool	The pool for creating the new message.
	msg	The message to be duplicated.

Returns:

New message, which is duplicated from the original message.

void* pjsip_msg_find_hdr	(	const pjsip_msg *	msg,
		pjsip_hdr_e	type,
		const void *	start
	)

Find a header in the message by the header type.

Parameters:

	msg	The message.
	type	The header type to find.
	start	The first header field where the search should begin. If NULL is specified, then the search will begin from the first header, otherwise the search will begin at the specified header.

Returns:

The header field, or NULL if no header with the specified type is found.

void* pjsip_msg_find_hdr_by_name	(	const pjsip_msg *	msg,
		const pj_str_t *	name,
		const void *	start
	)

Find a header in the message by its name.

Parameters:

	msg	The message.
	name	The header name to find.
	start	The first header field where the search should begin. If NULL is specified, then the search will begin from the first header, otherwise the search will begin at the specified header.

Returns:

The header field, or NULL if no header with the specified type is found.

void* pjsip_msg_find_hdr_by_names	(	const pjsip_msg *	msg,
		const pj_str_t *	name,
		const pj_str_t *	sname,
		const void *	start
	)

Find a header in the message by its name and short name version.

Parameters:

	msg	The message.
	name	The header name to find.
	sname	The short name version of the header name.
	start	The first header field where the search should begin. If NULL is specified, then the search will begin from the first header, otherwise the search will begin at the specified header.

Returns:

The header field, or NULL if no header with the specified type is found.

void* pjsip_msg_find_remove_hdr	(	pjsip_msg *	msg,
		pjsip_hdr_e	hdr,
		void *	start
	)

Find and remove a header in the message.

Parameters:

	msg	The message.
	hdr	The header type to find.
	start	The first header field where the search should begin, or NULL to search from the first header in the message.

Returns:

The header field, or NULL if not found.

void pjsip_msg_add_hdr	(	pjsip_msg *	msg,
		pjsip_hdr *	hdr
	)

Add a header to the message, putting it last in the header list.

Parameters:

	msg	The message.
	hdr	The header to add.

Bug:

Once the header is put in a list (or message), it can not be put in other list (or message). Otherwise Real Bad Thing will happen.

References pj_list_insert_before().

void pjsip_msg_insert_first_hdr	(	pjsip_msg *	msg,
		pjsip_hdr *	hdr
	)

Add header field to the message, putting it in the front of the header list.

Parameters:

	msg	The message.
	hdr	The header to add.

Bug:

Once the header is put in a list (or message), it can not be put in other list (or message). Otherwise Real Bad Thing will happen.

References PJ_INLINE, and pj_list_insert_after().

pj_ssize_t pjsip_msg_print	(	const pjsip_msg *	msg,
		char *	buf,
		pj_size_t	size
	)

Print the message to the specified buffer.

Parameters:

	msg	The message to print.
	buf	The buffer
	size	The size of the buffer.

Returns:

The length of the printed characters (in bytes), or NEGATIVE value if the message is too large for the specified buffer.