sdp.h

一个开源SIP协议栈

/* $Id: sdp.h 974 2007-02-19 01:13:53Z 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 __PJMEDIA_SDP_H__
#define __PJMEDIA_SDP_H__

/**
 * @file sdp.h
 * @brief SDP header file.
 */
#include <pjmedia/types.h>


/**
 * @defgroup PJMEDIA_SDP SDP Parsing and Data Structure
 * @ingroup PJMEDIA_SESSION
 * @{
 *
 * The basic SDP session descriptor and elements are described in header
 * file <b><pjmedia/sdp.h></b>. This file contains declaration for
 * SDP session descriptor and SDP media descriptor, along with their
 * attributes. This file also declares functions to parse SDP message.
 */


PJ_BEGIN_DECL

/**
 * The PJMEDIA_MAX_SDP_FMT macro defines maximum format in a media line.
 */
#ifndef PJMEDIA_MAX_SDP_FMT
#   define PJMEDIA_MAX_SDP_FMT		32
#endif

/**
 * The PJMEDIA_MAX_SDP_ATTR macro defines maximum SDP attributes in media and
 * session descriptor.
 */
#ifndef PJMEDIA_MAX_SDP_ATTR
#   define PJMEDIA_MAX_SDP_ATTR		(PJMEDIA_MAX_SDP_FMT*2 + 4)
#endif

/**
 * The PJMEDIA_MAX_SDP_MEDIA macro defines maximum SDP media lines in a
 * SDP session descriptor.
 */
#ifndef PJMEDIA_MAX_SDP_MEDIA
#   define PJMEDIA_MAX_SDP_MEDIA	16
#endif


/* **************************************************************************
 * SDP ATTRIBUTES
 ***************************************************************************
 */

/** 
 * Generic representation of attribute.
 */
struct pjmedia_sdp_attr
{
    pj_str_t		name;	    /**< Attribute name.    */
    pj_str_t		value;	    /**< Attribute value.   */
};

/**
 * @see pjmedia_sdp_attr
 */
typedef struct pjmedia_sdp_attr pjmedia_sdp_attr;


/**
 * Create SDP attribute.
 *
 * @param pool		Pool to create the attribute.
 * @param name		Attribute name.
 * @param value		Optional attribute value.
 *
 * @return		The new SDP attribute.
 */
PJ_DECL(pjmedia_sdp_attr*) pjmedia_sdp_attr_create(pj_pool_t *pool,
						   const char *name,
						   const pj_str_t *value);

/** 
 * Clone attribute 
 *
 * @param pool		Pool to be used.
 * @param attr		The attribute to clone.
 *
 * @return		New attribute as cloned from the attribute.
 */
PJ_DECL(pjmedia_sdp_attr*) pjmedia_sdp_attr_clone(pj_pool_t *pool, 
						  const pjmedia_sdp_attr*attr);

/** 
 * Find the first attribute with the specified type.
 *
 * @param count		Number of attributes in the array.
 * @param attr_array	Array of attributes.
 * @param name		Attribute name to find.
 * @param fmt		Optional string to indicate which payload format
 *			to find for \a rtpmap and \a fmt attributes. For other
 *			types of attributes, the value should be NULL.
 *
 * @return		The specified attribute, or NULL if it can't be found.
 *
 * @see pjmedia_sdp_attr_find2, pjmedia_sdp_media_find_attr, 
 *	pjmedia_sdp_media_find_attr2
 */
PJ_DECL(pjmedia_sdp_attr*) 
pjmedia_sdp_attr_find(unsigned count, 
		      pjmedia_sdp_attr *const attr_array[],
		      const pj_str_t *name, const pj_str_t *fmt);

/** 
 * Find the first attribute with the specified type.
 *
 * @param count		Number of attributes in the array.
 * @param attr_array	Array of attributes.
 * @param name		Attribute name to find.
 * @param fmt		Optional string to indicate which payload format
 *			to find for \a rtpmap and \a fmt attributes. For other
 *			types of attributes, the value should be NULL.
 *
 * @return		The specified attribute, or NULL if it can't be found.
 *
 * @see pjmedia_sdp_attr_find, pjmedia_sdp_media_find_attr,
 *	pjmedia_sdp_media_find_attr2
 */
PJ_DECL(pjmedia_sdp_attr*) 
pjmedia_sdp_attr_find2(unsigned count, 
		       pjmedia_sdp_attr *const attr_array[],
		       const char *name, const pj_str_t *fmt);

/**
 * Add a new attribute to array of attributes.
 *
 * @param count		Number of attributes in the array.
 * @param attr_array	Array of attributes.
 * @param attr		The attribute to add.
 *
 * @return		PJ_SUCCESS or the error code.
 *
 * @see pjmedia_sdp_media_add_attr
 */
PJ_DECL(pj_status_t) pjmedia_sdp_attr_add(unsigned *count,
					  pjmedia_sdp_attr *attr_array[],
					  pjmedia_sdp_attr *attr);

/**
 * Remove all attributes with the specified name in array of attributes.
 *
 * @param count		Number of attributes in the array.
 * @param attr_array	Array of attributes.
 * @param name		Attribute name to find.
 *
 * @return		Number of attributes removed.
 *
 * @see pjmedia_sdp_media_remove_all_attr
 */
PJ_DECL(unsigned) pjmedia_sdp_attr_remove_all(unsigned *count,
					      pjmedia_sdp_attr *attr_array[],
					      const char *name);


/**
 * Remove the specified attribute from the attribute array.
 *
 * @param count		Number of attributes in the array.
 * @param attr_array	Array of attributes.
 * @param attr		The attribute instance to remove.
 *
 * @return		PJ_SUCCESS when attribute has been removed, or 
 *			PJ_ENOTFOUND when the attribute can not be found.
 *
 * @see pjmedia_sdp_media_remove_attr
 */
PJ_DECL(pj_status_t) pjmedia_sdp_attr_remove(unsigned *count,
					     pjmedia_sdp_attr *attr_array[],
					     pjmedia_sdp_attr *attr);


/**
 * This structure declares SDP \a rtpmap attribute.
 */
struct pjmedia_sdp_rtpmap
{
    pj_str_t		pt;	    /**< Payload type.	    */
    pj_str_t		enc_name;   /**< Encoding name.	    */
    unsigned		clock_rate; /**< Clock rate.	    */
    pj_str_t		param;	    /**< Parameter.	    */
};

/**
 * @see pjmedia_sdp_rtpmap
 */
typedef struct pjmedia_sdp_rtpmap pjmedia_sdp_rtpmap;


/**
 * Convert generic attribute to SDP \a rtpmap. This function allocates
 * a new attribute and call #pjmedia_sdp_attr_get_rtpmap().
 *
 * @param pool		Pool used to create the rtpmap attribute.
 * @param attr		Generic attribute to be converted to rtpmap, which
 *			name must be "rtpmap".
 * @param p_rtpmap	Pointer to receive SDP rtpmap attribute.
 *
 * @return		PJ_SUCCESS if the attribute can be successfully
 *			converted to \a rtpmap type.
 *
 * @see pjmedia_sdp_attr_get_rtpmap
 */
PJ_DECL(pj_status_t) pjmedia_sdp_attr_to_rtpmap(pj_pool_t *pool,
						const pjmedia_sdp_attr *attr,
						pjmedia_sdp_rtpmap **p_rtpmap);


/**
 * Get the rtpmap representation of the same SDP attribute.
 *
 * @param attr		Generic attribute to be converted to rtpmap, which
 *			name must be "rtpmap".
 * @param rtpmap	SDP \a rtpmap attribute to be initialized.
 *
 * @return		PJ_SUCCESS if the attribute can be successfully
 *			converted to \a rtpmap attribute.
 *
 * @see pjmedia_sdp_attr_to_rtpmap
 */
PJ_DECL(pj_status_t) pjmedia_sdp_attr_get_rtpmap(const pjmedia_sdp_attr *attr,
						 pjmedia_sdp_rtpmap *rtpmap);


/**
 * Convert \a rtpmap attribute to generic attribute.
 *
 * @param pool		Pool to be used.
 * @param rtpmap	The \a rtpmap attribute.
 * @param p_attr	Pointer to receive the generic SDP attribute.
 *
 * @return		PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t) 
pjmedia_sdp_rtpmap_to_attr( pj_pool_t *pool,
			    const pjmedia_sdp_rtpmap *rtpmap,
			    pjmedia_sdp_attr **p_attr);


/**
 * This structure describes SDP \a fmtp attribute.
 */
struct pjmedia_sdp_fmtp
{
    pj_str_t		fmt;	    /**< Format type.		    */
    pj_str_t		fmt_param;  /**< Format specific parameter. */
};


/**
 * @see pjmedia_sdp_fmtp
 */
typedef struct pjmedia_sdp_fmtp pjmedia_sdp_fmtp;



/**
 * Get the fmtp representation of the same SDP attribute.
 *
 * @param attr		Generic attribute to be converted to fmtp, which
 *			name must be "fmtp".
 * @param fmtp		SDP fmtp attribute to be initialized.
 *
 * @return		PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t) pjmedia_sdp_attr_get_fmtp(const pjmedia_sdp_attr *attr,
					       pjmedia_sdp_fmtp *fmtp);


/**
 * This structure describes SDP \a rtcp attribute.
 */
typedef struct pjmedia_sdp_rtcp_attr
{
    unsigned	port;	    /**< RTCP port number.	    */
    pj_str_t	net_type;   /**< Optional network type.	    */
    pj_str_t	addr_type;  /**< Optional address type.	    */
    pj_str_t	addr;	    /**< Optional address.	    */
} pjmedia_sdp_rtcp_attr;


/**
 * Parse a generic SDP attribute to get SDP rtcp attribute values.
 *
 * @param attr		Generic attribute to be converted to rtcp, which
 *			name must be "rtcp".
 * @param rtcp		SDP rtcp attribute to be initialized.