codec.h

一个开源SIP协议栈

			   struct pjmedia_frame *output);
} pjmedia_codec_op;



/*
 * Forward declaration for pjmedia_codec_factory.
 */
typedef struct pjmedia_codec_factory pjmedia_codec_factory;


/**
 * This structure describes a codec instance. 
 */
struct pjmedia_codec
{
    /** Entries to put this codec instance in codec factory's list. */
    PJ_DECL_LIST_MEMBER(struct pjmedia_codec);

    /** Codec's private data. */
    void		    *codec_data;

    /** Codec factory where this codec was allocated. */
    pjmedia_codec_factory   *factory;

    /** Operations to codec. */
    pjmedia_codec_op	    *op;
};



/**
 * This structure describes operations that must be supported by codec 
 * factories.
 */
typedef struct pjmedia_codec_factory_op
{
    /** 
     * Check whether the factory can create codec with the specified 
     * codec info.
     *
     * @param factory	The codec factory.
     * @param info	The codec info.
     *
     * @return		PJ_SUCCESS if this factory is able to create an
     *			instance of codec with the specified info.
     */
    pj_status_t	(*test_alloc)(pjmedia_codec_factory *factory, 
			      const pjmedia_codec_info *info );

    /** 
     * Create default attributes for the specified codec ID. This function
     * can be called by application to get the capability of the codec.
     *
     * @param factory	The codec factory.
     * @param info	The codec info.
     * @param attr	The attribute to be initialized.
     *
     * @return		PJ_SUCCESS if success.
     */
    pj_status_t (*default_attr)(pjmedia_codec_factory *factory, 
    				const pjmedia_codec_info *info,
    				pjmedia_codec_param *attr );

    /** 
     * Enumerate supported codecs that can be created using this factory.
     * 
     *  @param factory	The codec factory.
     *  @param count	On input, specifies the number of elements in
     *			the array. On output, the value will be set to
     *			the number of elements that have been initialized
     *			by this function.
     *  @param info	The codec info array, which contents will be 
     *			initialized upon return.
     *
     *  @return		PJ_SUCCESS on success.
     */
    pj_status_t (*enum_info)(pjmedia_codec_factory *factory, 
			     unsigned *count, 
			     pjmedia_codec_info codecs[]);

    /** 
     * Create one instance of the codec with the specified codec info.
     *
     * @param factory	The codec factory.
     * @param info	The codec info.
     * @param p_codec	Pointer to receive the codec instance.
     *
     * @return		PJ_SUCCESS on success.
     */
    pj_status_t (*alloc_codec)(pjmedia_codec_factory *factory, 
			       const pjmedia_codec_info *info,
			       pjmedia_codec **p_codec);

    /** 
     * This function is called by codec manager to return a particular 
     * instance of codec back to the codec factory.
     *
     * @param factory	The codec factory.
     * @param codec	The codec instance to be returned.
     *
     * @return		PJ_SUCCESS on success.
     */
    pj_status_t (*dealloc_codec)(pjmedia_codec_factory *factory, 
				 pjmedia_codec *codec );

} pjmedia_codec_factory_op;



/**
 * Codec factory describes a module that is able to create codec with specific
 * capabilities. These capabilities can be queried by codec manager to create
 * instances of codec.
 */
struct pjmedia_codec_factory
{
    /** Entries to put this structure in the codec manager list. */
    PJ_DECL_LIST_MEMBER(struct pjmedia_codec_factory);

    /** The factory's private data. */
    void		     *factory_data;

    /** Operations to the factory. */
    pjmedia_codec_factory_op *op;

};


/**
 * Declare maximum codecs
 */
#define PJMEDIA_CODEC_MGR_MAX_CODECS	    32


/**
 * Specify these values to set the codec priority, by calling
 * #pjmedia_codec_mgr_set_codec_priority().
 */
typedef enum pjmedia_codec_priority
{
    /**
     * This priority makes the codec the highest in the order.
     * The last codec specified with this priority will get the
     * highest place in the order, and will change the priority
     * of previously highest priority codec to NEXT_HIGHER.
     */
    PJMEDIA_CODEC_PRIO_HIGHEST = 255,

    /**
     * This priority will put the codec as the next codec after
     * codecs with this same priority.
     */
    PJMEDIA_CODEC_PRIO_NEXT_HIGHER = 254,

    /**
     * This is the initial codec priority when it is registered to
     * codec manager by codec factory.
     */
    PJMEDIA_CODEC_PRIO_NORMAL = 128,

    /**
     * This priority makes the codec the lowest in the order.
     * The last codec specified with this priority will be put
     * in the last place in the order.
     */
    PJMEDIA_CODEC_PRIO_LOWEST = 1,

    /**
     * This priority will prevent the codec from being listed in the
     * SDP created by media endpoint, thus should prevent the codec
     * from being used in the sessions. However, the codec will still
     * be listed by #pjmedia_codec_mgr_enum_codecs() and other codec
     * query functions.
     */
    PJMEDIA_CODEC_PRIO_DISABLED = 0

} pjmedia_codec_priority;


/** 
 * Codec identification (e.g. "pcmu/8000/1").
 * See @ref codec_ident for more info.
 */
typedef char pjmedia_codec_id[32];


/** 
 * Codec manager maintains array of these structs for each supported
 * codec.
 */
struct pjmedia_codec_desc
{
    pjmedia_codec_info	    info;	/**< Codec info.	    */
    pjmedia_codec_id	    id;		/**< Fully qualified name   */
    pjmedia_codec_priority  prio;	/**< Priority.		    */
    pjmedia_codec_factory  *factory;	/**< The factory.	    */
};


/**
 * The declaration for codec manager. Application doesn't normally need
 * to see this declaration, but nevertheless this declaration is needed
 * by media endpoint to instantiate the codec manager.
 */
typedef struct pjmedia_codec_mgr
{
    /** List of codec factories registered to codec manager. */
    pjmedia_codec_factory	factory_list;

    /** Number of supported codesc. */
    unsigned			codec_cnt;

    /** Array of codec descriptor. */
    struct pjmedia_codec_desc	codec_desc[PJMEDIA_CODEC_MGR_MAX_CODECS];

} pjmedia_codec_mgr;



/**
 * Initialize codec manager. Normally this function is called by pjmedia
 * endpoint's initialization code.
 *
 * @param mgr	    Codec manager instance.
 *
 * @return	    PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t) pjmedia_codec_mgr_init(pjmedia_codec_mgr *mgr);


/** 
 * Register codec factory to codec manager. This will also register
 * all supported codecs in the factory to the codec manager.
 *
 * @param mgr	    The codec manager instance. Application can get the
 *		    instance by calling #pjmedia_endpt_get_codec_mgr().
 * @param factory   The codec factory to be registered.
 *
 * @return	    PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t) 
pjmedia_codec_mgr_register_factory( pjmedia_codec_mgr *mgr,
				    pjmedia_codec_factory *factory);

/**
 * Unregister codec factory from the codec manager. This will also
 * remove all the codecs registered by the codec factory from the
 * codec manager's list of supported codecs.
 *
 * @param mgr	    The codec manager instance. Application can get the
 *		    instance by calling #pjmedia_endpt_get_codec_mgr().
 * @param factory   The codec factory to be unregistered.
 *
 * @return	    PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t) 
pjmedia_codec_mgr_unregister_factory( pjmedia_codec_mgr *mgr, 
				      pjmedia_codec_factory *factory);

/**
 * Enumerate all supported codecs that have been registered to the
 * codec manager by codec factories.
 *
 * @param mgr	    The codec manager instance. Application can get the
 *		    instance by calling #pjmedia_endpt_get_codec_mgr().
 * @param count	    On input, specifies the number of elements in
 *		    the array. On output, the value will be set to
 *		    the number of elements that have been initialized
 *		    by this function.
 * @param info	    The codec info array, which contents will be 
 *		    initialized upon return.
 * @param prio	    Optional pointer to receive array of codec priorities.
 *
 * @return	    PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t) pjmedia_codec_mgr_enum_codecs( pjmedia_codec_mgr *mgr, 
						    unsigned *count, 
						    pjmedia_codec_info info[],
						    unsigned *prio);

/**
 * Get codec info for the specified static payload type. Note that
 * this can only find codec with static payload types. This function can
 * be used to find codec info for a payload type inside SDP which doesn't
 * have the corresponding rtpmap attribute.
 *
 * @param mgr	    The codec manager instance. Application can get the
 *		    instance by calling #pjmedia_endpt_get_codec_mgr().
 * @param pt	    Static payload type/number.
 * @param inf	    Pointer to receive codec info.
 *
 * @return	    PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t) 
pjmedia_codec_mgr_get_codec_info( pjmedia_codec_mgr *mgr,
				  unsigned pt,
				  const pjmedia_codec_info **inf);

/**
 * Convert codec info struct into a unique codec identifier.
 * A codec identifier looks something like "L16/44100/2".
 *
 * @param info	    The codec info
 * @param id	    Buffer to put the codec info string.
 * @param max_len   The length of the buffer.
 *
 * @return	    The null terminated codec info string, or NULL if
 *		    the buffer is not long enough.
 */
PJ_DECL(char*) pjmedia_codec_info_to_id(const pjmedia_codec_info *info,
				        char *id, unsigned max_len );


/**
 * Find codecs by the unique codec identifier. This function will find
 * all codecs that match the codec identifier prefix. For example, if
 * "L16" is specified, then it will find "L16/8000/1", "L16/16000/1",
 * and so on, up to the maximum count specified in the argument.
 *
 * @param mgr	    The codec manager instance. Application can get the
 *		    instance by calling #pjmedia_endpt_get_codec_mgr().
 * @param codec_id  The full codec ID or codec ID prefix. If an empty
 *		    string is given, it will match all codecs.
 * @param count	    Maximum number of codecs to find. On return, it
 *		    contains the actual number of codecs found.
 * @param p_info    Array of pointer to codec info to be filled. This
 *		    argument may be NULL, which in this case, only
 *		    codec count will be returned.
 * @param prio	    Optional array of codec priorities.
 *
 * @return	    PJ_SUCCESS if at least one codec info is found.
 */
PJ_DECL(pj_status_t) 
pjmedia_codec_mgr_find_codecs_by_id( pjmedia_codec_mgr *mgr,
				     const pj_str_t *codec_id,
				     unsigned *count,
				     const pjmedia_codec_info *p_info[],
				     unsigned prio[]);


/**
 * Set codec priority. The codec priority determines the order of
 * the codec in the SDP created by the endpoint. If more than one codecs
 * are found with the same codec_id prefix, then the function sets the
 * priorities of all those codecs.
 *
 * @param mgr	    The codec manager instance. Application can get the
 *		    instance by calling #pjmedia_endpt_get_codec_mgr().
 * @param codec_id  The full codec ID or codec ID prefix. If an empty
 *		    string is given, it will match all codecs.
 * @param prio	    Priority to be set. The priority can have any value
 *		    between 1 to 255. When the priority is set to zero,
 *		    the codec will be disabled.
 *
 * @return	    PJ_SUCCESS if at least one codec info is found.
 */
PJ_DECL(pj_status_t)
pjmedia_codec_mgr_set_codec_priority(pjmedia_codec_mgr *mgr, 
				     const pj_str_t *codec_id,
				     pj_uint8_t prio);


/**
 * Get default codec param for the specified codec info.
 *
 * @param mgr	    The codec manager instance. Application can get the
 *		    instance by calling #pjmedia_endpt_get_codec_mgr().
 * @param info	    The codec info, which default parameter's is being
 *		    queried.
 * @param param	    On return, will be filled with the default codec
 *		    parameter.
 *
 * @return	    PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t) 
pjmedia_codec_mgr_get_default_param( pjmedia_codec_mgr *mgr,
				     const pjmedia_codec_info *info,
				     pjmedia_codec_param *param );

/**
 * Request the codec manager to allocate one instance of codec with the
 * specified codec info. The codec will enumerate all codec factories
 * until it finds factory that is able to create the specified codec.
 *
 * @param mgr	    The codec manager instance. Application can get the
 *		    instance by calling #pjmedia_endpt_get_codec_mgr().
 * @param info	    The information about the codec to be created.
 * @param p_codec   Pointer to receive the codec instance.
 *
 * @return	    PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t) 
pjmedia_codec_mgr_alloc_codec( pjmedia_codec_mgr *mgr, 
			       const pjmedia_codec_info *info,
			       pjmedia_codec **p_codec);

/**
 * Deallocate the specified codec instance. The codec manager will return
 * the instance of the codec back to its factory.
 *
 * @param mgr	    The codec manager instance. Application can get the
 *		    instance by calling #pjmedia_endpt_get_codec_mgr().
 * @param codec	    The codec instance.
 *
 * @return	    PJ_SUCESS on success.
 */
PJ_DECL(pj_status_t) pjmedia_codec_mgr_dealloc_codec(pjmedia_codec_mgr *mgr, 
						     pjmedia_codec *codec);





/**
 * @}
 */

PJ_END_DECL


#endif	/* __PJMEDIA_CODEC_H__ */