smsg.h

libosip-0.9.7源码

/*
  The oSIP library implements the Session Initiation Protocol (SIP -rfc3261-)
  Copyright (C) 2001,2002,2003  Aymeric MOIZARD [e-mail]
  
  This library is free software; you can redistribute it and/or
  modify it under the terms of the GNU Lesser General Public
  License as published by the Free Software Foundation; either
  version 2.1 of the License, or (at your option) any later version.
  
  This library 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
  Lesser General Public License for more details.
  
  You should have received a copy of the GNU Lesser General Public
  License along with this library; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
*/


#ifndef _SMSG_H_
#define _SMSG_H_

#include <osip/const.h>		/* constant definitions */
#include <osip/smsgtypes.h>	/* type     definitions */

/**
 * @file smsg.h
 * @brief oSIP parser Routines
 *
 * This is the SIP accessor and parser related API.
 * <BR>Understanding the parser implementation will prevent you from
 * using it improperly. Read this carefully.<BR>
 * <BR>This implementation could be seen as a partial implementation
 * of the whole SIP syntax. In other words, the parser is 'tolerant'
 * and will not detect a lot of error cases. As an example, no error
 * will be detected while trying to parse the following request-uri:
 * <BR><pre><code>INVITE sip:[e-mail]:abcd SIP/2.0</pre></code>
 * <BR>This code shows that even if your SIP message is parsed
 * correctly by oSIP, it may still be not compliant. This could be
 * used by attackers to make your application crash or whatever.
 * In this example, if you are trying to call the atoi() method with
 * the string 'abcd', your application will crash. Of course, there
 * exist solutions! You can check yourself for the validity of the
 * string or use the strtol() method (found on most unix) which is
 * capable of detecting such error cases.
 * <BR>Are you wondering why the parser has been built this way?
 * <BR>The initial answer is that each SIP application have
 * different requirement and some (the proxy!) needs SIP message
 * to be parsed as quickly as possible. Also, most applications
 * only need a few information from a SIP message. (the first Via
 * is the only one interesting!). If the parser was fully checking each
 * Via field validity, it would consume too much CPU on useless
 * operations. If you think this model does not fit your application,
 * then you should buy a slow stack :-).
 * <BR>Is there any plan to change that behaviour?
 * <BR>I do not need it, but if this interest you, it would be
 * possible to compile oSIP in 2 different ways: a full checker
 * model could be useful for SIP application with no performance
 * requirements. Any contributions is welcomed and will be merged
 * if it's made optional.
 */

/**
 * @defgroup oSIP_SMSG oSIP parser Handling
 * @ingroup oSIP
 * @{
 */

#ifdef __cplusplus
extern "C"
{
#endif

/**
 * Initialise the oSIP parser.
 */
  int parser_init ();

/**
 * Fix the via header for INCOMING requests only.
 * a copy of ip_addr is done.
 */
  int msg_fix_last_via_header (sip_t * request, char *ip_addr, int port);

/**
 * Allocate a sip_t element.
 * @param sip The element to allocate.
 */
  int msg_init (sip_t ** sip);
/**
 * Free all resource in a sip_t element.
 * @param sip The element to free.
 */
  void msg_free (sip_t * sip);
/**
 * Parse a sip_t element.
 * @param sip The resulting element.
 * @param message The buffer to parse.
 */
  int msg_parse (sip_t * sip, char *message);
/**
 * Get a string representation of a sip_t element.
 * @param sip The element to work on.
 * @param dest new allocated buffer returned.
 */
  int msg_2char (sip_t * sip, char **dest);
/**
 * Clone a sip_t element.
 * @param sip The element to clone.
 * @param dest The new allocated element cloned.
 */
  int msg_clone (sip_t * sip, sip_t ** dest);

/**
 * define this macro to avoid building several times
 * the message on retransmissions. If you have changed
 * the sip_t element since last call of msg_2char() you
 * can call msg_force_update() to force a rebuild.
*/
#ifdef USE_TMP_BUFFER
/**
 * Check if the element is already built. (so msg_2char won't build it again)
 * @param sip The element to check.
*/
  int msg_get_property (sip_t * sip);
#endif

/**
 * Force a sip_t element to be rebuild on next msg_2char() call.
 * @param sip The element to work on.
 */
  int msg_force_update (sip_t * sip);

/**
 * Get the usual reason phrase as defined in SIP for a specific status code.
 * @param status_code A status code.
 */
  char *msg_getreason (int status_code);
/**
 * Set the reason phrase. This is entirely free in SIP.
 * @param sip The element to work on.
 * @param reason The reason phrase.
 */
  void msg_setreasonphrase (sip_t * sip, char *reason);
/**
 * Get the reason phrase. This is entirely free in SIP.
 * @param sip The element to work on.
 */
  char *msg_getreasonphrase (sip_t * sip);
/**
 * Set the status code. This is entirely free in SIP.
 * @param sip The element to work on.
 * @param statuscode The status code.
 */
  void msg_setstatuscode (sip_t * sip, char *statuscode);
/**
 * Get the status code.
 * @param sip The element to work on.
 */
  char *msg_getstatuscode (sip_t * sip);
/**
 * Set the method. You can set any string here.
 * @param sip The element to work on.
 * @param method The method name.
 */
  void msg_setmethod (sip_t * sip, char *method);
/**
 * Get the method name.
 * @param sip The element to work on.
 */
  char *msg_getmethod (sip_t * sip);
/**
 * Set the SIP version used. (use "SIP/2.0")
 * @param sip The element to work on.
 * @param version The version of SIP.
 */
  void msg_setversion (sip_t * sip, char *version);
/**
 * Get the SIP version.
 * @param sip The element to work on.
 */
  char *msg_getversion (sip_t * sip);
/**
 * Set the Request-URI.
 * @param sip The element to work on.
 * @param uri The uri to set.
 */
  void msg_seturi (sip_t * sip, url_t * uri);
/**
 * Get the Request-URI.
 * @param sip The element to work on.
 */
  url_t *msg_geturi (sip_t * sip);

/**
 * Set the Accept header.
 * @param sip The element to work on.
 * @param hvalue The string describing the element.
 */
  int msg_setaccept (sip_t * sip, char *hvalue);
/**
 * Get one Accept header.
 * @param sip The element to work on.
 * @param pos The index of the element to get.
 * @param dest A pointer on the header found.
 */
  int msg_getaccept (sip_t * sip, int pos, accept_t ** dest);
/**
 * Set the Accept-encoding header.
 * @param sip The element to work on.
 * @param hvalue The string describing the element.
 */
  int msg_setaccept_encoding (sip_t * sip, char *hvalue);
/**
 * Get one Accept-encoding header.
 * @param sip The element to work on.
 * @param pos The index of the element to get.
 * @param dest A pointer on the header found.
 */
  int msg_getaccept_encoding (sip_t * sip, int pos,
			      accept_encoding_t ** dest);
/**
 * Set the Accept-language header.
 * @param sip The element to work on.
 * @param hvalue The string describing the element.
 */
  int msg_setaccept_language (sip_t * sip, char *hvalue);
/**
 * Get one Accept header.
 * @param sip The element to work on.
 * @param pos The index of the element to get.
 * @param dest A pointer on the header found.
 */
  int msg_getaccept_language (sip_t * sip, int pos,
			      accept_language_t ** dest);
/**
 * Set the Alert-info header.
 * @param sip The element to work on.
 * @param hvalue The string describing the element.
 */
  int msg_setalert_info (sip_t * sip, char *hvalue);
/**
 * Get one Alert-info header.
 * @param sip The element to work on.
 * @param pos The index of the element to get.
 * @param dest A pointer on the header found.
 */
  int msg_getalert_info (sip_t * sip, int pos, alert_info_t ** dest);
/**
 * Set the Allow header.
 * @param sip The element to work on.
 * @param hvalue The string describing the element.
 */
  int msg_setallow (sip_t * sip, char *hvalue);
/**
 * Get one Allow header.
 * @param sip The element to work on.
 * @param pos The index of the element to get.
 * @param dest A pointer on the header found.
 */
  int msg_getallow (sip_t * sip, int pos, allow_t ** dest);
/**
 * Set the Authorization header.
 * @param sip The element to work on.
 * @param hvalue The string describing the element.
 */
  int msg_setauthorization (sip_t * sip, char *hvalue);
/**
 * Get one Authorization header.
 * @param sip The element to work on.
 * @param pos The index of the element to get.
 * @param dest A pointer on the header found.
 */
  int msg_getauthorization (sip_t * sip, int pos, authorization_t ** dest);
/**
 * Set the Call-id header.
 * @param sip The element to work on.
 * @param hvalue The string describing the element.
 */
  int msg_setcall_id (sip_t * sip, char *hvalue);
/**
 * Get one Call-id header.
 * @param sip The element to work on.
 */
  call_id_t *msg_getcall_id (sip_t * sip);
/**
 * Set the Call-info header.
 * @param sip The element to work on.
 * @param hvalue The string describing the element.
 */
  int msg_setcall_info (sip_t * sip, char *hvalue);
/**
 * Get one Call-info header.
 * @param sip The element to work on.
 * @param pos The index of the element to get.
 * @param dest A pointer on the header found.
 */
  int msg_getcall_info (sip_t * sip, int pos, call_info_t ** dest);
/**
 * Set the Contact header.
 * @param sip The element to work on.
 * @param hvalue The string describing the element.
 */
  int msg_setcontact (sip_t * sip, char *hvalue);
/**
 * Get one Contact header.
 * @param sip The element to work on.
 * @param pos The index of the element to get.
 * @param dest A pointer on the header found.
 */
  int msg_getcontact (sip_t * sip, int pos, contact_t ** dest);
/**
 * Set the Content-disposition header.
 * @param sip The element to work on.
 * @param hvalue The string describing the element.
 */
  int msg_setcontent_disposition (sip_t * sip, char *hvalue);
/**
 * Get one Content-disposition header.
 * @param sip The element to work on.
 * @param pos The index of the element to get.
 * @param dest A pointer on the header found.
 */
  int msg_getcontent_disposition (sip_t * sip, int pos,
				  content_disposition_t ** dest);
/**
 * Set the Content-encoding header.
 * @param sip The element to work on.
 * @param hvalue The string describing the element.
 */
  int msg_setcontent_encoding (sip_t * sip, char *hvalue);
/**
 * Get one Content-encoding header.
 * @param sip The element to work on.
 * @param pos The index of the element to get.
 * @param dest A pointer on the header found.
 */
  int msg_getcontent_encoding (sip_t * sip, int pos,
			       content_encoding_t ** dest);
/**
 * Set the Content-length header.
 * @param sip The element to work on.
 * @param hvalue The string describing the element.
 */
  int msg_setcontent_length (sip_t * sip, char *hvalue);
/**
 * Get one Content-length header.
 * @param sip The element to work on.
 */
  content_length_t *msg_getcontent_length (sip_t * sip);
/**
 * Set the Content-type header.
 * @param sip The element to work on.
 * @param hvalue The string describing the element.
 */
  int msg_setcontent_type (sip_t * sip, char *hvalue);
/**
 * Get one Content-type header.
 * @param sip The element to work on.
 */
  content_type_t *msg_getcontent_type (sip_t * sip);
/**
 * Set the Cseq header.
 * @param sip The element to work on.
 * @param hvalue The string describing the element.
 */
  int msg_setcseq (sip_t * sip, char *hvalue);
/**
 * Get one Cseq header.
 * @param sip The element to work on.
 */
  cseq_t *msg_getcseq (sip_t * sip);
/**
 * Set the Error-info header.
 * @param sip The element to work on.
 * @param hvalue The string describing the element.
 */
  int msg_seterror_info (sip_t * sip, char *hvalue);
/**
 * Get one Error-info header.
 * @param sip The element to work on.
 * @param pos The index of the element to get.
 * @param dest A pointer on the header found.
 */
  int msg_geterror_info (sip_t * sip, int pos, error_info_t ** dest);
/**
 * Set the From header.
 * @param sip The element to work on.
 * @param hvalue The string describing the element.
 */
  int msg_setfrom (sip_t * sip, char *hvalue);
/**
 * Get the From header.
 * @param sip The element to work on.
 */