sip_msg.h

一个开源的sip源代码

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

/** 
 * Add a header to the message, putting it last in the header list.
 *
 * @param msg	    The message.
 * @param 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.
 */
PJ_INLINE(void) pjsip_msg_add_hdr( pjsip_msg *msg, pjsip_hdr *hdr )
{
    pj_list_insert_before(&msg->hdr, hdr);
}

/** 
 * Add header field to the message, putting it in the front of the header list.
 *
 * @param msg	The message.
 * @param 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.
 */
PJ_INLINE(void) pjsip_msg_insert_first_hdr( pjsip_msg *msg, pjsip_hdr *hdr )
{
    pj_list_insert_after(&msg->hdr, hdr);
}

/** 
 * Print the message to the specified buffer. 
 *
 * @param msg	The message to print.
 * @param buf	The buffer
 * @param size	The size of the buffer.
 *
 * @return	The length of the printed characters (in bytes), or NEGATIVE
 *		value if the message is too large for the specified buffer.
 */
PJ_DECL(pj_ssize_t) pjsip_msg_print(const pjsip_msg *msg, 
				    char *buf, pj_size_t size);


/*
 * Some usefull macros to find common headers.
 */


/**
 * Find Call-ID header.
 *
 * @param msg	The message.
 * @return	Call-ID header instance.
 */
#define PJSIP_MSG_CID_HDR(msg) \
	    ((pjsip_cid_hdr*)pjsip_msg_find_hdr(msg, PJSIP_H_CALL_ID, NULL))

/**
 * Find CSeq header.
 *
 * @param msg	The message.
 * @return	CSeq header instance.
 */
#define PJSIP_MSG_CSEQ_HDR(msg) \
	    ((pjsip_cseq_hdr*)pjsip_msg_find_hdr(msg, PJSIP_H_CSEQ, NULL))

/**
 * Find From header.
 *
 * @param msg	The message.
 * @return	From header instance.
 */
#define PJSIP_MSG_FROM_HDR(msg) \
	    ((pjsip_from_hdr*)pjsip_msg_find_hdr(msg, PJSIP_H_FROM, NULL))

/**
 * Find To header.
 *
 * @param msg	The message.
 * @return	To header instance.
 */
#define PJSIP_MSG_TO_HDR(msg) \
	    ((pjsip_to_hdr*)pjsip_msg_find_hdr(msg, PJSIP_H_TO, NULL))


/**
 * @}
 */

/* **************************************************************************/
/**
 * @addtogroup PJSIP_MSG_HDR
 * @{
 */

/**
 * Generic SIP header, which contains hname and a string hvalue.
 * Note that this header is not supposed to be used as 'base' class for headers.
 */
typedef struct pjsip_generic_string_hdr
{
    /** Standard header field. */
    PJSIP_DECL_HDR_MEMBER(struct pjsip_generic_string_hdr);
    /** hvalue */
    pj_str_t hvalue;
} pjsip_generic_string_hdr;


/**
 * Create a new instance of generic header. A generic header can have an
 * arbitrary header name.
 *
 * @param pool	    The pool.
 * @param hname	    The header name to be assigned to the header, or NULL to
 *		    assign the header name with some string.
 * @param hvalue    Optional string to be assigned as the value.
 *
 * @return	    The header, or THROW exception.
 */
PJ_DECL(pjsip_generic_string_hdr*) 
pjsip_generic_string_hdr_create( pj_pool_t *pool, 
				 const pj_str_t *hname,
				 const pj_str_t *hvalue);


/**
 * Initialize a preallocated memory with the header structure. This function
 * should only be called when application uses its own memory allocation to
 * allocate memory block for the specified header (e.g. in C++, when the 
 * header is allocated with "new" operator).
 * For normal applications, they should use pjsip_xxx_hdr_create() instead,
 * which allocates memory and initialize it in one go.
 *
 * @param pool	    Pool for additional memory allocation if required.
 * @param mem	    Pre-allocated memory to be initialized as the header.
 * @param hname	    The header name to be assigned to the header, or NULL to
 *		    assign the header name with some string later.
 * @param hvalue    Optional string to be assigned as the value.
 *
 * @return	    The header instance, which points to the same memory 
 *		    location as the mem argument.
 */
PJ_DECL(pjsip_generic_string_hdr*) 
pjsip_generic_string_hdr_init( pj_pool_t *pool,
			       void *mem,
			       const pj_str_t *hname,
			       const pj_str_t *hvalue);


/**
 * Construct a generic string header without allocating memory from the pool.
 * This function is useful to create a temporary header which life-time is
 * very short (for example, creating the header in the stack to be passed
 * as argument to a function which will copy the header).
 *
 * @param h	    The header to be initialized.
 * @param hname	    The header name to be assigned to the header, or NULL to
 *		    assign the header name with some string.
 * @param hvalue    Optional string to be assigned as the value.
 *
 * @return	    The header, or THROW exception.
 */
PJ_DECL(void) pjsip_generic_string_hdr_init2(pjsip_generic_string_hdr *h,
					     pj_str_t *hname,
					     pj_str_t *hvalue);


/* **************************************************************************/

/**
 * Generic SIP header, which contains hname and a string hvalue.
 */
typedef struct pjsip_generic_int_hdr
{
    PJSIP_DECL_HDR_MEMBER(struct pjsip_generic_int_hdr); /**< Standard header field. */
    pj_int32_t ivalue;				    /**< ivalue */
} pjsip_generic_int_hdr;


/**
 * Create a new instance of generic header. A generic header can have an
 * arbitrary header name.
 *
 * @param pool	    The pool.
 * @param hname	    The header name to be assigned to the header, or NULL to
 *		    assign the header name with some string.
 * @param hvalue    The value to be assigned to the header.
 *
 * @return	    The header, or THROW exception.
 */
PJ_DECL(pjsip_generic_int_hdr*) pjsip_generic_int_hdr_create( pj_pool_t *pool,
						      const pj_str_t *hname,
						      int hvalue );


/**
 * Initialize a preallocated memory with the header structure. This function
 * should only be called when application uses its own memory allocation to
 * allocate memory block for the specified header (e.g. in C++, when the 
 * header is allocated with "new" operator).
 * For normal applications, they should use pjsip_xxx_hdr_create() instead,
 * which allocates memory and initialize it in one go.
 *
 * @param pool	    Pool for additional memory allocation if required.
 * @param mem	    Pre-allocated memory to be initialized as the header.
 * @param hname	    The header name to be assigned to the header, or NULL to
 *		    assign the header name with some string later.
 * @param value	    Value to be assigned to the header.
 *
 * @return	    The header instance, which points to the same memory 
 *		    location as the mem argument.
 */
PJ_DECL(pjsip_generic_int_hdr*) pjsip_generic_int_hdr_init( pj_pool_t *pool,
							    void *mem,
							    const pj_str_t *hname,
							    int value );

/* **************************************************************************/

/** Maximum elements in the header array. */
#define PJSIP_GENERIC_ARRAY_MAX_COUNT	32

/**
 * Generic array of string header.
 */
typedef struct pjsip_generic_array_hdr
{
    /** Standard header fields. */
    PJSIP_DECL_HDR_MEMBER(struct pjsip_generic_array_hdr);

    /** Number of tags/elements. */
    unsigned	count;

    /**< Tags/elements. */
    pj_str_t	values[PJSIP_GENERIC_ARRAY_MAX_COUNT];

} pjsip_generic_array_hdr;

/**
 * Create generic array header.
 *
 * @param pool	    Pool to allocate memory from.
 * @param hname	    Header name.
 *
 * @return	    New generic array header.
 */
PJ_DECL(pjsip_generic_array_hdr*) pjsip_generic_array_hdr_create(pj_pool_t *pool,
							     const pj_str_t *hname);

/**
 * Initialize a preallocated memory with the header structure. This function
 * should only be called when application uses its own memory allocation to
 * allocate memory block for the specified header (e.g. in C++, when the 
 * header is allocated with "new" operator).
 * For normal applications, they should use pjsip_xxx_hdr_create() instead,
 * which allocates memory and initialize it in one go.
 *
 * @param pool	    Pool for additional memory allocation if required.
 * @param mem	    Pre-allocated memory to be initialized as the header.
 * @param hname	    The header name to be assigned to the header, or NULL to
 *		    assign the header name with some string later.
 *
 * @return	    The header instance, which points to the same memory 
 *		    location as the mem argument.
 */
PJ_DECL(pjsip_generic_array_hdr*) pjsip_generic_array_hdr_init(pj_pool_t *pool,
							       void *mem,
							       const pj_str_t *hname);


/* **************************************************************************/

/** Accept header. */
typedef pjsip_generic_array_hdr pjsip_accept_hdr;

/** Maximum fields in Accept header. */
#define PJSIP_MAX_ACCEPT_COUNT	PJSIP_GENERIC_ARRAY_MAX_COUNT

/**
 * Create new Accept header instance.
 *
 * @param pool	    The pool.
 *
 * @return	    New Accept header instance.
 */
PJ_DECL(pjsip_accept_hdr*) pjsip_accept_hdr_create(pj_pool_t *pool);

/**
 * Initialize a preallocated memory with the header structure. This function
 * should only be called when application uses its own memory allocation to
 * allocate memory block for the specified header (e.g. in C++, when the 
 * header is allocated with "new" operator).
 * For normal applications, they should use pjsip_xxx_hdr_create() instead,
 * which allocates memory and initialize it in one go.
 *
 * @param pool	    Pool for additional memory allocation if required.
 * @param mem	    Pre-allocated memory to be initialized as the header.
 *
 * @return	    The header instance, which points to the same memory 
 *		    location as the mem argument.
 */
PJ_DECL(pjsip_accept_hdr*) pjsip_accept_hdr_init( pj_pool_t *pool,
						  void *mem );


/* **************************************************************************/

/**
 * Allow header.
 */
typedef pjsip_generic_array_hdr pjsip_allow_hdr;

/**
 * Create new Allow header instance.
 *
 * @param pool	    The pool.
 *
 * @return	    New Allow header instance.
 */
PJ_DECL(pjsip_allow_hdr*) pjsip_allow_hdr_create(pj_pool_t *pool);



/**
 * Initialize a preallocated memory with the header structure. This function
 * should only be called when application uses its own memory allocation to
 * allocate memory block for the specified header (e.g. in C++, when the 
 * header is allocated with "new" operator).
 * For normal applications, they should use pjsip_xxx_hdr_create() instead,
 * which allocates memory and initialize it in one go.
 *
 * @param pool	    Pool for additional memory allocation if required.
 * @param mem	    Pre-allocated memory to be initialized as the header.
 *
 * @return	    The header instance, which points to the same memory 
 *		    location as the mem argument.
 */
PJ_DECL(pjsip_allow_hdr*) pjsip_allow_hdr_init( pj_pool_t *pool,
						void *mem );

/* **************************************************************************/

/**
 * Call-ID header.
 */
typedef struct pjsip_cid_hdr
{
    PJSIP_DECL_HDR_MEMBER(struct pjsip_cid_hdr);
    pj_str_t id;	    /**< Call-ID string. */
} pjsip_cid_hdr;


/**
 * Create new Call-ID header.
 *
 * @param pool	The pool.
 *
 * @return	new Call-ID header.
 */
PJ_DECL(pjsip_cid_hdr*) pjsip_cid_hdr_create( pj_pool_t *pool );


/**
 * Initialize a preallocated memory with the header structure. This function
 * should only be called when application uses its own memory allocation to
 * allocate memory block for the specified header (e.g. in C++, when the 
 * header is allocated with "new" operator).
 * For normal applications, they should use pjsip_xxx_hdr_create() instead,
 * which allocates memory and initialize it in one go.
 *
 * @param pool	    Pool for additional memory allocation if required.
 * @param mem	    Pre-allocated memory to be initialized as the header.
 *
 * @return	    The header instance, which points to the same memory 
 *		    location as the mem argument.
 */
PJ_DECL(pjsip_cid_hdr*) pjsip_cid_hdr_init( pj_pool_t *pool,
					    void *mem );



/* **************************************************************************/