sip_msg.h

一个开源的sip源代码

    PJSIP_SC_USE_PROXY = 305,
    PJSIP_SC_ALTERNATIVE_SERVICE = 380,

    PJSIP_SC_BAD_REQUEST = 400,
    PJSIP_SC_UNAUTHORIZED = 401,
    PJSIP_SC_PAYMENT_REQUIRED = 402,
    PJSIP_SC_FORBIDDEN = 403,
    PJSIP_SC_NOT_FOUND = 404,
    PJSIP_SC_METHOD_NOT_ALLOWED = 405,
    PJSIP_SC_NOT_ACCEPTABLE = 406,
    PJSIP_SC_PROXY_AUTHENTICATION_REQUIRED = 407,
    PJSIP_SC_REQUEST_TIMEOUT = 408,
    PJSIP_SC_GONE = 410,
    PJSIP_SC_REQUEST_ENTITY_TOO_LARGE = 413,
    PJSIP_SC_REQUEST_URI_TOO_LONG = 414,
    PJSIP_SC_UNSUPPORTED_MEDIA_TYPE = 415,
    PJSIP_SC_UNSUPPORTED_URI_SCHEME = 416,
    PJSIP_SC_BAD_EXTENSION = 420,
    PJSIP_SC_EXTENSION_REQUIRED = 421,
    PJSIP_SC_SESSION_TIMER_TOO_SMALL = 422,
    PJSIP_SC_INTERVAL_TOO_BRIEF = 423,
    PJSIP_SC_TEMPORARILY_UNAVAILABLE = 480,
    PJSIP_SC_CALL_TSX_DOES_NOT_EXIST = 481,
    PJSIP_SC_LOOP_DETECTED = 482,
    PJSIP_SC_TOO_MANY_HOPS = 483,
    PJSIP_SC_ADDRESS_INCOMPLETE = 484,
    PJSIP_AC_AMBIGUOUS = 485,
    PJSIP_SC_BUSY_HERE = 486,
    PJSIP_SC_REQUEST_TERMINATED = 487,
    PJSIP_SC_NOT_ACCEPTABLE_HERE = 488,
    PJSIP_SC_BAD_EVENT = 489,
    PJSIP_SC_REQUEST_UPDATED = 490,
    PJSIP_SC_REQUEST_PENDING = 491,
    PJSIP_SC_UNDECIPHERABLE = 493,

    PJSIP_SC_INTERNAL_SERVER_ERROR = 500,
    PJSIP_SC_NOT_IMPLEMENTED = 501,
    PJSIP_SC_BAD_GATEWAY = 502,
    PJSIP_SC_SERVICE_UNAVAILABLE = 503,
    PJSIP_SC_SERVER_TIMEOUT = 504,
    PJSIP_SC_VERSION_NOT_SUPPORTED = 505,
    PJSIP_SC_MESSAGE_TOO_LARGE = 513,
    PJSIP_SC_PRECONDITION_FAILURE = 580,

    PJSIP_SC_BUSY_EVERYWHERE = 600,
    PJSIP_SC_DECLINE = 603,
    PJSIP_SC_DOES_NOT_EXIST_ANYWHERE = 604,
    PJSIP_SC_NOT_ACCEPTABLE_ANYWHERE = 606,

    PJSIP_SC_TSX_TIMEOUT = PJSIP_SC_REQUEST_TIMEOUT,
    /*PJSIP_SC_TSX_RESOLVE_ERROR = 702,*/
    PJSIP_SC_TSX_TRANSPORT_ERROR = PJSIP_SC_SERVICE_UNAVAILABLE

} pjsip_status_code;

/**
 * Get the default status text for the status code.
 *
 * @param status_code	    SIP Status Code
 *
 * @return		    textual message for the status code.
 */ 
PJ_DECL(const pj_str_t*) pjsip_get_status_text(int status_code);

/**
 * This macro returns non-zero (TRUE) if the specified status_code is
 * in the same class as the code_class.
 *
 * @param status_code	The status code.
 * @param code_class	The status code in the class (for example 100, 200).
 */
#define PJSIP_IS_STATUS_IN_CLASS(status_code, code_class)    \
	    (status_code/100 == code_class/100)

/**
 * @}
 */

/* **************************************************************************/
/**
 * @addtogroup PJSIP_MSG_MEDIA Media/MIME Type
 * @brief Media/MIME type declaration and manipulations.
 * @ingroup PJSIP_MSG
 * @{
 */

/**
 * This structure describes SIP media type, as used for example in 
 * Accept and Content-Type header..
 */
typedef struct pjsip_media_type
{
    pj_str_t type;	    /**< Media type. */
    pj_str_t subtype;	    /**< Media subtype. */
    pj_str_t param;	    /**< Media type parameters (concatenated). */
} pjsip_media_type;

/**
 * @}
 */

/* **************************************************************************/
/**
 * @addtogroup PJSIP_MSG_BODY Message Body
 * @brief SIP message body structures and manipulation.
 * @ingroup PJSIP_MSG
 * @{
 */

/**
 * 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. 
 */
struct pjsip_msg_body
{
    /** 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.
     */
    pjsip_media_type content_type;

    /** 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.
     */
    void *data;

    /** 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.
     */
    unsigned len;

    /** 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.
     */
    int (*print_body)(struct pjsip_msg_body *msg_body, 
		      char *buf, pj_size_t size);

    /** 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.
     */
    void* (*clone_data)(pj_pool_t *pool, const void *data, unsigned len);

};

/**
 * 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.
 *
 * @param msg_body	The message body.
 * @param buf		Buffer to copy the message body to.
 * @param size		The size of the buffer.
 *
 * @return		The length copied to the buffer, or -1.
 */
PJ_DECL(int) pjsip_print_text_body( pjsip_msg_body *msg_body, 
				    char *buf, pj_size_t size);

/**
 * 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.
 *
 *  @param pool		Pool used to clone the data.
 *  @param data		Textual data.
 *  @param len		The length of the string.
 *
 *  @return		New text duplicated from the original text.
 */
PJ_DECL(void*) pjsip_clone_text_data( pj_pool_t *pool, const void *data,
				      unsigned len);


/**
 * Clone the message body in src_body to the dst_body. This will duplicate
 * the contents of the message body using the \a clone_data member of the
 * source message body.
 *
 * @param pool		Pool to use to duplicate the message body.
 * @param dst_body	Destination message body.
 * @param src_body	Source message body to duplicate.
 *
 * @return		PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t) pjsip_msg_body_copy( pj_pool_t *pool,
					  pjsip_msg_body *dst_body,
					  const pjsip_msg_body *src_body );
					   

/**
 * Create cloned message body. This will duplicate the contents of the message
 * body using the \a clone_data member of the source message body.
 *
 * @param pool		Pool to use to duplicate the message body.
 * @param body		Source message body to duplicate.
 *
 * @return		The cloned message body on successfull.
 */
PJ_DECL(pjsip_msg_body*) pjsip_msg_body_clone( pj_pool_t *pool,
					       const pjsip_msg_body *body );
					   

/**
 * 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.
 *
 * @param pool		Pool to allocate message body and its contents.
 * @param type		MIME type (e.g. "text").
 * @param subtype	MIME subtype (e.g. "plain").
 * @param text		The text content to be put in the message body.
 *
 * @return		A new message body with the specified Content-Type and
 *			text.
 */
PJ_DECL(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 );

/**
 * @}
 */

/* **************************************************************************/
/**
 * @defgroup PJSIP_MSG_MSG Message Structure
 * @brief SIP message (request and response) structure and operations.
 * @ingroup PJSIP_MSG
 * @{
 */

/**
 * Message type (request or response).
 */
typedef enum pjsip_msg_type_e
{
    PJSIP_REQUEST_MSG,	    /**< Indicates request message. */
    PJSIP_RESPONSE_MSG	    /**< Indicates response message. */
} pjsip_msg_type_e;


/**
 * This structure describes a SIP message.
 */
struct pjsip_msg
{
    /** Message type (ie request or response). */
    pjsip_msg_type_e  type;

    /** The first line of the message can be either request line for request
     *	messages, or status line for response messages. It is represented here
     *  as a union.
     */
    union
    {
	/** Request Line. */
	struct pjsip_request_line   req;

	/** Status Line. */
	struct pjsip_status_line    status;
    } line;

    /** List of message headers. */
    pjsip_hdr hdr;

    /** Pointer to message body, or NULL if no message body is attached to
     *	this mesage. 
     */
    pjsip_msg_body *body;
};


/** 
 * Create new request or response message.
 *
 * @param pool	    The pool.
 * @param type	    Message type.
 * @return	    New message, or THROW exception if failed.
 */
PJ_DECL(pjsip_msg*)  pjsip_msg_create( pj_pool_t *pool, pjsip_msg_type_e type);


/**
 * Perform a deep clone of a SIP message.
 *
 * @param pool	    The pool for creating the new message.
 * @param msg	    The message to be duplicated.
 *
 * @return	    New message, which is duplicated from the original 
 *		    message.
 */
PJ_DECL(pjsip_msg*) pjsip_msg_clone( pj_pool_t *pool, const pjsip_msg *msg);


/** 
 * Find a header in the message by the header type.
 *
 * @param msg	    The message.
 * @param type	    The header type to find.
 * @param 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.
 *
 * @return	    The header field, or NULL if no header with the specified 
 *		    type is found.
 */
PJ_DECL(void*)  pjsip_msg_find_hdr( const pjsip_msg *msg, 
				    pjsip_hdr_e type, const void *start);

/** 
 * Find a header in the message by its name.
 *
 * @param msg	    The message.
 * @param name	    The header name to find.
 * @param 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.
 *
 * @return	    The header field, or NULL if no header with the specified 
 *		    type is found.
 */
PJ_DECL(void*)  pjsip_msg_find_hdr_by_name( const pjsip_msg *msg, 
					    const pj_str_t *name, 
					    const void *start);

/** 
 * Find and remove a header in the message. 
 *
 * @param msg	    The message.
 * @param hdr	    The header type to find.
 * @param start	    The first header field where the search should begin,
 *		    or NULL to search from the first header in the message.
 *
 * @return	    The header field, or NULL if not found.
 */