pjsua.h

基于sip协议的网络电话源码

 * \par Python:
 * The corresponding Python function creates and initialize the config:
 * \code
    stun_cfg = py_pjsua.stun_config_default()
 * \endcode
 */
PJ_INLINE(void) pjsua_stun_config_default(pjsua_stun_config *cfg)
{
    pj_bzero(cfg, sizeof(*cfg));
}


/**
 * Transport configuration for creating transports for both SIP
 * and media. Before setting some values to this structure, application
 * MUST call #pjsua_transport_config_default() to initialize its
 * values with default settings.
 *
 * \par Python:
 * The data type in Python is <tt>py_pjsua.Transport_Config</tt>,
 * although application can just do this to create the instance:
 * \code
    transport_cfg = py_pjsua.transport_config_default()
 * \endcode
 */
typedef struct pjsua_transport_config
{
    /**
     * UDP port number to bind locally. This setting MUST be specified
     * even when default port is desired. If the value is zero, the
     * transport will be bound to any available port, and application
     * can query the port by querying the transport info.
     */
    unsigned		port;

    /**
     * Optional address to advertise as the address of this transport.
     * Application can specify any address or hostname for this field,
     * for example it can point to one of the interface address in the
     * system, or it can point to the public address of a NAT router
     * where port mappings have been configured for the application.
     *
     * Note: this option can be used for both UDP and TCP as well!
     */
    pj_str_t		public_addr;

    /**
     * Optional address where the socket should be bound to. This option
     * SHOULD only be used to selectively bind the socket to particular
     * interface (instead of 0.0.0.0), and SHOULD NOT be used to set the
     * published address of a transport (the public_addr field should be
     * used for that purpose).
     *
     * Note that unlike public_addr field, the address (or hostname) here 
     * MUST correspond to the actual interface address in the host, since
     * this address will be specified as bind() argument.
     */
    pj_str_t		bound_addr;

    /**
     * Flag to indicate whether STUN should be used.
     */
    pj_bool_t		use_stun;

    /**
     * STUN configuration, must be specified when STUN is used.
     */
    pjsua_stun_config	stun_config;

    /**
     * This specifies TLS settings for TLS transport. It is only be used
     * when this transport config is being used to create a SIP TLS
     * transport.
     */
    pjsip_tls_setting	tls_setting;

} pjsua_transport_config;


/**
 * Call this function to initialize UDP config with default values.
 *
 * @param cfg	    The UDP config to be initialized.
 *
 * \par Python:
 * The corresponding Python function is rather different:
 * \code
    transport_cfg = py_pjsua.transport_config_default()
 * \endcode
 */
PJ_INLINE(void) pjsua_transport_config_default(pjsua_transport_config *cfg)
{
    pj_bzero(cfg, sizeof(*cfg));
    pjsua_stun_config_default(&cfg->stun_config);
    pjsip_tls_setting_default(&cfg->tls_setting);
}


/**
 * This is a utility function to normalize STUN config. It's only
 * used internally by the library.
 *
 * @param cfg	    The STUN config to be initialized.
 *
 * \par Python:
 * \code
    py_pjsua.normalize_stun_config(cfg)
 * \code
 */
PJ_INLINE(void) pjsua_normalize_stun_config( pjsua_stun_config *cfg )
{
    if (cfg->stun_srv1.slen) {

	if (cfg->stun_port1 == 0)
	    cfg->stun_port1 = 3478;

	if (cfg->stun_srv2.slen == 0) {
	    cfg->stun_srv2 = cfg->stun_srv1;
	    cfg->stun_port2 = cfg->stun_port1;
	} else {
	    if (cfg->stun_port2 == 0)
		cfg->stun_port2 = 3478;
	}

    } else {
	cfg->stun_port1 = 0;
	cfg->stun_srv2.slen = 0;
	cfg->stun_port2 = 0;
    }
}


/**
 * Duplicate transport config.
 *
 * @param pool		The pool.
 * @param dst		The destination config.
 * @param src		The source config.
 *
 * \par Python:
 * Not applicable. One should be able to just copy one variable instance
 * to another in Python.
 */
PJ_INLINE(void) pjsua_transport_config_dup(pj_pool_t *pool,
					   pjsua_transport_config *dst,
					   const pjsua_transport_config *src)
{
    pj_memcpy(dst, src, sizeof(*src));

    if (src->stun_config.stun_srv1.slen) {
	pj_strdup_with_null(pool, &dst->stun_config.stun_srv1,
			    &src->stun_config.stun_srv1);
    }

    if (src->stun_config.stun_srv2.slen) {
	pj_strdup_with_null(pool, &dst->stun_config.stun_srv2,
			    &src->stun_config.stun_srv2);
    }

    pjsua_normalize_stun_config(&dst->stun_config);
}



/**
 * This structure describes transport information returned by
 * #pjsua_transport_get_info() function.
 *
 * \par Python:
 * The corresponding data type in Python is <tt>py_pjsua.Transport_Info</tt>.
 */
typedef struct pjsua_transport_info
{
    /**
     * PJSUA transport identification.
     */
    pjsua_transport_id	    id;

    /**
     * Transport type.
     */
    pjsip_transport_type_e  type;

    /**
     * Transport type name.
     */
    pj_str_t		    type_name;

    /**
     * Transport string info/description.
     */
    pj_str_t		    info;

    /**
     * Transport flag (see ##pjsip_transport_flags_e).
     */
    unsigned		    flag;

    /**
     * Local address length.
     */
    unsigned		    addr_len;

    /**
     * Local/bound address.
     */
    pj_sockaddr		    local_addr;

    /**
     * Published address (or transport address name).
     */
    pjsip_host_port	    local_name;

    /**
     * Current number of objects currently referencing this transport.
     */
    unsigned		    usage_count;


} pjsua_transport_info;


/**
 * Create and start a new SIP transport according to the specified
 * settings.
 *
 * @param type		Transport type.
 * @param cfg		Transport configuration.
 * @param p_id		Optional pointer to receive transport ID.
 *
 * @return		PJ_SUCCESS on success, or the appropriate error code.
 *
 * \par Python:
 * The corresponding Python function returns (status,id) tuple:
 * \code
    status, transport_id = py_pjsua.transport_create(type, cfg)
 * \endcode
 */
PJ_DECL(pj_status_t) pjsua_transport_create(pjsip_transport_type_e type,
					    const pjsua_transport_config *cfg,
					    pjsua_transport_id *p_id);

/**
 * Register transport that has been created by application. This function
 * is useful if application wants to implement custom SIP transport and use
 * it with pjsua.
 *
 * @param tp		Transport instance.
 * @param p_id		Optional pointer to receive transport ID.
 *
 * @return		PJ_SUCCESS on success, or the appropriate error code.
 *
 * \par Python:
 * Not applicable (for now), because one cannot create a custom transport
 * from Python script.
 */
PJ_DECL(pj_status_t) pjsua_transport_register(pjsip_transport *tp,
					      pjsua_transport_id *p_id);


/**
 * Enumerate all transports currently created in the system. This function
 * will return all transport IDs, and application may then call 
 * #pjsua_transport_get_info() function to retrieve detailed information
 * about the transport.
 *
 * @param id		Array to receive transport ids.
 * @param count		In input, specifies the maximum number of elements.
 *			On return, it contains the actual number of elements.
 *
 * @return		PJ_SUCCESS on success, or the appropriate error code.
 *
 * \par Python:
 * The function returns list of integers representing transport ids:
 * \code
    [int] = py_pjsua.enum_transports()
 * \endcode
 */
PJ_DECL(pj_status_t) pjsua_enum_transports( pjsua_transport_id id[],
					    unsigned *count );


/**
 * Get information about transports.
 *
 * @param id		Transport ID.
 * @param info		Pointer to receive transport info.
 *
 * @return		PJ_SUCCESS on success, or the appropriate error code.
 *
 * \par Python:
 * \code
    transport_info = py_pjsua.transport_get_info(id)
 * \endcode
 * The Python function returns None on error.
 */
PJ_DECL(pj_status_t) pjsua_transport_get_info(pjsua_transport_id id,
					      pjsua_transport_info *info);


/**
 * Disable a transport or re-enable it. By default transport is always 
 * enabled after it is created. Disabling a transport does not necessarily
 * close the socket, it will only discard incoming messages and prevent
 * the transport from being used to send outgoing messages.
 *
 * @param id		Transport ID.
 * @param enabled	Non-zero to enable, zero to disable.
 *
 * @return		PJ_SUCCESS on success, or the appropriate error code.
 *
 * \par Python:
 * \code
    status = py_pjsua.transport_set_enable(id, enabled)
 * \endcode
 */
PJ_DECL(pj_status_t) pjsua_transport_set_enable(pjsua_transport_id id,
						pj_bool_t enabled);


/**
 * Close the transport. If transport is forcefully closed, it will be
 * immediately closed, and any pending transactions that are using the
 * transport may not terminate properly (it may even crash). Otherwise, 
 * the system will wait until all transactions are closed while preventing 
 * new users from using the transport, and will close the transport when 
 * it is safe to do so.
 *
 * @param id		Transport ID.
 * @param force		Non-zero to immediately close the transport. This
 *			is not recommended!
 *
 * @return		PJ_SUCCESS on success, or the appropriate error code.
 *
 * \par Python:
 * \code
    status = py_pjsua.transport_close(id, force)
 * \endcode
 */
PJ_DECL(pj_status_t) pjsua_transport_close( pjsua_transport_id id,
					    pj_bool_t force );

/**
 * @}
 */




/*****************************************************************************
 * ACCOUNT API
 */


/**
 * @defgroup PJSUA_LIB_ACC PJSUA-API Accounts Management
 * @ingroup PJSUA_LIB
 * @brief PJSUA Accounts management
 * @{
 *
 * PJSUA accounts provide identity (or identities) of the user who is currently
 * using the application. In SIP terms, the identity is used as the <b>From</b>
 * header in outgoing requests.
 *
 * PJSUA-API supports creating and managing multiple accounts. The maximum
 * number of accounts is limited by a compile time constant
 * <tt>PJSUA_MAX_ACC</tt>.
 *
 * Account may or may not have client registration associated with it.
 * An account is also associated with <b>route set</b> and some <b>authentication
 * credentials</b>, which are used when sending SIP request messages using the
 * account. An account also has presence's <b>online status</b>, which
 * will be reported to remote peer when they subscribe to the account's
 * presence, or which is published to a presence server if presence 
 * publication is enabled for the account.
 *
 * At least one account MUST be created in the application. If no user
 * association is required, application can create a userless account by
 * calling #pjsua_acc_add_local(). A userless account identifies local endpoint
 * instead of a particular user, and it correspond with a particular
 * transport instance.
 *
 * Also one account must be set as the <b>default account</b>, which is used as
 * the account to use when PJSUA fails to match a request with any other
 * accounts.
 *
 * When sending outgoing SIP requests (such as making calls or sending
 * instant messages), normally PJSUA requires the application to specify
 * which account to use for the request. If no account is specified,
 * PJSUA may be able to select the account by matching the destination
 * domain name, and fall back to default account when no match is found.
 */

/**
 * Maximum accounts.
 */
#ifndef PJSUA_MAX_ACC
#   define PJSUA_MAX_ACC	    8
#endif


/**
 * Default registration interval.
 */
#ifndef PJSUA_REG_INTERVAL
#   define PJSUA_REG_INTERVAL	    55
#endif


/**
 * Default PUBLISH expiration
 */
#ifndef PJSUA_PUBLISH_EXPIRATION
#   define PJSUA_PUBLISH_EXPIRATION 600
#endif


/**
 * Default account priority.
 */
#ifndef PJSUA_DEFAULT_ACC_PRIORITY
#   define PJSUA_DEFAULT_ACC_PRIORITY	0
#endif


/**
 * This structure describes account configuration to be specified when
 * adding a new account with #pjsua_acc_add(). Application MUST initialize
 * this structure first by calling #pjsua_acc_config_default().
 *
 * \par Python:
 * The data type in Python is <tt>py_pjsua.Acc_Config</tt>, but normally
 * application can just use the snippet below to create and initialize
 * the account config:
 * \code
    acc_cfg = py_pjsua.acc_config_default()
 * \endcode
 */
typedef struct pjsua_acc_config
{
    /**
     * Account priority, which is used to control the order of matching
     * incoming/outgoing requests. The higher the number means the higher
     * the priority is, and the account will be matched first.
     */
    int		    priority;

    /** 
     * The full SIP URL for the account. The value can take name address or 
     * URL format, and will look something like "sip:account@serviceprovider".
     *
     * This field is mandatory.
     */
    pj_str_t	    id;

    /** 
     * This is the URL to be put in the request URI for the registration,
     * and will look something like "sip:serviceprovider".
     *