ice_strans.h

一个开源的sip源代码

/* $Id: ice_strans.h 1242 2007-05-02 11:29:37Z 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 __PJNATH_ICE_STRANS_H__
#define __PJNATH_ICE_STRANS_H__


/**
 * @file ice_strans.h
 * @brief ICE Stream Transport
 */
#include <pjnath/ice_session.h>
#include <pjlib-util/resolver.h>
#include <pj/ioqueue.h>
#include <pj/timer.h>


PJ_BEGIN_DECL


/**
 * @defgroup PJNATH_ICE_STREAM_TRANSPORT ICE Stream Transport
 * @brief Transport for media stream using ICE
 * @ingroup PJNATH_ICE
 * @{
 *
 * This module describes ICE stream transport, as represented by #pj_ice_strans
 * structure, and is part of PJNATH - the Open Source NAT traversal helper
 * library.
 *
 * ICE stream transport, as represented by #pj_ice_strans structure, is an ICE
 * capable component for transporting media within a media stream. 
 * It consists of one or more transport sockets (typically two for RTP
 * based communication - one for RTP and one for RTCP), and an 
 * \ref PJNATH_ICE_SESSION for performing connectivity checks among the.
 * various candidates of the transport addresses.
 *
 * \section PJNATH_ICE_STREAM_TRANSPORT_USING Using the ICE Stream Transport
 *
 * Application may use the ICE stream transport in two ways:
 *  - it can create the ICE stream transports once during application 
 *    initialization and keep them alive throughout application lifetime, or
 *  - it can create and destroy the ICE stream transport as needed everytime 
 *     a call is made and destroyed. 
 *
 * Keeping the ICE stream transport alive throughout
 * application's lifetime is normally preferable, as initializing the
 * ICE stream transport may incur delay because the ICE stream transport
 * would need to communicate with the STUN/TURN server to get the
 * server reflexive and relayed candidates for the transports.
 *
 * Regardless of which usage scenario is being used, the ICE stream
 * transport is capable for restarting the ICE session being used and to
 * send STUN keep-alives for its STUN server reflexive and relayed
 * candidates.
 *
 * \subsection PJNATH_ICE_ST_TRA_INIT Stream Transport Initialization
 *
 * Application creates the ICE stream transport by calling 
 * #pj_ice_strans_create() function.
 *
 * After the ICE stream transport is created, application may set up the
 * STUN servers to be used to obtain STUN server reflexive and relayed
 * candidate, by calling #pj_ice_strans_set_stun_domain() or 
 * #pj_ice_strans_set_stun_srv(). Then it has to create each component by
 * calling #pj_ice_strans_create_comp(); this would create an actual socket
 * which listens to the specified local address, and it would also
 * perform lookup to find various transport address candidates for this
 * socket.
 * 
 * \subsection PJNATH_ICE_ST_TRA_INIT_ICE ICE Session Initialization
 *
 * When application is about to send an offer containing ICE capability,
 * or when it receives an offer containing ICE capability, it would
 * create the ICE session by calling #pj_ice_strans_init_ice(). This would
 * register all transport address aliases for each component to the ICE
 * session as candidates. After this application can enumerate all local
 * candidates by calling #pj_ice_strans_enum_cands(), and encode these
 * candidates in the SDP to be sent to remote agent.
 *
 * \subsection PJNATH_ICE_ST_TRA_START Starting Connectivity Checks
 *
 * Once application receives the SDP from remote, it can start ICE
 * connectivity checks by calling #pj_ice_strans_start_ice(), specifying
 * the username, password, and candidates of the remote agent. The ICE
 * session/transport will then notify the application via the callback
 * when ICE connectivity checks completes, either successfully or with
 * failure.
 *
 * \subsection PJNATH_ICE_ST_TRA_STOP Stopping ICE Session
 *
 * Once the call is terminated, application no longer needs to keep the
 * ICE session, so it should call #pj_ice_strans_stop_ice() to destroy the
 * ICE session within this ICE stream transport. Note that this WILL NOT
 * destroy the sockets/transports, it only destroys the ICE session
 * within this ICE stream transport.
 *
 * \subsection PJNATH_ICE_ST_TRA_RESTART Restarting ICE Session
 *
 * When a new call is made, application can repeat the above
 * #pj_ice_strans_init_ice() to #pj_ice_strans_stop_ice() cycle for 
 * the new call, using this same ICE stream transport.
 *
 * \subsection PJNATH_ICE_ST_TRA_DESTROY Destroying ICE Stream Transport
 *
 * Finally, when the ICE stream transport itself is no longer needed,
 * for example when the application quits, application should call
 * #pj_ice_strans_destroy() to release back all resources allocated by this
 * ICE stream transport.
 *
 */

/** Forward declaration for ICE stream transport. */
typedef struct pj_ice_strans pj_ice_strans;

/** 
 * This structure contains callbacks that will be called by the 
 * ICE stream transport.
 */
typedef struct pj_ice_strans_cb
{
    /**
     * This callback will be called when the ICE transport receives
     * incoming packet from the sockets which is not related to ICE
     * (for example, normal RTP/RTCP packet destined for application).
     *
     * @param ice_st	    The ICE stream transport.
     * @param comp_id	    The component ID.
     * @param pkt	    The packet.
     * @param size	    Size of the packet.
     * @param src_addr	    Source address of the packet.
     * @param src_addr_len  Length of the source address.
     */
    void    (*on_rx_data)(pj_ice_strans *ice_st,
			  unsigned comp_id, 
			  void *pkt, pj_size_t size,
			  const pj_sockaddr_t *src_addr,
			  unsigned src_addr_len);

    /**
     * This callback will be called when ICE checks have completed.
     * This callback is optional.
     * 
     * @param ice_st	    The ICE stream transport.
     * @param status	    The ICE connectivity check status.
     */
    void    (*on_ice_complete)(pj_ice_strans *ice_st, 
			       pj_status_t status);

} pj_ice_strans_cb;


/**
 * Various flags that can be specified when creating a component with
 * #pj_ice_strans_create_comp(). These options may be combined together
 * with bitmask operation.
 */
enum pj_ice_strans_option
{
    /**
     * If this option is specified, only a listening socket will be
     * created for the component, and no candidate will be added to
     * the component. Application must add the component manually
     * by inspecting the socket and transport address of the component.
     */
    PJ_ICE_ST_OPT_DONT_ADD_CAND = 1,

    /**
     * If this option is specified, then no STUN reflexive candidate
     * will be added to the component.
     */
    PJ_ICE_ST_OPT_DISABLE_STUN	= 2,

    /**
     * If this option is specified, then no STUN relay candidate
     * will be added to the component.
     */
    PJ_ICE_ST_OPT_DISABLE_RELAY	= 4,

    /**
     * If this option is specified, then when the function fails to
     * bind the socket to the specified port, it WILL NOT try to
     * bind the socket to the next available port.
     *
     * If this option is NOT specified, then the function will try to
     * bind the socket to next port+2, repetitively until the socket
     * is bound successfully.
     */
    PJ_ICE_ST_OPT_NO_PORT_RETRY	= 8,
};


/**
 * This structure describes ICE stream transport candidate. A "candidate"
 * in ICE stream transport can be viewed as alias transport address
 * for the socket.
 */
typedef struct pj_ice_strans_cand
{
    /**
     * Candidate type.
     */
    pj_ice_cand_type	type;

    /** 
     * Status of this candidate. This status is useful for ICE reflexive
     * and relay candidate, where the address needs to be resolved 
     * asynchronously by sending STUN request to STUN server.
     *
     * The value will be PJ_SUCCESS if candidate address has been resolved
     * successfully, PJ_EPENDING when the address resolution process is
     * in progress, or other value when the address resolution has
     * completed with failure.
     */
    pj_status_t		status;

    /**
     * The candidate transport address.
     */
    pj_sockaddr		addr;

    /**
     * The ICE session candidate ID after this candidate has been registered
     * to an ICE session. Before ICE session is created, or after ICE
     * session has been destroyed, the value will be -1.
     */
    int			ice_cand_id;

    /**
     * Local preference value, which typically is 65535.
     */
    pj_uint16_t		local_pref;

    /**
     * Foundation associated with this candidate, which value normally will be
     * calculated by the function.
     */
    pj_str_t		foundation;

} pj_ice_strans_cand;


/**
 * This structure describes an ICE stream transport component. A component
 * in ICE stream transport typically corresponds to a single socket created
 * for this component, and bound to a specific transport address. This
 * component may have multiple alias addresses, for example one alias 
 * address for each interfaces in multi-homed host, another for server
 * reflexive alias, and another for relayed alias. For each transport
 * address alias, an ICE stream transport candidate (#pj_ice_strans_cand) will
 * be created, and these candidates will eventually registered to the ICE
 * session.
 */
typedef struct pj_ice_strans_comp
{
    pj_ice_strans	*ice_st;	/**< ICE stream transport.	*/
    unsigned		 comp_id;	/**< Component ID.		*/
    pj_uint32_t		 options;	/**< Option flags.		*/
    pj_sock_t		 sock;		/**< Socket descriptor.		*/

    pj_stun_session	*stun_sess;	/**< STUN session.		*/
    pj_uint8_t		 ka_tsx_id[12];	/**< ID for keep STUN alives	*/

    pj_sockaddr		 local_addr;	/**< Local/base address.	*/

    unsigned		 pending_cnt;	/**< Pending resolution cnt.	*/
    pj_status_t		 last_status;	/**< Last status.		*/

    unsigned		 cand_cnt;	/**< # of candidates/aliaes.	*/
    pj_ice_strans_cand	 cand_list[PJ_ICE_ST_MAX_CAND];	/**< Cand array	*/
    int			 default_cand;	/**< Default candidate selected	*/

    pj_ioqueue_key_t	*key;		/**< ioqueue key.		*/
    pj_uint8_t		 pkt[1500];	/**< Incoming packet buffer.	*/
    pj_ioqueue_op_key_t	 read_op;	/**< ioqueue read operation key	*/
    pj_ioqueue_op_key_t	 write_op;	/**< ioqueue write op. key	*/
    pj_sockaddr		 src_addr;	/**< source packet address buf.	*/
    int			 src_addr_len;	/**< length of src addr. buf.	*/

} pj_ice_strans_comp;