From 3034f9480369cb8083cd625b358354b4618cd985 Mon Sep 17 00:00:00 2001 From: Benny Prijono Date: Sat, 17 Jun 2006 04:08:30 +0000 Subject: Modifications all over the place, but mainly only to update Doxygen documentation git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@515 74dad513-b988-da41-8d7b-12977e46ad98 --- pjsip/include/pjsua-lib/pjsua.h | 2237 ++++++++++++++++++++++----------------- 1 file changed, 1253 insertions(+), 984 deletions(-) (limited to 'pjsip/include/pjsua-lib/pjsua.h') diff --git a/pjsip/include/pjsua-lib/pjsua.h b/pjsip/include/pjsua-lib/pjsua.h index 65e0cc72..90ba0f42 100644 --- a/pjsip/include/pjsua-lib/pjsua.h +++ b/pjsip/include/pjsua-lib/pjsua.h @@ -19,6 +19,12 @@ #ifndef __PJSUA_H__ #define __PJSUA_H__ +/** + * @file pjsua.h + * @brief PJSUA API. + */ + + /* Include all PJSIP core headers. */ #include @@ -41,64 +47,138 @@ #include +/** + * @defgroup PJSUA_LIB PJSUA API + * @ingroup PJSIP + * @brief Very high level API for constructing SIP UA applications. + * @{ + * + * PJSUA API is very high level API for constructing SIP user agent + * applications. It wraps together the signaling and media functionalities + * into an easy to use call API, provides account management, buddy + * management, presence, instant messaging, along with multimedia + * features such as conferencing, file streaming, local playback, + * voice recording, and so on. + * + * Application must link with pjsua-lib to use this API. In addition, + * this library depends on the following libraries: + * - pjsip-ua, + * - pjsip-simple, + * - pjsip-core, + * - pjmedia, + * - pjmedia-codec, + * - pjlib-util, and + * - pjlib, + * + * so application must also link with these libraries as well. + * + * @section root_using_pjsua_lib Using PJSUA API + * + * Please refer to @ref using_pjsua_lib on how to use PJSUA API. + */ + PJ_BEGIN_DECL -/** - * Max buddies in buddy list. - */ -#ifndef PJSUA_MAX_BUDDIES -# define PJSUA_MAX_BUDDIES 256 -#endif +/** Forward declaration */ +typedef struct pjsua_media_config pjsua_media_config; -/** - * Max simultaneous calls. +/***************************************************************************** + * BASE API */ -#ifndef PJSUA_MAX_CALLS -# define PJSUA_MAX_CALLS 32 -#endif - /** - * Max ports in the conference bridge. - */ -#ifndef PJSUA_MAX_CONF_PORTS -# define PJSUA_MAX_CONF_PORTS 254 -#endif + * @defgroup PJSUA_LIB_BASE Base API + * @ingroup PJSUA_LIB + * @brief Basic application creation/initialization, logging configuration, etc. + * @{ + * + * The base PJSUA API controls PJSUA creation, initialization, and startup, and + * also provides various auxiliary functions. + * + * @section using_pjsua_lib Using PJSUA Library + * + * @subsection creating_pjsua_lib Creating PJSUA + * + * Before anything else, application must create PJSUA by calling #pjsua_create(). + * This, among other things, will initialize PJLIB, which is crucial before + * any PJLIB functions can be called. + * + * @subsection init_pjsua_lib Initializing PJSUA + * + * After PJSUA is created, application can initialize PJSUA by calling + * #pjsua_init(). This function takes several configuration settings in the + * argument, so application normally would want to set these configuration + * before passing them to #pjsua_init(). + * + * Sample code to initialize PJSUA: + \code + pjsua_config ua_cfg; + pjsua_logging_config log_cfg; + pjsua_media_config media_cfg; -/** - * Maximum accounts. - */ -#ifndef PJSUA_MAX_ACC -# define PJSUA_MAX_ACC 8 -#endif + // Initialize configs with default settings. + pjsua_config_default(&ua_cfg); + pjsua_logging_config_default(&log_cfg); + pjsua_media_config_default(&media_cfg); + // At the very least, application would want to override + // the call callbacks in pjsua_config: + ua_cfg.cb.on_incoming_call = ... + ua_cfg.cb.on_call_state = .. + ... -/** - * Maximum proxies in account. - */ -#ifndef PJSUA_ACC_MAX_PROXIES -# define PJSUA_ACC_MAX_PROXIES 8 -#endif + // Customize other settings (or initialize them from application specific + // configuration file): + ... -/** - * Default registration interval. - */ -#ifndef PJSUA_REG_INTERVAL -# define PJSUA_REG_INTERVAL 55 -#endif + // Initialize pjsua + status = pjsua_init(&ua_cfg, &log_cfg, &media_cfg); + if (status != PJ_SUCCESS) { + pjsua_perror(THIS_FILE, "Error initializing pjsua", status); + return status; + } + .. + \endcode + * + * @subsection other_init_pjsua_lib Other Initialization + * + * After PJSUA is initialized with #pjsua_init(), application will normally + * need/want to perform the following tasks: + * + * - create SIP transport with #pjsua_transport_create(). Please see + * @ref PJSUA_LIB_TRANSPORT section for more info. + * - create one or more SIP accounts with #pjsua_acc_add() or + * #pjsua_acc_add_local(). Please see @ref PJSUA_LIB_ACC for more info. + * - add one or more buddies with #pjsua_buddy_add(). Please see + * @ref PJSUA_LIB_BUDDY section for more info. + * - optionally configure the sound device, codec settings, and other + * media settings. Please see @ref PJSUA_LIB_MEDIA for more info. + * + * + * @subsection starting_pjsua_lib Starting PJSUA + * + * After all initializations have been done, application must call + * #pjsua_start() to start PJSUA. This function will check that all settings + * are properly configured, and apply default settings when it's not, or + * report error status when it is unable to recover from missing setting. + * + * Most settings can be changed during run-time. For example, application + * may add, modify, or delete accounts, buddies, or change media settings + * during run-time. + */ -/** Account identification */ -typedef int pjsua_acc_id; +/** Constant to identify invalid ID for all sorts of IDs. */ +#define PJSUA_INVALID_ID (-1) /** Call identification */ typedef int pjsua_call_id; -/** SIP transport identification */ -typedef int pjsua_transport_id; +/** Account identification */ +typedef int pjsua_acc_id; /** Buddy identification */ typedef int pjsua_buddy_id; @@ -113,1188 +193,1223 @@ typedef int pjsua_recorder_id; typedef int pjsua_conf_port_id; -/** Constant to identify invalid ID for all sorts of IDs. */ -#define PJSUA_INVALID_ID (-1) + +/** + * Maximum proxies in account. + */ +#ifndef PJSUA_ACC_MAX_PROXIES +# define PJSUA_ACC_MAX_PROXIES 8 +#endif /** - * Account configuration. + * Logging configuration. */ -typedef struct pjsua_acc_config +typedef struct pjsua_logging_config { - /** - * 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". - * - * This field should be specified if registration is desired. If the - * value is empty, no account registration will be performed. + /** + * Log incoming and outgoing SIP message? Yes! */ - pj_str_t reg_uri; + pj_bool_t msg_logging; - /** - * Optional URI to be put as Contact for this account. It is recommended - * that this field is left empty, so that the value will be calculated - * automatically based on the transport address. + /** + * Input verbosity level. Value 5 is reasonable. */ - pj_str_t contact; + unsigned level; /** - * Number of proxies in the proxy array below. + * Verbosity level for console. Value 4 is reasonable. */ - unsigned proxy_cnt; + unsigned console_level; - /** - * Optional URI of the proxies to be visited for all outgoing requests - * that are using this account (REGISTER, INVITE, etc). Application need - * to specify these proxies if the service provider requires that requests - * destined towards its network should go through certain proxies first - * (for example, border controllers). - * - * These proxies will be put in the route set for this account, with - * maintaining the orders (the first proxy in the array will be visited - * first). + /** + * Log decoration. */ - pj_str_t proxy[PJSUA_ACC_MAX_PROXIES]; + unsigned decor; - /** - * Optional interval for registration, in seconds. If the value is zero, - * default interval will be used (PJSUA_REG_INTERVAL, 55 seconds). + /** + * Optional log filename. */ - unsigned reg_timeout; + pj_str_t log_filename; - /** - * Number of credentials in the credential array. + /** + * Optional callback function to be called to write log to + * application specific device. This function will be called for + * log messages on input verbosity level. */ - unsigned cred_count; + void (*cb)(int level, const char *data, pj_size_t len); - /** - * Array of credentials. If registration is desired, normally there should - * be at least one credential specified, to successfully authenticate - * against the service provider. More credentials can be specified, for - * example when the requests are expected to be challenged by the - * proxies in the route set. - */ - pjsip_cred_info cred_info[PJSUA_ACC_MAX_PROXIES]; -} pjsua_acc_config; +} pjsua_logging_config; /** - * Call this function to initialize account config with default values. + * Use this function to initialize logging config. * - * @param cfg The account config to be initialized. + * @param cfg The logging config to be initialized. */ -PJ_INLINE(void) pjsua_acc_config_default(pjsua_acc_config *cfg) +PJ_INLINE(void) pjsua_logging_config_default(pjsua_logging_config *cfg) { pj_memset(cfg, 0, sizeof(*cfg)); - cfg->reg_timeout = PJSUA_REG_INTERVAL; + cfg->msg_logging = PJ_TRUE; + cfg->level = 5; + cfg->console_level = 4; + cfg->decor = PJ_LOG_HAS_SENDER | PJ_LOG_HAS_TIME | + PJ_LOG_HAS_MICRO_SEC | PJ_LOG_HAS_NEWLINE; +} + +/** + * Use this function to duplicate logging config. + * + * @param pool Pool to use. + * @param dst Destination config. + * @param src Source config. + */ +PJ_INLINE(void) pjsua_logging_config_dup(pj_pool_t *pool, + pjsua_logging_config *dst, + const pjsua_logging_config *src) +{ + pj_memcpy(dst, src, sizeof(*src)); + pj_strdup_with_null(pool, &dst->log_filename, &src->log_filename); } /** - * Account info. Application can query account info by calling - * #pjsua_acc_get_info(). + * Application callbacks. */ -typedef struct pjsua_acc_info +typedef struct pjsua_callback { - /** - * The account ID. - */ - pjsua_acc_id id; - /** - * Flag to indicate whether this is the default account. - */ - pj_bool_t is_default; - - /** - * Account URI + * Notify application when invite state has changed. + * Application may then query the call info to get the + * detail call states. */ - pj_str_t acc_uri; + void (*on_call_state)(pjsua_call_id call_id, pjsip_event *e); - /** - * Flag to tell whether this account has registration setting - * (reg_uri is not empty). + /** + * Notify application on incoming call. */ - pj_bool_t has_registration; + void (*on_incoming_call)(pjsua_acc_id acc_id, pjsua_call_id call_id, + pjsip_rx_data *rdata); /** - * An up to date expiration interval for account registration session. + * Notify application when media state in the call has changed. + * Normal application would need to implement this callback, e.g. + * to connect the call's media to sound device. */ - int expires; + void (*on_call_media_state)(pjsua_call_id call_id); /** - * Last registration status code. If status code is zero, the account - * is currently not registered. Any other value indicates the SIP - * status code of the registration. + * Notify application on call being transfered. + * Application can decide to accept/reject transfer request + * by setting the code (default is 200). When this callback + * is not defined, the default behavior is to accept the + * transfer. */ - pjsip_status_code status; + void (*on_call_transfered)(pjsua_call_id call_id, + const pj_str_t *dst, + pjsip_status_code *code); /** - * String describing the registration status. + * Notify application when registration status has changed. + * Application may then query the account info to get the + * registration details. */ - pj_str_t status_text; + void (*on_reg_state)(pjsua_acc_id acc_id); /** - * Presence online status for this account. + * Notify application when the buddy state has changed. + * Application may then query the buddy into to get the details. */ - pj_bool_t online_status; + void (*on_buddy_state)(pjsua_buddy_id buddy_id); /** - * Buffer that is used internally to store the status text. + * Notify application on incoming pager (i.e. MESSAGE request). + * Argument call_id will be -1 if MESSAGE request is not related to an + * existing call. */ - char buf_[PJ_ERR_MSG_SIZE]; - -} pjsua_acc_info; - - + void (*on_pager)(pjsua_call_id call_id, const pj_str_t *from, + const pj_str_t *to, const pj_str_t *contact, + const pj_str_t *mime_type, const pj_str_t *body); -/** - * STUN configuration. - */ -typedef struct pjsua_stun_config -{ /** - * The first STUN server IP address or hostname. + * Notify application about the delivery status of outgoing pager + * request. + * + * @param call_id Containts the ID of the call where the IM was + * sent, or PJSUA_INVALID_ID if the IM was sent + * outside call context. + * @param to Destination URI. + * @param body Message body. + * @param user_data Arbitrary data that was specified when sending + * IM message. + * @param status Delivery status. + * @param reason Delivery status reason. */ - pj_str_t stun_srv1; + void (*on_pager_status)(pjsua_call_id call_id, + const pj_str_t *to, + const pj_str_t *body, + void *user_data, + pjsip_status_code status, + const pj_str_t *reason); /** - * Port number of the first STUN server. - * If zero, default STUN port will be used. - */ - unsigned stun_port1; - - /** - * Optional second STUN server IP address or hostname, for which the - * result of the mapping request will be compared to. If the value - * is empty, only one STUN server will be used. + * Notify application about typing indication. */ - pj_str_t stun_srv2; + void (*on_typing)(pjsua_call_id call_id, const pj_str_t *from, + const pj_str_t *to, const pj_str_t *contact, + pj_bool_t is_typing); - /** - * Port number of the second STUN server. - * If zero, default STUN port will be used. - */ - unsigned stun_port2; +} pjsua_callback; -} pjsua_stun_config; /** - * Call this function to initialize STUN config with default values. - * - * @param cfg The STUN config to be initialized. + * PJSUA settings. */ -PJ_INLINE(void) pjsua_stun_config_default(pjsua_stun_config *cfg) +typedef struct pjsua_config { - pj_memset(cfg, 0, sizeof(*cfg)); -} + /** + * Maximum calls to support (default: 4) + */ + unsigned max_calls; -/** - * Transport configuration for creating UDP transports for both SIP - * and media. - */ -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. + /** + * Number of worker threads. Normally application will want to have at + * least one worker thread, unless when it wants to poll the library + * periodically, which in this case the worker thread can be set to + * zero. */ - unsigned port; + unsigned thread_cnt; /** - * Optional address where the socket should be bound. + * Number of outbound proxies in the array. */ - pj_in_addr ip_addr; + unsigned outbound_proxy_cnt; - /** - * Flag to indicate whether STUN should be used. + /** + * Specify the URL of outbound proxies to visit for all outgoing requests. + * The outbound proxies will be used for all accounts, and it will + * be used to build the route set for outgoing requests. The final + * route set for outgoing requests will consists of the outbound proxies + * and the proxy configured in the account. */ - pj_bool_t use_stun; + pj_str_t outbound_proxy[4]; + + /** + * Number of credentials in the credential array. + */ + unsigned cred_count; + + /** + * Array of credentials. These credentials will be used by all accounts, + * and can be used to authenticate against outbound proxies. + */ + pjsip_cred_info cred_info[PJSUA_ACC_MAX_PROXIES]; /** - * STUN configuration, must be specified when STUN is used. + * Application callback. */ - pjsua_stun_config stun_config; + pjsua_callback cb; -} pjsua_transport_config; +} pjsua_config; /** - * Call this function to initialize UDP config with default values. + * Use this function to initialize pjsua config. * - * @param cfg The UDP config to be initialized. + * @param cfg pjsua config to be initialized. */ -PJ_INLINE(void) pjsua_transport_config_default(pjsua_transport_config *cfg) +PJ_INLINE(void) pjsua_config_default(pjsua_config *cfg) { pj_memset(cfg, 0, sizeof(*cfg)); + + cfg->max_calls = 4; + cfg->thread_cnt = 1; } /** - * Normalize STUN config. + * Duplicate credential. */ -PJ_INLINE(void) pjsua_normalize_stun_config( pjsua_stun_config *cfg ) +PJ_INLINE(void) pjsip_cred_dup( pj_pool_t *pool, + pjsip_cred_info *dst, + const pjsip_cred_info *src) { - 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; - } + pj_strdup_with_null(pool, &dst->realm, &src->realm); + pj_strdup_with_null(pool, &dst->scheme, &src->scheme); + pj_strdup_with_null(pool, &dst->username, &src->username); + pj_strdup_with_null(pool, &dst->data, &src->data); - } else { - cfg->stun_port1 = 0; - cfg->stun_srv2.slen = 0; - cfg->stun_port2 = 0; - } } /** - * Duplicate transport config. + * Duplicate pjsua_config. */ -PJ_INLINE(void) pjsua_transport_config_dup(pj_pool_t *pool, - pjsua_transport_config *dst, - const pjsua_transport_config *src) +PJ_INLINE(void) pjsua_config_dup(pj_pool_t *pool, + pjsua_config *dst, + const pjsua_config *src) { + unsigned i; + 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); + for (i=0; ioutbound_proxy_cnt; ++i) { + pj_strdup_with_null(pool, &dst->outbound_proxy[i], + &src->outbound_proxy[i]); } - if (src->stun_config.stun_srv2.slen) { - pj_strdup_with_null(pool, &dst->stun_config.stun_srv2, - &src->stun_config.stun_srv2); + for (i=0; icred_count; ++i) { + pjsip_cred_dup(pool, &dst->cred_info[i], &src->cred_info[i]); } - - pjsua_normalize_stun_config(&dst->stun_config); } /** - * Transport info. + * This structure describes additional information to be sent with + * outgoing SIP message. */ -typedef struct pjsua_transport_info +typedef struct pjsua_msg_data { /** - * PJSUA transport identification. + * Additional message headers as linked list. */ - pjsua_transport_id id; + pjsip_hdr hdr_list; /** - * Transport type. + * MIME type of optional message body. */ - pjsip_transport_type_e type; + pj_str_t content_type; /** - * Transport type name. + * Optional message body. */ - pj_str_t type_name; + pj_str_t msg_body; - /** - * Transport string info/description. - */ - pj_str_t info; +} pjsua_msg_data; - /** - * Transport flag (see ##pjsip_transport_flags_e). - */ - unsigned flag; - /** - * Local address length. - */ - unsigned addr_len; +/** + * Initialize message data. + * + * @param msg_data Message data to be initialized. + */ +PJ_INLINE(void) pjsua_msg_data_init(pjsua_msg_data *msg_data) +{ + pj_memset(msg_data, 0, sizeof(*msg_data)); + pj_list_init(&msg_data->hdr_list); +} - /** - * 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; +/** + * Instantiate pjsua application. Application must call this function before + * calling any other functions, to make sure that the underlying libraries + * are properly initialized. Once this function has returned success, + * application must call pjsua_destroy() before quitting. + * + * @return PJ_SUCCESS on success, or the appropriate error code. + */ +PJ_DECL(pj_status_t) pjsua_create(void); -} pjsua_transport_info; +/** + * Initialize pjsua with the specified settings. All the settings are + * optional, and the default values will be used when the config is not + * specified. + * + * @param ua_cfg User agent configuration. + * @param log_cfg Optional logging configuration. + * @param media_cfg Optional media configuration. + * + * @return PJ_SUCCESS on success, or the appropriate error code. + */ +PJ_DECL(pj_status_t) pjsua_init(const pjsua_config *ua_cfg, + const pjsua_logging_config *log_cfg, + const pjsua_media_config *media_cfg); /** - * Media configuration. + * Application is recommended to call this function after all initialization + * is done, so that the library can do additional checking set up + * additional + * + * @return PJ_SUCCESS on success, or the appropriate error code. */ -typedef struct pjsua_media_config -{ - /** - * Clock rate to be applied to the conference bridge. - * If value is zero, default clock rate will be used (16KHz). - */ - unsigned clock_rate; - - /** - * Specify maximum number of media ports to be created in the - * conference bridge. Since all media terminate in the bridge - * (calls, file player, file recorder, etc), the value must be - * large enough to support all of them. However, the larger - * the value, the more computations are performed. - */ - unsigned max_media_ports; - - /** - * Specify whether the media manager should manage its own - * ioqueue for the RTP/RTCP sockets. If yes, ioqueue will be created - * and at least one worker thread will be created too. If no, - * the RTP/RTCP sockets will share the same ioqueue as SIP sockets, - * and no worker thread is needed. - * - * Normally application would say yes here, unless it wants to - * run everything from a single thread. - */ - pj_bool_t has_ioqueue; - - /** - * Specify the number of worker threads to handle incoming RTP - * packets. A value of one is recommended for most applications. - */ - unsigned thread_cnt; +PJ_DECL(pj_status_t) pjsua_start(void); -} pjsua_media_config; +/** + * Destroy pjsua. This function must be called once PJSUA is created. To + * make it easier for application, application may call this function + * several times with no danger. + * + * @return PJ_SUCCESS on success, or the appropriate error code. + */ +PJ_DECL(pj_status_t) pjsua_destroy(void); /** - * Use this function to initialize media config. + * Poll pjsua for events, and if necessary block the caller thread for + * the specified maximum interval (in miliseconds). * - * @param cfg The media config to be initialized. + * @param msec_timeout Maximum time to wait, in miliseconds. + * + * @return The number of events that have been handled during the + * poll. Negative value indicates error, and application + * can retrieve the error as (err = -return_value). */ -PJ_INLINE(void) pjsua_media_config_default(pjsua_media_config *cfg) -{ - pj_memset(cfg, 0, sizeof(*cfg)); +PJ_DECL(int) pjsua_handle_events(unsigned msec_timeout); - cfg->clock_rate = 16000; - cfg->max_media_ports = 32; - cfg->has_ioqueue = PJ_TRUE; - cfg->thread_cnt = 1; -} +/** + * Create memory pool. + * + * @param name Optional pool name. + * @param init_size Initial size of the pool. + * @param increment Increment size. + * + * @return The pool, or NULL when there's no memory. + */ +PJ_DECL(pj_pool_t*) pjsua_pool_create(const char *name, pj_size_t init_size, + pj_size_t increment); /** - * Logging configuration. + * Application can call this function at any time (after pjsua_create(), of + * course) to change logging settings. + * + * @param c Logging configuration. + * + * @return PJ_SUCCESS on success, or the appropriate error code. */ -typedef struct pjsua_logging_config -{ - /** - * Log incoming and outgoing SIP message? Yes! - */ - pj_bool_t msg_logging; - - /** - * Input verbosity level. Value 5 is reasonable. - */ - unsigned level; +PJ_DECL(pj_status_t) pjsua_reconfigure_logging(const pjsua_logging_config *c); - /** - * Verbosity level for console. Value 4 is reasonable. - */ - unsigned console_level; - /** - * Log decoration. - */ - unsigned decor; +/** + * Internal function to get SIP endpoint instance of pjsua, which is + * needed for example to register module, create transports, etc. + * Probably is only valid after #pjsua_init() is called. + * + * @return SIP endpoint instance. + */ +PJ_DECL(pjsip_endpoint*) pjsua_get_pjsip_endpt(void); - /** - * Optional log filename. - */ - pj_str_t log_filename; +/** + * Internal function to get media endpoint instance. + * Only valid after #pjsua_init() is called. + * + * @return Media endpoint instance. + */ +PJ_DECL(pjmedia_endpt*) pjsua_get_pjmedia_endpt(void); - /** - * Optional callback function to be called to write log to - * application specific device. This function will be called for - * log messages on input verbosity level. - */ - void (*cb)(int level, const char *data, pj_size_t len); +/***************************************************************************** + * Utilities. + * + */ -} pjsua_logging_config; +/** + * Verify that valid SIP url is given. + * + * @param c_url The URL, as NULL terminated string. + * + * @return PJ_SUCCESS on success, or the appropriate error code. + */ +PJ_DECL(pj_status_t) pjsua_verify_sip_url(const char *c_url); /** - * Use this function to initialize logging config. + * Display error message for the specified error code. * - * @param cfg The logging config to be initialized. + * @param sender The log sender field. + * @param title Message title for the error. + * @param status Status code. */ -PJ_INLINE(void) pjsua_logging_config_default(pjsua_logging_config *cfg) -{ - pj_memset(cfg, 0, sizeof(*cfg)); +PJ_DECL(void) pjsua_perror(const char *sender, const char *title, + pj_status_t status); + + - cfg->msg_logging = PJ_TRUE; - cfg->level = 5; - cfg->console_level = 4; - cfg->decor = PJ_LOG_HAS_SENDER | PJ_LOG_HAS_TIME | - PJ_LOG_HAS_MICRO_SEC | PJ_LOG_HAS_NEWLINE; -} /** - * Use this function to duplicate logging config. - * - * @param pool Pool to use. - * @param dst Destination config. - * @param src Source config. + * @} */ -PJ_INLINE(void) pjsua_logging_config_dup(pj_pool_t *pool, - pjsua_logging_config *dst, - const pjsua_logging_config *src) -{ - pj_memcpy(dst, src, sizeof(*src)); - pj_strdup_with_null(pool, &dst->log_filename, &src->log_filename); -} + +/***************************************************************************** + * TRANSPORT API + */ + /** - * Buddy configuration. + * @defgroup PJSUA_LIB_TRANSPORT Signaling Transport + * @ingroup PJSUA_LIB + * @brief API for managing SIP transports + * @{ + * SIP transport must be created before adding an account. SIP transport is + * created by calling #pjsua_transport_create() function. */ -typedef struct pjsua_buddy_config -{ - /** - * Buddy URL or name address. - */ - pj_str_t uri; - /** - * Specify whether presence subscription should start immediately. - */ - pj_bool_t subscribe; -} pjsua_buddy_config; +/** SIP transport identification */ +typedef int pjsua_transport_id; /** - * Buddy's online status. + * STUN configuration. */ -typedef enum pjsua_buddy_status +typedef struct pjsua_stun_config { /** - * Online status is unknown (possibly because no presence subscription - * has been established). + * The first STUN server IP address or hostname. */ - PJSUA_BUDDY_STATUS_UNKNOWN, + pj_str_t stun_srv1; /** - * Buddy is known to be offline. + * Port number of the first STUN server. + * If zero, default STUN port will be used. */ - PJSUA_BUDDY_STATUS_ONLINE, + unsigned stun_port1; + + /** + * Optional second STUN server IP address or hostname, for which the + * result of the mapping request will be compared to. If the value + * is empty, only one STUN server will be used. + */ + pj_str_t stun_srv2; /** - * Buddy is offline. + * Port number of the second STUN server. + * If zero, default STUN port will be used. */ - PJSUA_BUDDY_STATUS_OFFLINE, + unsigned stun_port2; -} pjsua_buddy_status; +} pjsua_stun_config; /** - * Buddy info. + * Call this function to initialize STUN config with default values. + * + * @param cfg The STUN config to be initialized. */ -typedef struct pjsua_buddy_info +PJ_INLINE(void) pjsua_stun_config_default(pjsua_stun_config *cfg) { - /** - * The buddy ID. - */ - pjsua_buddy_id id; - - /** - * The full URI of the buddy, as specified in the configuration. - */ - pj_str_t uri; + pj_memset(cfg, 0, sizeof(*cfg)); +} - /** - * Buddy's Contact, only available when presence subscription has - * been established to the buddy. - */ - pj_str_t contact; +/** + * Transport configuration for creating UDP transports for both SIP + * and media. + */ +typedef struct pjsua_transport_config +{ /** - * Buddy's online status. + * 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. */ - pjsua_buddy_status status; + unsigned port; /** - * Text to describe buddy's online status. + * Optional address where the socket should be bound. */ - pj_str_t status_text; + pj_in_addr ip_addr; /** - * Flag to indicate that we should monitor the presence information for - * this buddy (normally yes, unless explicitly disabled). + * Flag to indicate whether STUN should be used. */ - pj_bool_t monitor_pres; + pj_bool_t use_stun; /** - * Internal buffer. + * STUN configuration, must be specified when STUN is used. */ - char buf_[256]; + pjsua_stun_config stun_config; -} pjsua_buddy_info; +} pjsua_transport_config; /** - * Codec config. + * Call this function to initialize UDP config with default values. + * + * @param cfg The UDP config to be initialized. */ -typedef struct pjsua_codec_info +PJ_INLINE(void) pjsua_transport_config_default(pjsua_transport_config *cfg) { - /** - * Codec unique identification. - */ - pj_str_t codec_id; + pj_memset(cfg, 0, sizeof(*cfg)); +} - /** - * Codec priority (integer 0-255). - */ - pj_uint8_t priority; - /** - * Internal buffer. - */ - char buf_[32]; +/** + * Normalize STUN config. + */ +PJ_INLINE(void) pjsua_normalize_stun_config( pjsua_stun_config *cfg ) +{ + if (cfg->stun_srv1.slen) { -} pjsua_codec_info; + 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; + } +} /** - * Application callbacks. + * Duplicate transport config. */ -typedef struct pjsua_callback +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); +} + + + +/** + * Transport info. + */ +typedef struct pjsua_transport_info { /** - * Notify application when invite state has changed. - * Application may then query the call info to get the - * detail call states. + * PJSUA transport identification. */ - void (*on_call_state)(pjsua_call_id call_id, pjsip_event *e); + pjsua_transport_id id; /** - * Notify application on incoming call. + * Transport type. */ - void (*on_incoming_call)(pjsua_acc_id acc_id, pjsua_call_id call_id, - pjsip_rx_data *rdata); + pjsip_transport_type_e type; /** - * Notify application when media state in the call has changed. - * Normal application would need to implement this callback, e.g. - * to connect the call's media to sound device. + * Transport type name. */ - void (*on_call_media_state)(pjsua_call_id call_id); + pj_str_t type_name; /** - * Notify application on call being transfered. - * Application can decide to accept/reject transfer request - * by setting the code (default is 200). When this callback - * is not defined, the default behavior is to accept the - * transfer. + * Transport string info/description. */ - void (*on_call_transfered)(pjsua_call_id call_id, - const pj_str_t *dst, - pjsip_status_code *code); + pj_str_t info; /** - * Notify application when registration status has changed. - * Application may then query the account info to get the - * registration details. + * Transport flag (see ##pjsip_transport_flags_e). */ - void (*on_reg_state)(pjsua_acc_id acc_id); + unsigned flag; /** - * Notify application when the buddy state has changed. - * Application may then query the buddy into to get the details. + * Local address length. */ - void (*on_buddy_state)(pjsua_buddy_id buddy_id); + unsigned addr_len; /** - * Notify application on incoming pager (i.e. MESSAGE request). - * Argument call_id will be -1 if MESSAGE request is not related to an - * existing call. + * Local/bound address. */ - void (*on_pager)(pjsua_call_id call_id, const pj_str_t *from, - const pj_str_t *to, const pj_str_t *contact, - const pj_str_t *mime_type, const pj_str_t *body); + pj_sockaddr local_addr; /** - * Notify application about the delivery status of outgoing pager - * request. - * - * @param call_id Containts the ID of the call where the IM was - * sent, or PJSUA_INVALID_ID if the IM was sent - * outside call context. - * @param to Destination URI. - * @param body Message body. - * @param user_data Arbitrary data that was specified when sending - * IM message. - * @param status Delivery status. - * @param reason Delivery status reason. + * Published address (or transport address name). */ - void (*on_pager_status)(pjsua_call_id call_id, - const pj_str_t *to, - const pj_str_t *body, - void *user_data, - pjsip_status_code status, - const pj_str_t *reason); + pjsip_host_port local_name; /** - * Notify application about typing indication. + * Current number of objects currently referencing this transport. */ - void (*on_typing)(pjsua_call_id call_id, const pj_str_t *from, - const pj_str_t *to, const pj_str_t *contact, - pj_bool_t is_typing); - -} pjsua_callback; + unsigned usage_count; +} pjsua_transport_info; /** - * PJSUA settings. + * Create SIP transport. + * + * @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. */ -typedef struct pjsua_config -{ - - /** - * Maximum calls to support (default: 4) - */ - unsigned max_calls; - - /** - * Number of worker threads. Normally application will want to have at - * least one worker thread, unless when it wants to poll the library - * periodically, which in this case the worker thread can be set to - * zero. - */ - unsigned thread_cnt; - - /** - * Number of outbound proxies in the array. - */ - unsigned outbound_proxy_cnt; - - /** - * Specify the URL of outbound proxies to visit for all outgoing requests. - * The outbound proxies will be used for all accounts, and it will - * be used to build the route set for outgoing requests. The final - * route set for outgoing requests will consists of the outbound proxies - * and the proxy configured in the account. - */ - pj_str_t outbound_proxy[4]; - - /** - * Number of credentials in the credential array. - */ - unsigned cred_count; - - /** - * Array of credentials. These credentials will be used by all accounts, - * and can be used to authenticate against outbound proxies. - */ - pjsip_cred_info cred_info[PJSUA_ACC_MAX_PROXIES]; - - /** - * Application callback. - */ - pjsua_callback cb; - -} pjsua_config; - +PJ_DECL(pj_status_t) pjsua_transport_create(pjsip_transport_type_e type, + const pjsua_transport_config *cfg, + pjsua_transport_id *p_id); /** - * Use this function to initialize pjsua config. + * Register transport that has been created by application. * - * @param cfg pjsua config to be initialized. + * @param tp Transport instance. + * @param p_id Optional pointer to receive transport ID. + * + * @return PJ_SUCCESS on success, or the appropriate error code. */ -PJ_INLINE(void) pjsua_config_default(pjsua_config *cfg) -{ - pj_memset(cfg, 0, sizeof(*cfg)); - - cfg->max_calls = 4; - cfg->thread_cnt = 1; -} +PJ_DECL(pj_status_t) pjsua_transport_register(pjsip_transport *tp, + pjsua_transport_id *p_id); /** - * Duplicate credential. + * Enumerate all transports currently created in the system. + * + * @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. */ -PJ_INLINE(void) pjsip_cred_dup( pj_pool_t *pool, - pjsip_cred_info *dst, - const pjsip_cred_info *src) -{ - pj_strdup_with_null(pool, &dst->realm, &src->realm); - pj_strdup_with_null(pool, &dst->scheme, &src->scheme); - pj_strdup_with_null(pool, &dst->username, &src->username); - pj_strdup_with_null(pool, &dst->data, &src->data); - -} +PJ_DECL(pj_status_t) pjsua_enum_transports( pjsua_transport_id id[], + unsigned *count ); /** - * Duplicate pjsua_config. + * 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. */ -PJ_INLINE(void) pjsua_config_dup(pj_pool_t *pool, - pjsua_config *dst, - const pjsua_config *src) -{ - unsigned i; - - pj_memcpy(dst, src, sizeof(*src)); +PJ_DECL(pj_status_t) pjsua_transport_get_info(pjsua_transport_id id, + pjsua_transport_info *info); - for (i=0; ioutbound_proxy_cnt; ++i) { - pj_strdup_with_null(pool, &dst->outbound_proxy[i], - &src->outbound_proxy[i]); - } - for (i=0; icred_count; ++i) { - pjsip_cred_dup(pool, &dst->cred_info[i], &src->cred_info[i]); - } -} +/** + * 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. + */ +PJ_DECL(pj_status_t) pjsua_transport_set_enable(pjsua_transport_id id, + pj_bool_t enabled); /** - * Call media status. + * 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. 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. */ -typedef enum pjsua_call_media_status -{ - PJSUA_CALL_MEDIA_NONE, - PJSUA_CALL_MEDIA_ACTIVE, - PJSUA_CALL_MEDIA_LOCAL_HOLD, - PJSUA_CALL_MEDIA_REMOTE_HOLD, -} pjsua_call_media_status; - +PJ_DECL(pj_status_t) pjsua_transport_close( pjsua_transport_id id, + pj_bool_t force ); /** - * Call info. + * @} */ -typedef struct pjsua_call_info -{ - /** Call identification. */ - pjsua_call_id id; - /** Initial call role (UAC == caller) */ - pjsip_role_e role; - /** Local URI */ - pj_str_t local_info; - /** Local Contact */ - pj_str_t local_contact; - /** Remote URI */ - pj_str_t remote_info; +/***************************************************************************** + * ACCOUNT API + */ - /** Remote contact */ - pj_str_t remote_contact; - /** Dialog Call-ID string. */ - pj_str_t call_id; +/** + * @defgroup PJSUA_LIB_ACC Account Management + * @ingroup PJSUA_LIB + * @brief PJSUA supports multiple accounts.. + * @{ + * PJSUA accounts provide identity (or identities) of the user who is currently + * using the application. More than one account maybe created with PJSUA. + * + * Account may or may not have client registration associated with it. + * An account is also associated with route set and some authentication + * credentials, which are used when sending SIP request messages using the + * account. An account also has presence's online status, which + * will be reported to remote peer when the subscribe to the account's + * presence. + * + * 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. + * + * Also one account must be set as the default account, 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. + */ - /** Call state */ - pjsip_inv_state state; +/** + * Maximum accounts. + */ +#ifndef PJSUA_MAX_ACC +# define PJSUA_MAX_ACC 8 +#endif - /** Text describing the state */ - pj_str_t state_text; - /** Last status code heard, which can be used as cause code */ - pjsip_status_code last_status; +/** + * Default registration interval. + */ +#ifndef PJSUA_REG_INTERVAL +# define PJSUA_REG_INTERVAL 55 +#endif - /** The reason phrase describing the status. */ - pj_str_t last_status_text; - /** Call media status. */ - pjsua_call_media_status media_status; +/** + * Account configuration. + */ +typedef struct pjsua_acc_config +{ + /** + * 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; - /** Media direction */ - pjmedia_dir media_dir; + /** + * This is the URL to be put in the request URI for the registration, + * and will look something like "sip:serviceprovider". + * + * This field should be specified if registration is desired. If the + * value is empty, no account registration will be performed. + */ + pj_str_t reg_uri; - /** The conference port number for the call */ - pjsua_conf_port_id conf_slot; + /** + * Optional URI to be put as Contact for this account. It is recommended + * that this field is left empty, so that the value will be calculated + * automatically based on the transport address. + */ + pj_str_t contact; - /** Up-to-date call connected duration (zero when call is not - * established) + /** + * Number of proxies in the proxy array below. */ - pj_time_val connect_duration; + unsigned proxy_cnt; - /** Total call duration, including set-up time */ - pj_time_val total_duration; + /** + * Optional URI of the proxies to be visited for all outgoing requests + * that are using this account (REGISTER, INVITE, etc). Application need + * to specify these proxies if the service provider requires that requests + * destined towards its network should go through certain proxies first + * (for example, border controllers). + * + * These proxies will be put in the route set for this account, with + * maintaining the orders (the first proxy in the array will be visited + * first). + */ + pj_str_t proxy[PJSUA_ACC_MAX_PROXIES]; - /** Internal */ - struct { - char local_info[128]; - char local_contact[128]; - char remote_info[128]; - char remote_contact[128]; - char call_id[128]; - char last_status_text[128]; - } buf_; + /** + * Optional interval for registration, in seconds. If the value is zero, + * default interval will be used (PJSUA_REG_INTERVAL, 55 seconds). + */ + unsigned reg_timeout; -} pjsua_call_info; + /** + * Number of credentials in the credential array. + */ + unsigned cred_count; + /** + * Array of credentials. If registration is desired, normally there should + * be at least one credential specified, to successfully authenticate + * against the service provider. More credentials can be specified, for + * example when the requests are expected to be challenged by the + * proxies in the route set. + */ + pjsip_cred_info cred_info[PJSUA_ACC_MAX_PROXIES]; +} pjsua_acc_config; /** - * Conference port info. + * Call this function to initialize account config with default values. + * + * @param cfg The account config to be initialized. */ -typedef struct pjsua_conf_port_info +PJ_INLINE(void) pjsua_acc_config_default(pjsua_acc_config *cfg) { - /** Conference port number. */ - pjsua_conf_port_id slot_id; - - /** Port name. */ - pj_str_t name; - - /** Clock rate. */ - unsigned clock_rate; - - /** Number of channels. */ - unsigned channel_count; - - /** Samples per frame */ - unsigned samples_per_frame; - - /** Bits per sample */ - unsigned bits_per_sample; - - /** Number of listeners in the array. */ - unsigned listener_cnt; + pj_memset(cfg, 0, sizeof(*cfg)); - /** Array of listeners (in other words, ports where this port is - * transmitting to. - */ - pjsua_conf_port_id listeners[PJSUA_MAX_CONF_PORTS]; + cfg->reg_timeout = PJSUA_REG_INTERVAL; +} -} pjsua_conf_port_info; /** - * This structure holds information about custom media transport to - * be registered to pjsua. + * Account info. Application can query account info by calling + * #pjsua_acc_get_info(). */ -typedef struct pjsua_media_transport +typedef struct pjsua_acc_info { - /** - * Media socket information containing the address information - * of the RTP and RTCP socket. + /** + * The account ID. */ - pjmedia_sock_info skinfo; + pjsua_acc_id id; /** - * The media transport instance. + * Flag to indicate whether this is the default account. */ - pjmedia_transport *transport; + pj_bool_t is_default; -} pjsua_media_transport; + /** + * Account URI + */ + pj_str_t acc_uri; + /** + * Flag to tell whether this account has registration setting + * (reg_uri is not empty). + */ + pj_bool_t has_registration; + + /** + * An up to date expiration interval for account registration session. + */ + int expires; + + /** + * Last registration status code. If status code is zero, the account + * is currently not registered. Any other value indicates the SIP + * status code of the registration. + */ + pjsip_status_code status; -/** - * This structure describes additional information to be sent with - * outgoing SIP message. - */ -typedef struct pjsua_msg_data -{ /** - * Additional message headers as linked list. + * String describing the registration status. */ - pjsip_hdr hdr_list; + pj_str_t status_text; /** - * MIME type of optional message body. + * Presence online status for this account. */ - pj_str_t content_type; + pj_bool_t online_status; /** - * Optional message body. + * Buffer that is used internally to store the status text. */ - pj_str_t msg_body; + char buf_[PJ_ERR_MSG_SIZE]; + +} pjsua_acc_info; -} pjsua_msg_data; /** - * Initialize message data. + * Get number of current accounts. * - * @param msg_data Message data to be initialized. + * @return Current number of accounts. */ -PJ_INLINE(void) pjsua_msg_data_init(pjsua_msg_data *msg_data) -{ - pj_memset(msg_data, 0, sizeof(*msg_data)); - pj_list_init(&msg_data->hdr_list); -} +PJ_DECL(unsigned) pjsua_acc_get_count(void); -/***************************************************************************** - * PJSUA Core API +/** + * Check if the specified account ID is valid. + * + * @param acc_id Account ID to check. + * + * @return Non-zero if account ID is valid. */ +PJ_DECL(pj_bool_t) pjsua_acc_is_valid(pjsua_acc_id acc_id); /** - * Instantiate pjsua application. Application must call this function before - * calling any other functions, to make sure that the underlying libraries - * are properly initialized. Once this function has returned success, - * application must call pjsua_destroy() before quitting. + * Add a new account to pjsua. PJSUA must have been initialized (with + * #pjsua_init()) before calling this function. + * + * @param cfg Account configuration. + * @param is_default If non-zero, this account will be set as the default + * account. The default account will be used when sending + * outgoing requests (e.g. making call) when no account is + * specified, and when receiving incoming requests when the + * request does not match any accounts. It is recommended + * that default account is set to local/LAN account. + * @param p_acc_id Pointer to receive account ID of the new account. * * @return PJ_SUCCESS on success, or the appropriate error code. */ -PJ_DECL(pj_status_t) pjsua_create(void); +PJ_DECL(pj_status_t) pjsua_acc_add(const pjsua_acc_config *cfg, + pj_bool_t is_default, + pjsua_acc_id *p_acc_id); /** - * Initialize pjsua with the specified settings. All the settings are - * optional, and the default values will be used when the config is not - * specified. + * Add a local account. A local account is used to identify local endpoint + * instead of a specific user, and for this reason, a transport ID is needed + * to obtain the local address information. * - * @param ua_cfg User agent configuration. - * @param log_cfg Optional logging configuration. - * @param media_cfg Optional media configuration. + * @param tid Transport ID to generate account address. + * @param is_default If non-zero, this account will be set as the default + * account. The default account will be used when sending + * outgoing requests (e.g. making call) when no account is + * specified, and when receiving incoming requests when the + * request does not match any accounts. It is recommended + * that default account is set to local/LAN account. + * @param p_acc_id Pointer to receive account ID of the new account. * * @return PJ_SUCCESS on success, or the appropriate error code. */ -PJ_DECL(pj_status_t) pjsua_init(const pjsua_config *ua_cfg, - const pjsua_logging_config *log_cfg, - const pjsua_media_config *media_cfg); - +PJ_DECL(pj_status_t) pjsua_acc_add_local(pjsua_transport_id tid, + pj_bool_t is_default, + pjsua_acc_id *p_acc_id); /** - * Application is recommended to call this function after all initialization - * is done, so that the library can do additional checking set up - * additional + * Delete account. + * + * @param acc_id Id of the account to be deleted. * * @return PJ_SUCCESS on success, or the appropriate error code. */ -PJ_DECL(pj_status_t) pjsua_start(void); +PJ_DECL(pj_status_t) pjsua_acc_del(pjsua_acc_id acc_id); /** - * Destroy pjsua. This function must be called once PJSUA is created. To - * make it easier for application, application may call this function - * several times with no danger. + * Modify account information. + * + * @param acc_id Id of the account to be modified. + * @param cfg New account configuration. * * @return PJ_SUCCESS on success, or the appropriate error code. */ -PJ_DECL(pj_status_t) pjsua_destroy(void); +PJ_DECL(pj_status_t) pjsua_acc_modify(pjsua_acc_id acc_id, + const pjsua_acc_config *cfg); /** - * Poll pjsua for events, and if necessary block the caller thread for - * the specified maximum interval (in miliseconds). + * Modify account's presence status to be advertised to remote/presence + * subscribers. * - * @param msec_timeout Maximum time to wait, in miliseconds. + * @param acc_id The account ID. + * @param is_online True of false. * - * @return The number of events that have been handled during the - * poll. Negative value indicates error, and application - * can retrieve the error as (err = -return_value). + * @return PJ_SUCCESS on success, or the appropriate error code. */ -PJ_DECL(int) pjsua_handle_events(unsigned msec_timeout); +PJ_DECL(pj_status_t) pjsua_acc_set_online_status(pjsua_acc_id acc_id, + pj_bool_t is_online); /** - * Create memory pool. + * Update registration or perform unregistration. * - * @param name Optional pool name. - * @param size Initial size of the pool. - * @param increment Increment size. + * @param acc_id The account ID. + * @param renew If renew argument is zero, this will start + * unregistration process. * - * @return The pool, or NULL when there's no memory. + * @return PJ_SUCCESS on success, or the appropriate error code. */ -PJ_DECL(pj_pool_t*) pjsua_pool_create(const char *name, pj_size_t init_size, - pj_size_t increment); +PJ_DECL(pj_status_t) pjsua_acc_set_registration(pjsua_acc_id acc_id, + pj_bool_t renew); /** - * Application can call this function at any time (after pjsua_create(), of - * course) to change logging settings. + * Get account information. * - * @param c Logging configuration. + * @param acc_id Account identification. + * @param info Pointer to receive account information. * * @return PJ_SUCCESS on success, or the appropriate error code. */ -PJ_DECL(pj_status_t) pjsua_reconfigure_logging(const pjsua_logging_config *c); - +PJ_DECL(pj_status_t) pjsua_acc_get_info(pjsua_acc_id acc_id, + pjsua_acc_info *info); -/** - * Internal function to get SIP endpoint instance of pjsua, which is - * needed for example to register module, create transports, etc. - * Probably is only valid after #pjsua_init() is called. - * - * @return SIP endpoint instance. - */ -PJ_DECL(pjsip_endpoint*) pjsua_get_pjsip_endpt(void); /** - * Internal function to get media endpoint instance. - * Only valid after #pjsua_init() is called. + * Enum accounts all account ids. * - * @return Media endpoint instance. + * @param ids Array of account IDs to be initialized. + * @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. */ -PJ_DECL(pjmedia_endpt*) pjsua_get_pjmedia_endpt(void); - +PJ_DECL(pj_status_t) pjsua_enum_accs(pjsua_acc_id ids[], + unsigned *count ); -/***************************************************************************** - * PJSUA SIP Transport API. - */ /** - * Create SIP transport. + * Enum accounts info. * - * @param type Transport type. - * @param cfg Transport configuration. - * @param p_id Optional pointer to receive transport ID. + * @param info Array of account infos to be initialized. + * @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. */ -PJ_DECL(pj_status_t) pjsua_transport_create(pjsip_transport_type_e type, - const pjsua_transport_config *cfg, - pjsua_transport_id *p_id); +PJ_DECL(pj_status_t) pjsua_acc_enum_info( pjsua_acc_info info[], + unsigned *count ); + /** - * Register transport that has been created by application. + * This is an internal function to find the most appropriate account to + * used to reach to the specified URL. * - * @param tp Transport instance. - * @param p_id Optional pointer to receive transport ID. + * @param url The remote URL to reach. * - * @return PJ_SUCCESS on success, or the appropriate error code. + * @return Account id. */ -PJ_DECL(pj_status_t) pjsua_transport_register(pjsip_transport *tp, - pjsua_transport_id *p_id); +PJ_DECL(pjsua_acc_id) pjsua_acc_find_for_outgoing(const pj_str_t *url); /** - * Enumerate all transports currently created in the system. + * This is an internal function to find the most appropriate account to be + * used to handle incoming calls. * - * @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. + * @param rdata The incoming request message. * - * @return PJ_SUCCESS on success, or the appropriate error code. + * @return Account id. */ -PJ_DECL(pj_status_t) pjsua_enum_transports( pjsua_transport_id id[], - unsigned *count ); +PJ_DECL(pjsua_acc_id) pjsua_acc_find_for_incoming(pjsip_rx_data *rdata); + + + +/** + * @} + */ + + +/***************************************************************************** + * CALLS API + */ + + +/** + * @defgroup PJSUA_LIB_CALL Calls + * @ingroup PJSUA_LIB + * @brief Call manipulation. + * @{ + */ + +/** + * Max simultaneous calls. + */ +#ifndef PJSUA_MAX_CALLS +# define PJSUA_MAX_CALLS 32 +#endif + + + +/** + * Call media status. + */ +typedef enum pjsua_call_media_status +{ + PJSUA_CALL_MEDIA_NONE, + PJSUA_CALL_MEDIA_ACTIVE, + PJSUA_CALL_MEDIA_LOCAL_HOLD, + PJSUA_CALL_MEDIA_REMOTE_HOLD, +} pjsua_call_media_status; + + +/** + * Call info. + */ +typedef struct pjsua_call_info +{ + /** Call identification. */ + pjsua_call_id id; + + /** Initial call role (UAC == caller) */ + pjsip_role_e role; + + /** Local URI */ + pj_str_t local_info; + + /** Local Contact */ + pj_str_t local_contact; + + /** Remote URI */ + pj_str_t remote_info; + + /** Remote contact */ + pj_str_t remote_contact; + /** Dialog Call-ID string. */ + pj_str_t call_id; -/** - * 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. - */ -PJ_DECL(pj_status_t) pjsua_transport_get_info(pjsua_transport_id id, - pjsua_transport_info *info); + /** Call state */ + pjsip_inv_state state; + /** Text describing the state */ + pj_str_t state_text; -/** - * 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. - */ -PJ_DECL(pj_status_t) pjsua_transport_set_enable(pjsua_transport_id id, - pj_bool_t enabled); + /** Last status code heard, which can be used as cause code */ + pjsip_status_code last_status; + /** The reason phrase describing the status. */ + pj_str_t last_status_text; -/** - * 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. 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. - */ -PJ_DECL(pj_status_t) pjsua_transport_close( pjsua_transport_id id, - pj_bool_t force ); + /** Call media status. */ + pjsua_call_media_status media_status; + /** Media direction */ + pjmedia_dir media_dir; -/***************************************************************************** - * PJSUA Media Transport. - */ + /** The conference port number for the call */ + pjsua_conf_port_id conf_slot; -/** - * Create UDP media transports for all the calls. This function creates - * one UDP media transport for each call. - * - * @param cfg Media transport configuration. The "port" field in the - * configuration is used as the start port to bind the - * sockets. - * - * @return PJ_SUCCESS on success, or the appropriate error code. - */ -PJ_DECL(pj_status_t) -pjsua_media_transports_create(const pjsua_transport_config *cfg); + /** Up-to-date call connected duration (zero when call is not + * established) + */ + pj_time_val connect_duration; + /** Total call duration, including set-up time */ + pj_time_val total_duration; -/** - * Register custom media transports to be used by calls. There must - * enough media transports for all calls. - * - * @param tp The media transport array. - * @param count Number of elements in the array. This number MUST - * match the number of maximum calls configured when - * pjsua is created. - * @param auto_delete Flag to indicate whether the transports should be - * destroyed when pjsua is shutdown. - * - * @return PJ_SUCCESS on success, or the appropriate error code. - */ -PJ_DECL(pj_status_t) -pjsua_media_transports_attach( pjsua_media_transport tp[], - unsigned count, - pj_bool_t auto_delete); + /** Internal */ + struct { + char local_info[128]; + char local_contact[128]; + char remote_info[128]; + char remote_contact[128]; + char call_id[128]; + char last_status_text[128]; + } buf_; +} pjsua_call_info; -/***************************************************************************** - * PJSUA Call API. - */ /** * Get maximum number of calls configured in pjsua. @@ -1327,7 +1442,6 @@ PJ_DECL(pj_status_t) pjsua_enum_calls(pjsua_call_id ids[], * Make outgoing call to the specified URI using the specified account. * * @param acc_id The account to be used. - * @param target URI to be put in the request URI. * @param dst_uri URI to be put in the To header (normally is the same * as the target URI). * @param options Options (must be zero at the moment). @@ -1564,182 +1678,118 @@ PJ_DECL(pj_status_t) pjsua_call_dump(pjsua_call_id call_id, unsigned maxlen, const char *indent); - -/***************************************************************************** - * PJSUA Account and Client Registration API. - */ - - -/** - * Get number of current accounts. - * - * @return Current number of accounts. - */ -PJ_DECL(unsigned) pjsua_acc_get_count(void); - - -/** - * Check if the specified account ID is valid. - * - * @param acc_id Account ID to check. - * - * @return Non-zero if account ID is valid. - */ -PJ_DECL(pj_bool_t) pjsua_acc_is_valid(pjsua_acc_id acc_id); - - /** - * Add a new account to pjsua. PJSUA must have been initialized (with - * #pjsua_init()) before calling this function. - * - * @param cfg Account configuration. - * @param is_default If non-zero, this account will be set as the default - * account. The default account will be used when sending - * outgoing requests (e.g. making call) when no account is - * specified, and when receiving incoming requests when the - * request does not match any accounts. It is recommended - * that default account is set to local/LAN account. - * @param p_acc_id Pointer to receive account ID of the new account. - * - * @return PJ_SUCCESS on success, or the appropriate error code. + * @} */ -PJ_DECL(pj_status_t) pjsua_acc_add(const pjsua_acc_config *cfg, - pj_bool_t is_default, - pjsua_acc_id *p_acc_id); - -/** - * Add a local account. A local account is used to identify local endpoint - * instead of a specific user, and for this reason, a transport ID is needed - * to obtain the local address information. - * - * @param tid Transport ID to generate account address. - * @param is_default If non-zero, this account will be set as the default - * account. The default account will be used when sending - * outgoing requests (e.g. making call) when no account is - * specified, and when receiving incoming requests when the - * request does not match any accounts. It is recommended - * that default account is set to local/LAN account. - * @param p_acc_id Pointer to receive account ID of the new account. - * - * @return PJ_SUCCESS on success, or the appropriate error code. - */ -PJ_DECL(pj_status_t) pjsua_acc_add_local(pjsua_transport_id tid, - pj_bool_t is_default, - pjsua_acc_id *p_acc_id); -/** - * Delete account. - * - * @param acc_id Id of the account to be deleted. - * - * @return PJ_SUCCESS on success, or the appropriate error code. +/***************************************************************************** + * BUDDY API */ -PJ_DECL(pj_status_t) pjsua_acc_del(pjsua_acc_id acc_id); /** - * Modify account information. - * - * @param acc_id Id of the account to be modified. - * @param cfg New account configuration. - * - * @return PJ_SUCCESS on success, or the appropriate error code. + * @defgroup PJSUA_LIB_BUDDY Buddy, Presence, and Instant Messaging + * @ingroup PJSUA_LIB + * @brief Buddy management, buddy's presence, and instant messaging. + * @{ */ -PJ_DECL(pj_status_t) pjsua_acc_modify(pjsua_acc_id acc_id, - const pjsua_acc_config *cfg); - /** - * Modify account's presence status to be advertised to remote/presence - * subscribers. - * - * @param acc_id The account ID. - * @param is_online True of false. - * - * @return PJ_SUCCESS on success, or the appropriate error code. + * Max buddies in buddy list. */ -PJ_DECL(pj_status_t) pjsua_acc_set_online_status(pjsua_acc_id acc_id, - pj_bool_t is_online); +#ifndef PJSUA_MAX_BUDDIES +# define PJSUA_MAX_BUDDIES 256 +#endif /** - * Update registration or perform unregistration. - * - * @param acc_id The account ID. - * @param renew If renew argument is zero, this will start - * unregistration process. - * - * @return PJ_SUCCESS on success, or the appropriate error code. + * Buddy configuration. */ -PJ_DECL(pj_status_t) pjsua_acc_set_registration(pjsua_acc_id acc_id, - pj_bool_t renew); +typedef struct pjsua_buddy_config +{ + /** + * Buddy URL or name address. + */ + pj_str_t uri; + /** + * Specify whether presence subscription should start immediately. + */ + pj_bool_t subscribe; -/** - * Get account information. - * - * @param acc_id Account identification. - * @param info Pointer to receive account information. - * - * @return PJ_SUCCESS on success, or the appropriate error code. - */ -PJ_DECL(pj_status_t) pjsua_acc_get_info(pjsua_acc_id acc_id, - pjsua_acc_info *info); +} pjsua_buddy_config; /** - * Enum accounts all account ids. - * - * @param ids Array of account IDs to be initialized. - * @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. + * Buddy's online status. */ -PJ_DECL(pj_status_t) pjsua_enum_accs(pjsua_acc_id ids[], - unsigned *count ); +typedef enum pjsua_buddy_status +{ + /** + * Online status is unknown (possibly because no presence subscription + * has been established). + */ + PJSUA_BUDDY_STATUS_UNKNOWN, + /** + * Buddy is known to be offline. + */ + PJSUA_BUDDY_STATUS_ONLINE, -/** - * Enum accounts info. - * - * @param info Array of account infos to be initialized. - * @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. - */ -PJ_DECL(pj_status_t) pjsua_acc_enum_info( pjsua_acc_info info[], - unsigned *count ); + /** + * Buddy is offline. + */ + PJSUA_BUDDY_STATUS_OFFLINE, +} pjsua_buddy_status; -/** - * This is an internal function to find the most appropriate account to - * used to reach to the specified URL. - * - * @param url The remote URL to reach. - * - * @return Account id. - */ -PJ_DECL(pjsua_acc_id) pjsua_acc_find_for_outgoing(const pj_str_t *url); /** - * This is an internal function to find the most appropriate account to be - * used to handle incoming calls. - * - * @param rdata The incoming request message. - * - * @return Account id. + * Buddy info. */ -PJ_DECL(pjsua_acc_id) pjsua_acc_find_for_incoming(pjsip_rx_data *rdata); +typedef struct pjsua_buddy_info +{ + /** + * The buddy ID. + */ + pjsua_buddy_id id; + + /** + * The full URI of the buddy, as specified in the configuration. + */ + pj_str_t uri; + /** + * Buddy's Contact, only available when presence subscription has + * been established to the buddy. + */ + pj_str_t contact; + /** + * Buddy's online status. + */ + pjsua_buddy_status status; + + /** + * Text to describe buddy's online status. + */ + pj_str_t status_text; + + /** + * Flag to indicate that we should monitor the presence information for + * this buddy (normally yes, unless explicitly disabled). + */ + pj_bool_t monitor_pres; + + /** + * Internal buffer. + */ + char buf_[256]; + +} pjsua_buddy_info; -/***************************************************************************** - * PJSUA Presence (pjsua_pres.c) - */ /** * Get total number of buddies. @@ -1826,10 +1876,6 @@ PJ_DECL(pj_status_t) pjsua_buddy_subscribe_pres(pjsua_buddy_id buddy_id, PJ_DECL(void) pjsua_pres_dump(pj_bool_t verbose); -/***************************************************************************** - * PJSUA Instant Messaging (pjsua_im.c) - */ - /** * The MESSAGE method (defined in pjsua_im.c) */ @@ -1881,9 +1927,215 @@ PJ_DECL(pj_status_t) pjsua_im_typing(pjsua_acc_id acc_id, +/** + * @} + */ + + /***************************************************************************** - * Conference bridge manipulation. + * MEDIA API + */ + + +/** + * @defgroup PJSUA_LIB_MEDIA Media + * @ingroup PJSUA_LIB + * @brief Media manipulation. + * @{ + * + * PJSUA has rather powerful media features, which are built around the + * PJMEDIA conference bridge. Basically, all media termination (such as + * calls, file players, file recorders, sound device, tone generators, etc) + * are terminated in the conference bridge, and application can manipulate + * the interconnection between these terminations freely. If more than + * one media terminations are terminated in the same slot, the conference + * bridge will mix the signal automatically. + * + * Application connects one media termination/slot to another by calling + * #pjsua_conf_connect() function. This will establish unidirectional + * media flow from the source termination to the sink termination. For + * example, to stream a WAV file to remote call, application may use + * the following steps: + * + \code + + pj_status_t stream_to_call( pjsua_call_id call_id ) + { + pjsua_player_id player_id; + + status = pjsua_player_create("mysong.wav", 0, NULL, &player_id); + if (status != PJ_SUCCESS) + return status; + + status = pjsua_conf_connect( pjsua_player_get_conf_port(), + pjsua_call_get_conf_port() ); + } + \endcode + * + * + * Other features of PJSUA media: + * - efficient N to M interconnections between media terminations. + * - media termination can be connected to itself to create loopback + * media. + * - the media termination may have different clock rates, and resampling + * will be done automatically by conference bridge. + * - media terminations may also have different frame time; the + * conference bridge will perform the necessary bufferring to adjust + * the difference between terminations. + * - interconnections are removed automatically when media termination + * is removed from the bridge. + * - sound device may be changed even when there are active media + * interconnections. + * - correctly report call's media quality (in #pjsua_call_dump()) from + * RTCP packet exchange. + */ + +/** + * Max ports in the conference bridge. + */ +#ifndef PJSUA_MAX_CONF_PORTS +# define PJSUA_MAX_CONF_PORTS 254 +#endif + + + +/** + * Media configuration. + */ +struct pjsua_media_config +{ + /** + * Clock rate to be applied to the conference bridge. + * If value is zero, default clock rate will be used (16KHz). + */ + unsigned clock_rate; + + /** + * Specify maximum number of media ports to be created in the + * conference bridge. Since all media terminate in the bridge + * (calls, file player, file recorder, etc), the value must be + * large enough to support all of them. However, the larger + * the value, the more computations are performed. + */ + unsigned max_media_ports; + + /** + * Specify whether the media manager should manage its own + * ioqueue for the RTP/RTCP sockets. If yes, ioqueue will be created + * and at least one worker thread will be created too. If no, + * the RTP/RTCP sockets will share the same ioqueue as SIP sockets, + * and no worker thread is needed. + * + * Normally application would say yes here, unless it wants to + * run everything from a single thread. + */ + pj_bool_t has_ioqueue; + + /** + * Specify the number of worker threads to handle incoming RTP + * packets. A value of one is recommended for most applications. + */ + unsigned thread_cnt; + + +}; + + +/** + * Use this function to initialize media config. + * + * @param cfg The media config to be initialized. + */ +PJ_INLINE(void) pjsua_media_config_default(pjsua_media_config *cfg) +{ + pj_memset(cfg, 0, sizeof(*cfg)); + + cfg->clock_rate = 16000; + cfg->max_media_ports = 32; + cfg->has_ioqueue = PJ_TRUE; + cfg->thread_cnt = 1; +} + + + +/** + * Codec config. + */ +typedef struct pjsua_codec_info +{ + /** + * Codec unique identification. + */ + pj_str_t codec_id; + + /** + * Codec priority (integer 0-255). + */ + pj_uint8_t priority; + + /** + * Internal buffer. + */ + char buf_[32]; + +} pjsua_codec_info; + + +/** + * Conference port info. + */ +typedef struct pjsua_conf_port_info +{ + /** Conference port number. */ + pjsua_conf_port_id slot_id; + + /** Port name. */ + pj_str_t name; + + /** Clock rate. */ + unsigned clock_rate; + + /** Number of channels. */ + unsigned channel_count; + + /** Samples per frame */ + unsigned samples_per_frame; + + /** Bits per sample */ + unsigned bits_per_sample; + + /** Number of listeners in the array. */ + unsigned listener_cnt; + + /** Array of listeners (in other words, ports where this port is + * transmitting to. + */ + pjsua_conf_port_id listeners[PJSUA_MAX_CONF_PORTS]; + +} pjsua_conf_port_info; + + +/** + * This structure holds information about custom media transport to + * be registered to pjsua. */ +typedef struct pjsua_media_transport +{ + /** + * Media socket information containing the address information + * of the RTP and RTCP socket. + */ + pjmedia_sock_info skinfo; + + /** + * The media transport instance. + */ + pjmedia_transport *transport; + +} pjsua_media_transport; + + + /** * Get maxinum number of conference ports. @@ -1968,7 +2220,9 @@ PJ_DECL(pj_status_t) pjsua_conf_disconnect(pjsua_conf_port_id source, * the conference bridge. * * @param filename The filename to be played. Currently only - * WAV files are supported. + * WAV files are supported, and the WAV file MUST be + * formatted as 16bit PCM mono/single channel (any + * clock rate is supported). * @param options Options (currently zero). * @param user_data Arbitrary user data to be associated with the player. * @param p_id Pointer to receive player ID. @@ -2165,36 +2419,51 @@ PJ_DECL(pj_status_t) pjsua_codec_set_param( const pj_str_t *id, - -/***************************************************************************** - * Utilities. +/** + * Create UDP media transports for all the calls. This function creates + * one UDP media transport for each call. + * + * @param cfg Media transport configuration. The "port" field in the + * configuration is used as the start port to bind the + * sockets. * + * @return PJ_SUCCESS on success, or the appropriate error code. */ +PJ_DECL(pj_status_t) +pjsua_media_transports_create(const pjsua_transport_config *cfg); -/* - * Verify that valid SIP url is given. + +/** + * Register custom media transports to be used by calls. There must + * enough media transports for all calls. * - * @param c_url The URL, as NULL terminated string. + * @param tp The media transport array. + * @param count Number of elements in the array. This number MUST + * match the number of maximum calls configured when + * pjsua is created. + * @param auto_delete Flag to indicate whether the transports should be + * destroyed when pjsua is shutdown. * * @return PJ_SUCCESS on success, or the appropriate error code. */ -PJ_DECL(pj_status_t) pjsua_verify_sip_url(const char *c_url); +PJ_DECL(pj_status_t) +pjsua_media_transports_attach( pjsua_media_transport tp[], + unsigned count, + pj_bool_t auto_delete); /** - * Display error message for the specified error code. - * - * @param sender The log sender field. - * @param title Message title for the error. - * @param status Status code. + * @} */ -PJ_DECL(void) pjsua_perror(const char *sender, const char *title, - pj_status_t status); - PJ_END_DECL +/** + * @} + */ + + #endif /* __PJSUA_H__ */ -- cgit v1.2.3