sip_msg.h

一个开源的sip源代码

/* $Id: sip_msg.h 1127 2007-04-02 11:44:47Z bennylp $ */
/* 
 * Copyright (C) 2003-2007 Benny Prijono <[e-mail]>
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
 */
#ifndef __PJSIP_SIP_MSG_H__
#define __PJSIP_SIP_MSG_H__

/**
 * @file pjsip/sip_msg.h
 * @brief SIP Message Structure.
 */

#include <pjsip/sip_types.h>
#include <pjsip/sip_uri.h>
#include <pj/list.h>

PJ_BEGIN_DECL

/**
 * @defgroup PJSIP_MSG Messaging Elements
 * @ingroup PJSIP_CORE
 * @brief Various SIP message elements such as methods, headers, URIs, etc.
 * @{
 */

/* **************************************************************************/
/**
 * @defgroup PJSIP_MSG_METHOD Methods
 * @brief Method names and manipulation.
 * @ingroup PJSIP_MSG
 * @{
 */

/**
 * This enumeration declares SIP methods as described by RFC3261. Additional
 * methods do exist, and they are described by corresponding RFCs for the SIP
 * extentensions. Since they won't alter the characteristic of the processing
 * of the message, they don't need to be explicitly mentioned here.
 */
typedef enum pjsip_method_e
{
    PJSIP_INVITE_METHOD,    /**< INVITE method, for establishing dialogs.   */
    PJSIP_CANCEL_METHOD,    /**< CANCEL method, for cancelling request.	    */
    PJSIP_ACK_METHOD,	    /**< ACK method.				    */
    PJSIP_BYE_METHOD,	    /**< BYE method, for terminating dialog.	    */
    PJSIP_REGISTER_METHOD,  /**< REGISTER method.			    */
    PJSIP_OPTIONS_METHOD,   /**< OPTIONS method.			    */

    PJSIP_OTHER_METHOD	    /**< Other method.				    */

} pjsip_method_e;



/**
 * This structure represents a SIP method.
 * Application must always use either #pjsip_method_init or #pjsip_method_set
 * to make sure that method name is initialized correctly. This way, the name
 * member will always contain a valid method string regardless whether the ID
 * is recognized or not.
 */
struct pjsip_method
{
    pjsip_method_e id;	    /**< Method ID, from \a pjsip_method_e. */
    pj_str_t	   name;    /**< Method name, which will always contain the 
			         method string. */
};


/*
 * For convenience, standard method structures are defined in the library.
 */
extern const pjsip_method pjsip_invite_method;	    /**< INVITE structure.  */
extern const pjsip_method pjsip_cancel_method;	    /**< CANCEL structure.  */
extern const pjsip_method pjsip_ack_method;	    /**< ACK structure.     */
extern const pjsip_method pjsip_bye_method;	    /**< BYE structure.     */
extern const pjsip_method pjsip_register_method;    /**< REGISTER structure.*/
extern const pjsip_method pjsip_options_method;	    /**< OPTIONS structure. */


/** 
 * Initialize the method structure from a string. 
 * This function will check whether the method is a known method then set
 * both the id and name accordingly.
 *
 * @param m	The method to initialize.
 * @param pool	Pool where memory allocation will be allocated from, if required.
 * @param str	The method string.
 */
PJ_DECL(void) pjsip_method_init( pjsip_method *m, 
				 pj_pool_t *pool, 
				 const pj_str_t *str);

/** 
 * Initialize the method structure from a string, without cloning the string.
 * See #pjsip_method_init.
 *
 * @param m	The method structure to be initialized.
 * @param str	The method string.
 */
PJ_DECL(void) pjsip_method_init_np( pjsip_method *m,
				    pj_str_t *str);

/** 
 * Set the method with the predefined method ID. 
 * This function will also set the name member of the structure to the correct
 * string according to the method.
 *
 * @param m	The method structure.
 * @param id	The method ID.
 */
PJ_DECL(void) pjsip_method_set( pjsip_method *m, pjsip_method_e id );


/** 
 * Copy one method structure to another. If the method is of the known methods,
 * then memory allocation is not required.
 *
 * @param pool	    Pool to allocate memory from, if required.
 * @param method    The destination method to copy to.
 * @param rhs	    The source method to copy from.
 */
PJ_DECL(void) pjsip_method_copy( pj_pool_t *pool,
				 pjsip_method *method,
				 const pjsip_method *rhs );

/** 
 * Compare one method with another, and conveniently determine whether the 
 * first method is equal, less than, or greater than the second method.
 *
 * @param m1	The first method.
 * @param m2	The second method.
 *
 * @return	Zero if equal, otherwise will return -1 if less or +1 if greater.
 */
PJ_DECL(int) pjsip_method_cmp( const pjsip_method *m1, const pjsip_method *m2);

/**
 * @}
 */

/* **************************************************************************/
/** 
 * @defgroup PJSIP_MSG_HDR Header Fields
 * @brief Declarations for various SIP header fields.
 * @ingroup PJSIP_MSG
 * @{
 */

/**
 * Header types, as defined by RFC3261.
 */
typedef enum pjsip_hdr_e
{
    /*
     * These are the headers documented in RFC3261. Headers not documented
     * there must have type PJSIP_H_OTHER, and the header type itself is 
     * recorded in the header name string.
     *
     * DO NOT CHANGE THE VALUE/ORDER OF THE HEADER IDs!!!.
     */
    PJSIP_H_ACCEPT,
    PJSIP_H_ACCEPT_ENCODING_UNIMP,	/* N/A, use pjsip_generic_string_hdr */
    PJSIP_H_ACCEPT_LANGUAGE_UNIMP,	/* N/A, use pjsip_generic_string_hdr */
    PJSIP_H_ALERT_INFO_UNIMP,		/* N/A, use pjsip_generic_string_hdr */
    PJSIP_H_ALLOW,
    PJSIP_H_AUTHENTICATION_INFO_UNIMP,	/* N/A, use pjsip_generic_string_hdr */
    PJSIP_H_AUTHORIZATION,
    PJSIP_H_CALL_ID,
    PJSIP_H_CALL_INFO_UNIMP,		/* N/A, use pjsip_generic_string_hdr */
    PJSIP_H_CONTACT,
    PJSIP_H_CONTENT_DISPOSITION_UNIMP,	/* N/A, use pjsip_generic_string_hdr */
    PJSIP_H_CONTENT_ENCODING_UNIMP,	/* N/A, use pjsip_generic_string_hdr */
    PJSIP_H_CONTENT_LANGUAGE_UNIMP,	/* N/A, use pjsip_generic_string_hdr */
    PJSIP_H_CONTENT_LENGTH,
    PJSIP_H_CONTENT_TYPE,
    PJSIP_H_CSEQ,
    PJSIP_H_DATE_UNIMP,			/* N/A, use pjsip_generic_string_hdr */
    PJSIP_H_ERROR_INFO_UNIMP,		/* N/A, use pjsip_generic_string_hdr */
    PJSIP_H_EXPIRES,
    PJSIP_H_FROM,
    PJSIP_H_IN_REPLY_TO_UNIMP,		/* N/A, use pjsip_generic_string_hdr */
    PJSIP_H_MAX_FORWARDS,
    PJSIP_H_MIME_VERSION_UNIMP,		/* N/A, use pjsip_generic_string_hdr */
    PJSIP_H_MIN_EXPIRES,
    PJSIP_H_ORGANIZATION_UNIMP,		/* N/A, use pjsip_generic_string_hdr */
    PJSIP_H_PRIORITY_UNIMP,		/* N/A, use pjsip_generic_string_hdr */
    PJSIP_H_PROXY_AUTHENTICATE,
    PJSIP_H_PROXY_AUTHORIZATION,
    PJSIP_H_PROXY_REQUIRE_UNIMP,	/* N/A, use pjsip_generic_string_hdr */
    PJSIP_H_RECORD_ROUTE,
    PJSIP_H_REPLY_TO_UNIMP,		/* N/A, use pjsip_generic_string_hdr */
    PJSIP_H_REQUIRE,
    PJSIP_H_RETRY_AFTER,
    PJSIP_H_ROUTE,
    PJSIP_H_SERVER_UNIMP,		/* N/A, use pjsip_generic_string_hdr */
    PJSIP_H_SUBJECT_UNIMP,		/* N/A, use pjsip_generic_string_hdr */
    PJSIP_H_SUPPORTED,
    PJSIP_H_TIMESTAMP_UNIMP,		/* N/A, use pjsip_generic_string_hdr */
    PJSIP_H_TO,
    PJSIP_H_UNSUPPORTED,
    PJSIP_H_USER_AGENT_UNIMP,		/* N/A, use pjsip_generic_string_hdr */
    PJSIP_H_VIA,
    PJSIP_H_WARNING_UNIMP,		/* N/A, use pjsip_generic_string_hdr */
    PJSIP_H_WWW_AUTHENTICATE,

    PJSIP_H_OTHER

} pjsip_hdr_e;

/**
 * This structure provides the pointer to basic functions that are needed
 * for generic header operations. All header fields will have pointer to
 * this structure, so that they can be manipulated uniformly.
 */
typedef struct pjsip_hdr_vptr
{
    /** 
     * Function to clone the header. 
     *
     * @param pool  Memory pool to allocate the new header.
     * @param hdr   Header to clone.
     *
     * @return A new instance of the header.
     */
    void *(*clone)(pj_pool_t *pool, const void *hdr);

    /** 
     * Pointer to function to shallow clone the header. 
     * Shallow cloning will just make a memory copy of the original header,
     * thus all pointers in original header will be kept intact. Because the
     * function does not need to perform deep copy, the operation should be
     * faster, but the application must make sure that the original header
     * is still valid throughout the lifetime of new header.
     *
     * @param pool  Memory pool to allocate the new header.
     * @param hdr   The header to clone.
     */
    void *(*shallow_clone)(pj_pool_t *pool, const void *hdr);

    /** Pointer to function to print the header to the specified buffer.
     *	Returns the length of string written, or -1 if the remaining buffer
     *	is not enough to hold the header.
     *
     *  @param hdr  The header to print.
     *  @param buf  The buffer.
     *  @param len  The size of the buffer.
     *
     *  @return	    The size copied to buffer, or -1 if there's not enough space.
     */
    int (*print_on)(void *hdr, char *buf, pj_size_t len);

} pjsip_hdr_vptr;


/**
 * Generic fields for all SIP headers are declared using this macro, to make
 * sure that all headers will have exactly the same layout in their start of
 * the storage. This behaves like C++ inheritance actually.
 */
#define PJSIP_DECL_HDR_MEMBER(hdr)   \
    /** List members. */	\
    PJ_DECL_LIST_MEMBER(hdr);	\
    /** Header type */		\
    pjsip_hdr_e	    type;	\
    /** Header name. */		\
    pj_str_t	    name;	\
    /** Header short name version. */	\
    pj_str_t	    sname;		\
    /** Virtual function table. */	\
    pjsip_hdr_vptr *vptr


/**
 * Generic SIP header structure, for generic manipulation for headers in the
 * message. All header fields can be typecasted to this type.
 */
struct pjsip_hdr
{
    PJSIP_DECL_HDR_MEMBER(struct pjsip_hdr);
};


/**
 * This generic function will clone any header, by calling "clone" function
 * in header's virtual function table.
 *
 * @param pool	    The pool to allocate memory from.
 * @param hdr	    The header to clone.
 *
 * @return	    A new instance copied from the original header.
 */
PJ_DECL(void*) pjsip_hdr_clone( pj_pool_t *pool, const void *hdr );


/**
 * This generic function will clone any header, by calling "shallow_clone" 
 * function in header's virtual function table.
 *
 * @param pool	    The pool to allocate memory from.
 * @param hdr	    The header to clone.
 *
 * @return	    A new instance copied from the original header.
 */
PJ_DECL(void*) pjsip_hdr_shallow_clone( pj_pool_t *pool, const void *hdr );

/**
 * This generic function will print any header, by calling "print" 
 * function in header's virtual function table.
 *
 * @param hdr  The header to print.
 * @param buf  The buffer.
 * @param len  The size of the buffer.
 *
 * @return	The size copied to buffer, or -1 if there's not enough space.
 */
PJ_DECL(int) pjsip_hdr_print_on( void *hdr, char *buf, pj_size_t len);

/**
 * @}
 */

/* **************************************************************************/
/**
 * @defgroup PJSIP_MSG_LINE Request and Status Line.
 * @brief Request and status line structures and manipulation.
 * @ingroup PJSIP_MSG
 * @{
 */

/**
 * This structure describes SIP request line.
 */
typedef struct pjsip_request_line 
{
    pjsip_method    method; /**< Method for this request line. */
    pjsip_uri *uri;    /**< URI for this request line. */
} pjsip_request_line;


/**
 * This structure describes SIP status line.
 */
typedef struct pjsip_status_line 
{
    int		code;	    /**< Status code. */
    pj_str_t	reason;	    /**< Reason string. */
} pjsip_status_line;


/**
 * This enumeration lists standard SIP status codes according to RFC 3261.
 * In addition, it also declares new status class 7xx for errors generated
 * by the stack. This status class however should not get transmitted on the 
 * wire.
 */
typedef enum pjsip_status_code
{
    PJSIP_SC_TRYING = 100,
    PJSIP_SC_RINGING = 180,
    PJSIP_SC_CALL_BEING_FORWARDED = 181,
    PJSIP_SC_QUEUED = 182,
    PJSIP_SC_PROGRESS = 183,

    PJSIP_SC_OK = 200,
    PJSIP_SC_ACCEPTED = 202,

    PJSIP_SC_MULTIPLE_CHOICES = 300,
    PJSIP_SC_MOVED_PERMANENTLY = 301,
    PJSIP_SC_MOVED_TEMPORARILY = 302,