Ignore:
Timestamp:
Jun 17, 2006 4:08:30 AM (18 years ago)
Author:
bennylp
Message:

Modifications all over the place, but mainly only to update Doxygen documentation

File:
1 edited

Legend:

Unmodified
Added
Removed

  • pjproject/trunk/pjsip/include/pjsua-lib/pjsua.h

    r503 r515  
    2020#define __PJSUA_H__ 
    2121 
     22/** 
     23 * @file pjsua.h 
     24 * @brief PJSUA API. 
     25 */ 
     26 
     27 
    2228/* Include all PJSIP core headers. */ 
    2329#include <pjsip.h> 
    … …  
    4248 
    4349 
     50/** 
     51 * @defgroup PJSUA_LIB PJSUA API 
     52 * @ingroup PJSIP 
     53 * @brief Very high level API for constructing SIP UA applications. 
     54 * @{ 
     55 * 
     56 * PJSUA API is very high level API for constructing SIP user agent 
     57 * applications. It wraps together the signaling and media functionalities 
     58 * into an easy to use call API, provides account management, buddy 
     59 * management, presence, instant messaging, along with multimedia 
     60 * features such as conferencing, file streaming, local playback, 
     61 * voice recording, and so on. 
     62 * 
     63 * Application must link with <b>pjsua-lib</b> to use this API. In addition, 
     64 * this library depends on the following libraries: 
     65 *  - <b>pjsip-ua</b>,  
     66 *  - <b>pjsip-simple</b>,  
     67 *  - <b>pjsip-core</b>,  
     68 *  - <b>pjmedia</b>, 
     69 *  - <b>pjmedia-codec</b>,  
     70 *  - <b>pjlib-util</b>, and 
     71 *  - <b>pjlib</b>,  
     72 * 
     73 * so application must also link with these libraries as well. 
     74 * 
     75 * @section root_using_pjsua_lib Using PJSUA API 
     76 * 
     77 * Please refer to @ref using_pjsua_lib on how to use PJSUA API. 
     78 */  
     79 
    4480PJ_BEGIN_DECL 
    4581 
    4682 
    47 /** 
    48  * Max buddies in buddy list. 
    49  */ 
    50 #ifndef PJSUA_MAX_BUDDIES 
    51 #   define PJSUA_MAX_BUDDIES        256 
    52 #endif 
    53  
    54  
    55 /** 
    56  * Max simultaneous calls. 
    57  */ 
    58 #ifndef PJSUA_MAX_CALLS 
    59 #   define PJSUA_MAX_CALLS          32 
    60 #endif 
    61  
    62  
    63 /** 
    64  * Max ports in the conference bridge. 
    65  */ 
    66 #ifndef PJSUA_MAX_CONF_PORTS 
    67 #   define PJSUA_MAX_CONF_PORTS     254 
    68 #endif 
    69  
    70  
    71 /** 
    72  * Maximum accounts. 
    73  */ 
    74 #ifndef PJSUA_MAX_ACC 
    75 #   define PJSUA_MAX_ACC            8 
    76 #endif 
     83/** Forward declaration */ 
     84typedef struct pjsua_media_config pjsua_media_config; 
     85 
     86 
     87/***************************************************************************** 
     88 * BASE API 
     89 */ 
     90 
     91/** 
     92 * @defgroup PJSUA_LIB_BASE Base API 
     93 * @ingroup PJSUA_LIB 
     94 * @brief Basic application creation/initialization, logging configuration, etc. 
     95 * @{ 
     96 * 
     97 * The base PJSUA API controls PJSUA creation, initialization, and startup, and 
     98 * also provides various auxiliary functions. 
     99 * 
     100 * @section using_pjsua_lib Using PJSUA Library 
     101 * 
     102 * @subsection creating_pjsua_lib Creating PJSUA 
     103 * 
     104 * Before anything else, application must create PJSUA by calling #pjsua_create(). 
     105 * This, among other things, will initialize PJLIB, which is crucial before  
     106 * any PJLIB functions can be called. 
     107 * 
     108 * @subsection init_pjsua_lib Initializing PJSUA 
     109 * 
     110 * After PJSUA is created, application can initialize PJSUA by calling 
     111 * #pjsua_init(). This function takes several configuration settings in the 
     112 * argument, so application normally would want to set these configuration 
     113 * before passing them to #pjsua_init(). 
     114 * 
     115 * Sample code to initialize PJSUA: 
     116 \code 
     117 
     118    pjsua_config         ua_cfg; 
     119    pjsua_logging_config log_cfg; 
     120    pjsua_media_config   media_cfg; 
     121 
     122    // Initialize configs with default settings. 
     123    pjsua_config_default(&ua_cfg); 
     124    pjsua_logging_config_default(&log_cfg); 
     125    pjsua_media_config_default(&media_cfg); 
     126 
     127    // At the very least, application would want to override 
     128    // the call callbacks in pjsua_config: 
     129    ua_cfg.cb.on_incoming_call = ... 
     130    ua_cfg.cb.on_call_state = .. 
     131    ... 
     132 
     133    // Customize other settings (or initialize them from application specific 
     134    // configuration file): 
     135    ... 
     136 
     137    // Initialize pjsua 
     138    status = pjsua_init(&ua_cfg, &log_cfg, &media_cfg); 
     139    if (status != PJ_SUCCESS) { 
     140          pjsua_perror(THIS_FILE, "Error initializing pjsua", status); 
     141          return status; 
     142    } 
     143    .. 
     144 
     145 \endcode 
     146 * 
     147 * @subsection other_init_pjsua_lib Other Initialization 
     148 * 
     149 * After PJSUA is initialized with #pjsua_init(), application will normally 
     150 * need/want to perform the following tasks: 
     151 * 
     152 *  - create SIP transport with #pjsua_transport_create(). Please see 
     153 *    @ref PJSUA_LIB_TRANSPORT section for more info. 
     154 *  - create one or more SIP accounts with #pjsua_acc_add() or 
     155 *    #pjsua_acc_add_local(). Please see @ref PJSUA_LIB_ACC for more info. 
     156 *  - add one or more buddies with #pjsua_buddy_add(). Please see 
     157 *    @ref PJSUA_LIB_BUDDY section for more info. 
     158 *  - optionally configure the sound device, codec settings, and other 
     159 *    media settings. Please see @ref PJSUA_LIB_MEDIA for more info. 
     160 * 
     161 * 
     162 * @subsection starting_pjsua_lib Starting PJSUA 
     163 * 
     164 * After all initializations have been done, application must call 
     165 * #pjsua_start() to start PJSUA. This function will check that all settings 
     166 * are properly configured, and apply default settings when it's not, or 
     167 * report error status when it is unable to recover from missing setting. 
     168 * 
     169 * Most settings can be changed during run-time. For example, application 
     170 * may add, modify, or delete accounts, buddies, or change media settings 
     171 * during run-time. 
     172 */ 
     173 
     174/** Constant to identify invalid ID for all sorts of IDs. */ 
     175#define PJSUA_INVALID_ID            (-1) 
     176 
     177/** Call identification */ 
     178typedef int pjsua_call_id; 
     179 
     180/** Account identification */ 
     181typedef int pjsua_acc_id; 
     182 
     183/** Buddy identification */ 
     184typedef int pjsua_buddy_id; 
     185 
     186/** File player identification */ 
     187typedef int pjsua_player_id; 
     188 
     189/** File recorder identification */ 
     190typedef int pjsua_recorder_id; 
     191 
     192/** Conference port identification */ 
     193typedef int pjsua_conf_port_id; 
     194 
    77195 
    78196 
    … …  
    83201#   define PJSUA_ACC_MAX_PROXIES    8 
    84202#endif 
    85  
    86 /** 
    87  * Default registration interval. 
    88  */ 
    89 #ifndef PJSUA_REG_INTERVAL 
    90 #   define PJSUA_REG_INTERVAL       55 
    91 #endif 
    92  
    93  
    94 /** Account identification */ 
    95 typedef int pjsua_acc_id; 
    96  
    97 /** Call identification */ 
    98 typedef int pjsua_call_id; 
    99  
    100 /** SIP transport identification */ 
    101 typedef int pjsua_transport_id; 
    102  
    103 /** Buddy identification */ 
    104 typedef int pjsua_buddy_id; 
    105  
    106 /** File player identification */ 
    107 typedef int pjsua_player_id; 
    108  
    109 /** File recorder identification */ 
    110 typedef int pjsua_recorder_id; 
    111  
    112 /** Conference port identification */ 
    113 typedef int pjsua_conf_port_id; 
    114  
    115  
    116 /** Constant to identify invalid ID for all sorts of IDs. */ 
    117 #define PJSUA_INVALID_ID            (-1) 
    118  
    119  
    120  
    121 /** 
    122  * Account configuration. 
    123  */ 
    124 typedef struct pjsua_acc_config 
    125 { 
    126     /**  
    127      * The full SIP URL for the account. The value can take name address or  
    128      * URL format, and will look something like "sip:account@serviceprovider". 
    129      * 
    130      * This field is mandatory. 
    131      */ 
    132     pj_str_t        id; 
    133  
    134     /**  
    135      * This is the URL to be put in the request URI for the registration, 
    136      * and will look something like "sip:serviceprovider". 
    137      * 
    138      * This field should be specified if registration is desired. If the 
    139      * value is empty, no account registration will be performed. 
    140      */ 
    141     pj_str_t        reg_uri; 
    142  
    143     /**  
    144      * Optional URI to be put as Contact for this account. It is recommended 
    145      * that this field is left empty, so that the value will be calculated 
    146      * automatically based on the transport address. 
    147      */ 
    148     pj_str_t        contact; 
    149  
    150     /** 
    151      * Number of proxies in the proxy array below. 
    152      */ 
    153     unsigned        proxy_cnt; 
    154  
    155     /**  
    156      * Optional URI of the proxies to be visited for all outgoing requests  
    157      * that are using this account (REGISTER, INVITE, etc). Application need  
    158      * to specify these proxies if the service provider requires that requests 
    159      * destined towards its network should go through certain proxies first 
    160      * (for example, border controllers). 
    161      * 
    162      * These proxies will be put in the route set for this account, with  
    163      * maintaining the orders (the first proxy in the array will be visited 
    164      * first). 
    165      */ 
    166     pj_str_t        proxy[PJSUA_ACC_MAX_PROXIES]; 
    167  
    168     /**  
    169      * Optional interval for registration, in seconds. If the value is zero,  
    170      * default interval will be used (PJSUA_REG_INTERVAL, 55 seconds). 
    171      */ 
    172     unsigned        reg_timeout; 
    173  
    174     /**  
    175      * Number of credentials in the credential array. 
    176      */ 
    177     unsigned        cred_count; 
    178  
    179     /**  
    180      * Array of credentials. If registration is desired, normally there should 
    181      * be at least one credential specified, to successfully authenticate 
    182      * against the service provider. More credentials can be specified, for 
    183      * example when the requests are expected to be challenged by the 
    184      * proxies in the route set. 
    185      */ 
    186     pjsip_cred_info cred_info[PJSUA_ACC_MAX_PROXIES]; 
    187  
    188 } pjsua_acc_config; 
    189  
    190  
    191 /** 
    192  * Call this function to initialize account config with default values. 
    193  * 
    194  * @param cfg       The account config to be initialized. 
    195  */ 
    196 PJ_INLINE(void) pjsua_acc_config_default(pjsua_acc_config *cfg) 
    197 { 
    198     pj_memset(cfg, 0, sizeof(*cfg)); 
    199  
    200     cfg->reg_timeout = PJSUA_REG_INTERVAL; 
    201 } 
    202  
    203  
    204  
    205 /** 
    206  * Account info. Application can query account info by calling  
    207  * #pjsua_acc_get_info(). 
    208  */ 
    209 typedef struct pjsua_acc_info 
    210 { 
    211     /**  
    212      * The account ID.  
    213      */ 
    214     pjsua_acc_id        id; 
    215  
    216     /** 
    217      * Flag to indicate whether this is the default account. 
    218      */ 
    219     pj_bool_t           is_default; 
    220  
    221     /**  
    222      * Account URI  
    223      */ 
    224     pj_str_t            acc_uri; 
    225  
    226     /**  
    227      * Flag to tell whether this account has registration setting 
    228      * (reg_uri is not empty). 
    229      */ 
    230     pj_bool_t           has_registration; 
    231  
    232     /** 
    233      * An up to date expiration interval for account registration session. 
    234      */ 
    235     int                 expires; 
    236  
    237     /** 
    238      * Last registration status code. If status code is zero, the account 
    239      * is currently not registered. Any other value indicates the SIP 
    240      * status code of the registration. 
    241      */ 
    242     pjsip_status_code   status; 
    243  
    244     /** 
    245      * String describing the registration status. 
    246      */ 
    247     pj_str_t            status_text; 
    248  
    249     /** 
    250      * Presence online status for this account. 
    251      */ 
    252     pj_bool_t           online_status; 
    253  
    254     /** 
    255      * Buffer that is used internally to store the status text. 
    256      */ 
    257     char                buf_[PJ_ERR_MSG_SIZE]; 
    258  
    259 } pjsua_acc_info; 
    260  
    261  
    262  
    263 /** 
    264  * STUN configuration. 
    265  */ 
    266 typedef struct pjsua_stun_config 
    267 { 
    268     /** 
    269      * The first STUN server IP address or hostname. 
    270      */ 
    271     pj_str_t    stun_srv1; 
    272  
    273     /** 
    274      * Port number of the first STUN server. 
    275      * If zero, default STUN port will be used. 
    276      */ 
    277     unsigned    stun_port1; 
    278      
    279     /** 
    280      * Optional second STUN server IP address or hostname, for which the 
    281      * result of the mapping request will be compared to. If the value 
    282      * is empty, only one STUN server will be used. 
    283      */ 
    284     pj_str_t    stun_srv2; 
    285  
    286     /** 
    287      * Port number of the second STUN server. 
    288      * If zero, default STUN port will be used. 
    289      */ 
    290     unsigned    stun_port2; 
    291  
    292 } pjsua_stun_config; 
    293  
    294  
    295  
    296 /** 
    297  * Call this function to initialize STUN config with default values. 
    298  * 
    299  * @param cfg       The STUN config to be initialized. 
    300  */ 
    301 PJ_INLINE(void) pjsua_stun_config_default(pjsua_stun_config *cfg) 
    302 { 
    303     pj_memset(cfg, 0, sizeof(*cfg)); 
    304 } 
    305  
    306  
    307 /** 
    308  * Transport configuration for creating UDP transports for both SIP 
    309  * and media. 
    310  */ 
    311 typedef struct pjsua_transport_config 
    312 { 
    313     /** 
    314      * UDP port number to bind locally. This setting MUST be specified 
    315      * even when default port is desired. If the value is zero, the 
    316      * transport will be bound to any available port, and application 
    317      * can query the port by querying the transport info. 
    318      */ 
    319     unsigned            port; 
    320  
    321     /** 
    322      * Optional address where the socket should be bound. 
    323      */ 
    324     pj_in_addr          ip_addr; 
    325  
    326     /** 
    327      * Flag to indicate whether STUN should be used. 
    328      */ 
    329     pj_bool_t           use_stun; 
    330  
    331     /** 
    332      * STUN configuration, must be specified when STUN is used. 
    333      */ 
    334     pjsua_stun_config   stun_config; 
    335  
    336 } pjsua_transport_config; 
    337  
    338  
    339 /** 
    340  * Call this function to initialize UDP config with default values. 
    341  * 
    342  * @param cfg       The UDP config to be initialized. 
    343  */ 
    344 PJ_INLINE(void) pjsua_transport_config_default(pjsua_transport_config *cfg) 
    345 { 
    346     pj_memset(cfg, 0, sizeof(*cfg)); 
    347 } 
    348  
    349  
    350 /** 
    351  * Normalize STUN config. 
    352  */ 
    353 PJ_INLINE(void) pjsua_normalize_stun_config( pjsua_stun_config *cfg ) 
    354 { 
    355     if (cfg->stun_srv1.slen) { 
    356  
    357         if (cfg->stun_port1 == 0) 
    358             cfg->stun_port1 = 3478; 
    359  
    360         if (cfg->stun_srv2.slen == 0) { 
    361             cfg->stun_srv2 = cfg->stun_srv1; 
    362             cfg->stun_port2 = cfg->stun_port1; 
    363         } else { 
    364             if (cfg->stun_port2 == 0) 
    365                 cfg->stun_port2 = 3478; 
    366         } 
    367  
    368     } else { 
    369         cfg->stun_port1 = 0; 
    370         cfg->stun_srv2.slen = 0; 
    371         cfg->stun_port2 = 0; 
    372     } 
    373 } 
    374  
    375  
    376 /** 
    377  * Duplicate transport config. 
    378  */ 
    379 PJ_INLINE(void) pjsua_transport_config_dup(pj_pool_t *pool, 
    380                                            pjsua_transport_config *dst, 
    381                                            const pjsua_transport_config *src) 
    382 { 
    383     pj_memcpy(dst, src, sizeof(*src)); 
    384  
    385     if (src->stun_config.stun_srv1.slen) { 
    386         pj_strdup_with_null(pool, &dst->stun_config.stun_srv1, 
    387                             &src->stun_config.stun_srv1); 
    388     } 
    389  
    390     if (src->stun_config.stun_srv2.slen) { 
    391         pj_strdup_with_null(pool, &dst->stun_config.stun_srv2, 
    392                             &src->stun_config.stun_srv2); 
    393     } 
    394  
    395     pjsua_normalize_stun_config(&dst->stun_config); 
    396 } 
    397  
    398  
    399  
    400 /** 
    401  * Transport info. 
    402  */ 
    403 typedef struct pjsua_transport_info 
    404 { 
    405     /** 
    406      * PJSUA transport identification. 
    407      */ 
    408     pjsua_transport_id      id; 
    409  
    410     /** 
    411      * Transport type. 
    412      */ 
    413     pjsip_transport_type_e  type; 
    414  
    415     /** 
    416      * Transport type name. 
    417      */ 
    418     pj_str_t                type_name; 
    419  
    420     /** 
    421      * Transport string info/description. 
    422      */ 
    423     pj_str_t                info; 
    424  
    425     /** 
    426      * Transport flag (see ##pjsip_transport_flags_e). 
    427      */ 
    428     unsigned                flag; 
    429  
    430     /** 
    431      * Local address length. 
    432      */ 
    433     unsigned                addr_len; 
    434  
    435     /** 
    436      * Local/bound address. 
    437      */ 
    438     pj_sockaddr             local_addr; 
    439  
    440     /** 
    441      * Published address (or transport address name). 
    442      */ 
    443     pjsip_host_port         local_name; 
    444  
    445     /** 
    446      * Current number of objects currently referencing this transport. 
    447      */ 
    448     unsigned                usage_count; 
    449  
    450  
    451 } pjsua_transport_info; 
    452  
    453  
    454 /** 
    455  * Media configuration. 
    456  */ 
    457 typedef struct pjsua_media_config 
    458 { 
    459     /** 
    460      * Clock rate to be applied to the conference bridge. 
    461      * If value is zero, default clock rate will be used (16KHz). 
    462      */ 
    463     unsigned            clock_rate; 
    464  
    465     /** 
    466      * Specify maximum number of media ports to be created in the 
    467      * conference bridge. Since all media terminate in the bridge 
    468      * (calls, file player, file recorder, etc), the value must be 
    469      * large enough to support all of them. However, the larger 
    470      * the value, the more computations are performed. 
    471      */ 
    472     unsigned            max_media_ports; 
    473  
    474     /** 
    475      * Specify whether the media manager should manage its own 
    476      * ioqueue for the RTP/RTCP sockets. If yes, ioqueue will be created 
    477      * and at least one worker thread will be created too. If no, 
    478      * the RTP/RTCP sockets will share the same ioqueue as SIP sockets, 
    479      * and no worker thread is needed. 
    480      * 
    481      * Normally application would say yes here, unless it wants to 
    482      * run everything from a single thread. 
    483      */ 
    484     pj_bool_t           has_ioqueue; 
    485  
    486     /** 
    487      * Specify the number of worker threads to handle incoming RTP 
    488      * packets. A value of one is recommended for most applications. 
    489      */ 
    490     unsigned            thread_cnt; 
    491  
    492  
    493 } pjsua_media_config; 
    494  
    495  
    496 /** 
    497  * Use this function to initialize media config. 
    498  * 
    499  * @param cfg   The media config to be initialized. 
    500  */ 
    501 PJ_INLINE(void) pjsua_media_config_default(pjsua_media_config *cfg) 
    502 { 
    503     pj_memset(cfg, 0, sizeof(*cfg)); 
    504  
    505     cfg->clock_rate = 16000; 
    506     cfg->max_media_ports = 32; 
    507     cfg->has_ioqueue = PJ_TRUE; 
    508     cfg->thread_cnt = 1; 
    509 } 
    510203 
    511204 
    … …  
    583276} 
    584277 
    585  
    586 /** 
    587  * Buddy configuration. 
    588  */ 
    589 typedef struct pjsua_buddy_config 
    590 { 
    591     /** 
    592      * Buddy URL or name address. 
    593      */ 
    594     pj_str_t    uri; 
    595  
    596     /** 
    597      * Specify whether presence subscription should start immediately. 
    598      */ 
    599     pj_bool_t   subscribe; 
    600  
    601 } pjsua_buddy_config; 
    602  
    603  
    604 /** 
    605  * Buddy's online status. 
    606  */ 
    607 typedef enum pjsua_buddy_status 
    608 { 
    609     /** 
    610      * Online status is unknown (possibly because no presence subscription 
    611      * has been established). 
    612      */ 
    613     PJSUA_BUDDY_STATUS_UNKNOWN, 
    614  
    615     /** 
    616      * Buddy is known to be offline. 
    617      */ 
    618     PJSUA_BUDDY_STATUS_ONLINE, 
    619  
    620     /** 
    621      * Buddy is offline. 
    622      */ 
    623     PJSUA_BUDDY_STATUS_OFFLINE, 
    624  
    625 } pjsua_buddy_status; 
    626  
    627  
    628  
    629 /** 
    630  * Buddy info. 
    631  */ 
    632 typedef struct pjsua_buddy_info 
    633 { 
    634     /** 
    635      * The buddy ID. 
    636      */ 
    637     pjsua_buddy_id      id; 
    638  
    639     /** 
    640      * The full URI of the buddy, as specified in the configuration. 
    641      */ 
    642     pj_str_t            uri; 
    643  
    644     /** 
    645      * Buddy's Contact, only available when presence subscription has 
    646      * been established to the buddy. 
    647      */ 
    648     pj_str_t            contact; 
    649  
    650     /** 
    651      * Buddy's online status. 
    652      */ 
    653     pjsua_buddy_status  status; 
    654  
    655     /** 
    656      * Text to describe buddy's online status. 
    657      */ 
    658     pj_str_t            status_text; 
    659  
    660     /** 
    661      * Flag to indicate that we should monitor the presence information for 
    662      * this buddy (normally yes, unless explicitly disabled). 
    663      */ 
    664     pj_bool_t           monitor_pres; 
    665  
    666     /** 
    667      * Internal buffer. 
    668      */ 
    669     char                buf_[256]; 
    670  
    671 } pjsua_buddy_info; 
    672  
    673  
    674 /** 
    675  * Codec config. 
    676  */ 
    677 typedef struct pjsua_codec_info 
    678 { 
    679     /** 
    680      * Codec unique identification. 
    681      */ 
    682     pj_str_t            codec_id; 
    683  
    684     /** 
    685      * Codec priority (integer 0-255). 
    686      */ 
    687     pj_uint8_t          priority; 
    688  
    689     /** 
    690      * Internal buffer. 
    691      */ 
    692     char                buf_[32]; 
    693  
    694 } pjsua_codec_info; 
    695278 
    696279 
    … …  
    889472 
    890473 
     474 
     475/** 
     476 * This structure describes additional information to be sent with 
     477 * outgoing SIP message. 
     478 */ 
     479typedef struct pjsua_msg_data 
     480{ 
     481    /** 
     482     * Additional message headers as linked list. 
     483     */ 
     484    pjsip_hdr   hdr_list; 
     485 
     486    /** 
     487     * MIME type of optional message body.  
     488     */ 
     489    pj_str_t    content_type; 
     490 
     491    /** 
     492     * Optional message body. 
     493     */ 
     494    pj_str_t    msg_body; 
     495 
     496} pjsua_msg_data; 
     497 
     498 
     499/** 
     500 * Initialize message data. 
     501 * 
     502 * @param msg_data  Message data to be initialized. 
     503 */ 
     504PJ_INLINE(void) pjsua_msg_data_init(pjsua_msg_data *msg_data) 
     505{ 
     506    pj_memset(msg_data, 0, sizeof(*msg_data)); 
     507    pj_list_init(&msg_data->hdr_list); 
     508} 
     509 
     510 
     511 
     512/** 
     513 * Instantiate pjsua application. Application must call this function before 
     514 * calling any other functions, to make sure that the underlying libraries 
     515 * are properly initialized. Once this function has returned success, 
     516 * application must call pjsua_destroy() before quitting. 
     517 * 
     518 * @return              PJ_SUCCESS on success, or the appropriate error code. 
     519 */ 
     520PJ_DECL(pj_status_t) pjsua_create(void); 
     521 
     522 
     523/** 
     524 * Initialize pjsua with the specified settings. All the settings are  
     525 * optional, and the default values will be used when the config is not 
     526 * specified. 
     527 * 
     528 * @param ua_cfg        User agent configuration. 
     529 * @param log_cfg       Optional logging configuration. 
     530 * @param media_cfg     Optional media configuration. 
     531 * 
     532 * @return              PJ_SUCCESS on success, or the appropriate error code. 
     533 */ 
     534PJ_DECL(pj_status_t) pjsua_init(const pjsua_config *ua_cfg, 
     535                                const pjsua_logging_config *log_cfg, 
     536                                const pjsua_media_config *media_cfg); 
     537 
     538 
     539/** 
     540 * Application is recommended to call this function after all initialization 
     541 * is done, so that the library can do additional checking set up 
     542 * additional  
     543 * 
     544 * @return              PJ_SUCCESS on success, or the appropriate error code. 
     545 */ 
     546PJ_DECL(pj_status_t) pjsua_start(void); 
     547 
     548 
     549/** 
     550 * Destroy pjsua. This function must be called once PJSUA is created. To 
     551 * make it easier for application, application may call this function 
     552 * several times with no danger. 
     553 * 
     554 * @return              PJ_SUCCESS on success, or the appropriate error code. 
     555 */ 
     556PJ_DECL(pj_status_t) pjsua_destroy(void); 
     557 
     558 
     559/** 
     560 * Poll pjsua for events, and if necessary block the caller thread for 
     561 * the specified maximum interval (in miliseconds). 
     562 * 
     563 * @param msec_timeout  Maximum time to wait, in miliseconds. 
     564 * 
     565 * @return  The number of events that have been handled during the 
     566 *          poll. Negative value indicates error, and application 
     567 *          can retrieve the error as (err = -return_value). 
     568 */ 
     569PJ_DECL(int) pjsua_handle_events(unsigned msec_timeout); 
     570 
     571 
     572/** 
     573 * Create memory pool. 
     574 * 
     575 * @param name          Optional pool name. 
     576 * @param init_size     Initial size of the pool. 
     577 * @param increment     Increment size. 
     578 * 
     579 * @return              The pool, or NULL when there's no memory. 
     580 */ 
     581PJ_DECL(pj_pool_t*) pjsua_pool_create(const char *name, pj_size_t init_size, 
     582                                      pj_size_t increment); 
     583 
     584 
     585/** 
     586 * Application can call this function at any time (after pjsua_create(), of 
     587 * course) to change logging settings. 
     588 * 
     589 * @param c             Logging configuration. 
     590 * 
     591 * @return              PJ_SUCCESS on success, or the appropriate error code. 
     592 */ 
     593PJ_DECL(pj_status_t) pjsua_reconfigure_logging(const pjsua_logging_config *c); 
     594 
     595 
     596/** 
     597 * Internal function to get SIP endpoint instance of pjsua, which is 
     598 * needed for example to register module, create transports, etc. 
     599 * Probably is only valid after #pjsua_init() is called. 
     600 *  
     601 * @return              SIP endpoint instance. 
     602 */ 
     603PJ_DECL(pjsip_endpoint*) pjsua_get_pjsip_endpt(void); 
     604 
     605/** 
     606 * Internal function to get media endpoint instance. 
     607 * Only valid after #pjsua_init() is called. 
     608 * 
     609 * @return              Media endpoint instance. 
     610 */ 
     611PJ_DECL(pjmedia_endpt*) pjsua_get_pjmedia_endpt(void); 
     612 
     613 
     614/***************************************************************************** 
     615 * Utilities. 
     616 * 
     617 */ 
     618 
     619/** 
     620 * Verify that valid SIP url is given. 
     621 * 
     622 * @param c_url         The URL, as NULL terminated string. 
     623 * 
     624 * @return              PJ_SUCCESS on success, or the appropriate error code. 
     625 */ 
     626PJ_DECL(pj_status_t) pjsua_verify_sip_url(const char *c_url); 
     627 
     628 
     629/** 
     630 * Display error message for the specified error code. 
     631 * 
     632 * @param sender        The log sender field. 
     633 * @param title         Message title for the error. 
     634 * @param status        Status code. 
     635 */ 
     636PJ_DECL(void) pjsua_perror(const char *sender, const char *title,  
     637                           pj_status_t status); 
     638 
     639 
     640 
     641 
     642/** 
     643 * @} 
     644 */ 
     645 
     646 
     647 
     648/***************************************************************************** 
     649 * TRANSPORT API 
     650 */ 
     651 
     652/** 
     653 * @defgroup PJSUA_LIB_TRANSPORT Signaling Transport 
     654 * @ingroup PJSUA_LIB 
     655 * @brief API for managing SIP transports 
     656 * @{ 
     657 * SIP transport must be created before adding an account. SIP transport is 
     658 * created by calling #pjsua_transport_create() function. 
     659 */ 
     660 
     661 
     662/** SIP transport identification */ 
     663typedef int pjsua_transport_id; 
     664 
     665 
     666/** 
     667 * STUN configuration. 
     668 */ 
     669typedef struct pjsua_stun_config 
     670{ 
     671    /** 
     672     * The first STUN server IP address or hostname. 
     673     */ 
     674    pj_str_t    stun_srv1; 
     675 
     676    /** 
     677     * Port number of the first STUN server. 
     678     * If zero, default STUN port will be used. 
     679     */ 
     680    unsigned    stun_port1; 
     681     
     682    /** 
     683     * Optional second STUN server IP address or hostname, for which the 
     684     * result of the mapping request will be compared to. If the value 
     685     * is empty, only one STUN server will be used. 
     686     */ 
     687    pj_str_t    stun_srv2; 
     688 
     689    /** 
     690     * Port number of the second STUN server. 
     691     * If zero, default STUN port will be used. 
     692     */ 
     693    unsigned    stun_port2; 
     694 
     695} pjsua_stun_config; 
     696 
     697 
     698 
     699/** 
     700 * Call this function to initialize STUN config with default values. 
     701 * 
     702 * @param cfg       The STUN config to be initialized. 
     703 */ 
     704PJ_INLINE(void) pjsua_stun_config_default(pjsua_stun_config *cfg) 
     705{ 
     706    pj_memset(cfg, 0, sizeof(*cfg)); 
     707} 
     708 
     709 
     710/** 
     711 * Transport configuration for creating UDP transports for both SIP 
     712 * and media. 
     713 */ 
     714typedef struct pjsua_transport_config 
     715{ 
     716    /** 
     717     * UDP port number to bind locally. This setting MUST be specified 
     718     * even when default port is desired. If the value is zero, the 
     719     * transport will be bound to any available port, and application 
     720     * can query the port by querying the transport info. 
     721     */ 
     722    unsigned            port; 
     723 
     724    /** 
     725     * Optional address where the socket should be bound. 
     726     */ 
     727    pj_in_addr          ip_addr; 
     728 
     729    /** 
     730     * Flag to indicate whether STUN should be used. 
     731     */ 
     732    pj_bool_t           use_stun; 
     733 
     734    /** 
     735     * STUN configuration, must be specified when STUN is used. 
     736     */ 
     737    pjsua_stun_config   stun_config; 
     738 
     739} pjsua_transport_config; 
     740 
     741 
     742/** 
     743 * Call this function to initialize UDP config with default values. 
     744 * 
     745 * @param cfg       The UDP config to be initialized. 
     746 */ 
     747PJ_INLINE(void) pjsua_transport_config_default(pjsua_transport_config *cfg) 
     748{ 
     749    pj_memset(cfg, 0, sizeof(*cfg)); 
     750} 
     751 
     752 
     753/** 
     754 * Normalize STUN config. 
     755 */ 
     756PJ_INLINE(void) pjsua_normalize_stun_config( pjsua_stun_config *cfg ) 
     757{ 
     758    if (cfg->stun_srv1.slen) { 
     759 
     760        if (cfg->stun_port1 == 0) 
     761            cfg->stun_port1 = 3478; 
     762 
     763        if (cfg->stun_srv2.slen == 0) { 
     764            cfg->stun_srv2 = cfg->stun_srv1; 
     765            cfg->stun_port2 = cfg->stun_port1; 
     766        } else { 
     767            if (cfg->stun_port2 == 0) 
     768                cfg->stun_port2 = 3478; 
     769        } 
     770 
     771    } else { 
     772        cfg->stun_port1 = 0; 
     773        cfg->stun_srv2.slen = 0; 
     774        cfg->stun_port2 = 0; 
     775    } 
     776} 
     777 
     778 
     779/** 
     780 * Duplicate transport config. 
     781 */ 
     782PJ_INLINE(void) pjsua_transport_config_dup(pj_pool_t *pool, 
     783                                           pjsua_transport_config *dst, 
     784                                           const pjsua_transport_config *src) 
     785{ 
     786    pj_memcpy(dst, src, sizeof(*src)); 
     787 
     788    if (src->stun_config.stun_srv1.slen) { 
     789        pj_strdup_with_null(pool, &dst->stun_config.stun_srv1, 
     790                            &src->stun_config.stun_srv1); 
     791    } 
     792 
     793    if (src->stun_config.stun_srv2.slen) { 
     794        pj_strdup_with_null(pool, &dst->stun_config.stun_srv2, 
     795                            &src->stun_config.stun_srv2); 
     796    } 
     797 
     798    pjsua_normalize_stun_config(&dst->stun_config); 
     799} 
     800 
     801 
     802 
     803/** 
     804 * Transport info. 
     805 */ 
     806typedef struct pjsua_transport_info 
     807{ 
     808    /** 
     809     * PJSUA transport identification. 
     810     */ 
     811    pjsua_transport_id      id; 
     812 
     813    /** 
     814     * Transport type. 
     815     */ 
     816    pjsip_transport_type_e  type; 
     817 
     818    /** 
     819     * Transport type name. 
     820     */ 
     821    pj_str_t                type_name; 
     822 
     823    /** 
     824     * Transport string info/description. 
     825     */ 
     826    pj_str_t                info; 
     827 
     828    /** 
     829     * Transport flag (see ##pjsip_transport_flags_e). 
     830     */ 
     831    unsigned                flag; 
     832 
     833    /** 
     834     * Local address length. 
     835     */ 
     836    unsigned                addr_len; 
     837 
     838    /** 
     839     * Local/bound address. 
     840     */ 
     841    pj_sockaddr             local_addr; 
     842 
     843    /** 
     844     * Published address (or transport address name). 
     845     */ 
     846    pjsip_host_port         local_name; 
     847 
     848    /** 
     849     * Current number of objects currently referencing this transport. 
     850     */ 
     851    unsigned                usage_count; 
     852 
     853 
     854} pjsua_transport_info; 
     855 
     856 
     857/** 
     858 * Create SIP transport. 
     859 * 
     860 * @param type          Transport type. 
     861 * @param cfg           Transport configuration. 
     862 * @param p_id          Optional pointer to receive transport ID. 
     863 * 
     864 * @return              PJ_SUCCESS on success, or the appropriate error code. 
     865 */ 
     866PJ_DECL(pj_status_t) pjsua_transport_create(pjsip_transport_type_e type, 
     867                                            const pjsua_transport_config *cfg, 
     868                                            pjsua_transport_id *p_id); 
     869 
     870/** 
     871 * Register transport that has been created by application. 
     872 * 
     873 * @param tp            Transport instance. 
     874 * @param p_id          Optional pointer to receive transport ID. 
     875 * 
     876 * @return              PJ_SUCCESS on success, or the appropriate error code. 
     877 */ 
     878PJ_DECL(pj_status_t) pjsua_transport_register(pjsip_transport *tp, 
     879                                              pjsua_transport_id *p_id); 
     880 
     881 
     882/** 
     883 * Enumerate all transports currently created in the system. 
     884 * 
     885 * @param id            Array to receive transport ids. 
     886 * @param count         In input, specifies the maximum number of elements. 
     887 *                      On return, it contains the actual number of elements. 
     888 * 
     889 * @return              PJ_SUCCESS on success, or the appropriate error code. 
     890 */ 
     891PJ_DECL(pj_status_t) pjsua_enum_transports( pjsua_transport_id id[], 
     892                                            unsigned *count ); 
     893 
     894 
     895/** 
     896 * Get information about transports. 
     897 * 
     898 * @param id            Transport ID. 
     899 * @param info          Pointer to receive transport info. 
     900 * 
     901 * @return              PJ_SUCCESS on success, or the appropriate error code. 
     902 */ 
     903PJ_DECL(pj_status_t) pjsua_transport_get_info(pjsua_transport_id id, 
     904                                              pjsua_transport_info *info); 
     905 
     906 
     907/** 
     908 * Disable a transport or re-enable it. By default transport is always  
     909 * enabled after it is created. Disabling a transport does not necessarily 
     910 * close the socket, it will only discard incoming messages and prevent 
     911 * the transport from being used to send outgoing messages. 
     912 * 
     913 * @param id            Transport ID. 
     914 * @param enabled       Non-zero to enable, zero to disable. 
     915 * 
     916 * @return              PJ_SUCCESS on success, or the appropriate error code. 
     917 */ 
     918PJ_DECL(pj_status_t) pjsua_transport_set_enable(pjsua_transport_id id, 
     919                                                pj_bool_t enabled); 
     920 
     921 
     922/** 
     923 * Close the transport. If transport is forcefully closed, it will be 
     924 * immediately closed, and any pending transactions that are using the 
     925 * transport may not terminate properly. Otherwise, the system will wait 
     926 * until all transactions are closed while preventing new users from 
     927 * using the transport, and will close the transport when it is safe to 
     928 * do so. 
     929 * 
     930 * @param id            Transport ID. 
     931 * @param force         Non-zero to immediately close the transport. This 
     932 *                      is not recommended! 
     933 * 
     934 * @return              PJ_SUCCESS on success, or the appropriate error code. 
     935 */ 
     936PJ_DECL(pj_status_t) pjsua_transport_close( pjsua_transport_id id, 
     937                                            pj_bool_t force ); 
     938 
     939/** 
     940 * @} 
     941 */ 
     942 
     943 
     944 
     945 
     946/***************************************************************************** 
     947 * ACCOUNT API 
     948 */ 
     949 
     950 
     951/** 
     952 * @defgroup PJSUA_LIB_ACC Account Management 
     953 * @ingroup PJSUA_LIB 
     954 * @brief PJSUA supports multiple accounts.. 
     955 * @{ 
     956 * PJSUA accounts provide identity (or identities) of the user who is currently 
     957 * using the application. More than one account maybe created with PJSUA. 
     958 * 
     959 * Account may or may not have client registration associated with it. 
     960 * An account is also associated with <b>route set</b> and some <b>authentication 
     961 * credentials</b>, which are used when sending SIP request messages using the 
     962 * account. An account also has presence's <b>online status</b>, which 
     963 * will be reported to remote peer when the subscribe to the account's 
     964 * presence. 
     965 * 
     966 * At least one account MUST be created in the application. If no user 
     967 * association is required, application can create a userless account by 
     968 * calling #pjsua_acc_add_local(). A userless account identifies local endpoint 
     969 * instead of a particular user. 
     970 * 
     971 * Also one account must be set as the <b>default account</b>, which is used as 
     972 * the account to use when PJSUA fails to match a request with any other 
     973 * accounts. 
     974 * 
     975 * When sending outgoing SIP requests (such as making calls or sending 
     976 * instant messages), normally PJSUA requires the application to specify 
     977 * which account to use for the request. If no account is specified, 
     978 * PJSUA may be able to select the account by matching the destination 
     979 * domain name, and fall back to default account when no match is found. 
     980 */ 
     981 
     982/** 
     983 * Maximum accounts. 
     984 */ 
     985#ifndef PJSUA_MAX_ACC 
     986#   define PJSUA_MAX_ACC            8 
     987#endif 
     988 
     989 
     990/** 
     991 * Default registration interval. 
     992 */ 
     993#ifndef PJSUA_REG_INTERVAL 
     994#   define PJSUA_REG_INTERVAL       55 
     995#endif 
     996 
     997 
     998/** 
     999 * Account configuration. 
     1000 */ 
     1001typedef struct pjsua_acc_config 
     1002{ 
     1003    /**  
     1004     * The full SIP URL for the account. The value can take name address or  
     1005     * URL format, and will look something like "sip:account@serviceprovider". 
     1006     * 
     1007     * This field is mandatory. 
     1008     */ 
     1009    pj_str_t        id; 
     1010 
     1011    /**  
     1012     * This is the URL to be put in the request URI for the registration, 
     1013     * and will look something like "sip:serviceprovider". 
     1014     * 
     1015     * This field should be specified if registration is desired. If the 
     1016     * value is empty, no account registration will be performed. 
     1017     */ 
     1018    pj_str_t        reg_uri; 
     1019 
     1020    /**  
     1021     * Optional URI to be put as Contact for this account. It is recommended 
     1022     * that this field is left empty, so that the value will be calculated 
     1023     * automatically based on the transport address. 
     1024     */ 
     1025    pj_str_t        contact; 
     1026 
     1027    /** 
     1028     * Number of proxies in the proxy array below. 
     1029     */ 
     1030    unsigned        proxy_cnt; 
     1031 
     1032    /**  
     1033     * Optional URI of the proxies to be visited for all outgoing requests  
     1034     * that are using this account (REGISTER, INVITE, etc). Application need  
     1035     * to specify these proxies if the service provider requires that requests 
     1036     * destined towards its network should go through certain proxies first 
     1037     * (for example, border controllers). 
     1038     * 
     1039     * These proxies will be put in the route set for this account, with  
     1040     * maintaining the orders (the first proxy in the array will be visited 
     1041     * first). 
     1042     */ 
     1043    pj_str_t        proxy[PJSUA_ACC_MAX_PROXIES]; 
     1044 
     1045    /**  
     1046     * Optional interval for registration, in seconds. If the value is zero,  
     1047     * default interval will be used (PJSUA_REG_INTERVAL, 55 seconds). 
     1048     */ 
     1049    unsigned        reg_timeout; 
     1050 
     1051    /**  
     1052     * Number of credentials in the credential array. 
     1053     */ 
     1054    unsigned        cred_count; 
     1055 
     1056    /**  
     1057     * Array of credentials. If registration is desired, normally there should 
     1058     * be at least one credential specified, to successfully authenticate 
     1059     * against the service provider. More credentials can be specified, for 
     1060     * example when the requests are expected to be challenged by the 
     1061     * proxies in the route set. 
     1062     */ 
     1063    pjsip_cred_info cred_info[PJSUA_ACC_MAX_PROXIES]; 
     1064 
     1065} pjsua_acc_config; 
     1066 
     1067 
     1068/** 
     1069 * Call this function to initialize account config with default values. 
     1070 * 
     1071 * @param cfg       The account config to be initialized. 
     1072 */ 
     1073PJ_INLINE(void) pjsua_acc_config_default(pjsua_acc_config *cfg) 
     1074{ 
     1075    pj_memset(cfg, 0, sizeof(*cfg)); 
     1076 
     1077    cfg->reg_timeout = PJSUA_REG_INTERVAL; 
     1078} 
     1079 
     1080 
     1081 
     1082/** 
     1083 * Account info. Application can query account info by calling  
     1084 * #pjsua_acc_get_info(). 
     1085 */ 
     1086typedef struct pjsua_acc_info 
     1087{ 
     1088    /**  
     1089     * The account ID.  
     1090     */ 
     1091    pjsua_acc_id        id; 
     1092 
     1093    /** 
     1094     * Flag to indicate whether this is the default account. 
     1095     */ 
     1096    pj_bool_t           is_default; 
     1097 
     1098    /**  
     1099     * Account URI  
     1100     */ 
     1101    pj_str_t            acc_uri; 
     1102 
     1103    /**  
     1104     * Flag to tell whether this account has registration setting 
     1105     * (reg_uri is not empty). 
     1106     */ 
     1107    pj_bool_t           has_registration; 
     1108 
     1109    /** 
     1110     * An up to date expiration interval for account registration session. 
     1111     */ 
     1112    int                 expires; 
     1113 
     1114    /** 
     1115     * Last registration status code. If status code is zero, the account 
     1116     * is currently not registered. Any other value indicates the SIP 
     1117     * status code of the registration. 
     1118     */ 
     1119    pjsip_status_code   status; 
     1120 
     1121    /** 
     1122     * String describing the registration status. 
     1123     */ 
     1124    pj_str_t            status_text; 
     1125 
     1126    /** 
     1127     * Presence online status for this account. 
     1128     */ 
     1129    pj_bool_t           online_status; 
     1130 
     1131    /** 
     1132     * Buffer that is used internally to store the status text. 
     1133     */ 
     1134    char                buf_[PJ_ERR_MSG_SIZE]; 
     1135 
     1136} pjsua_acc_info; 
     1137 
     1138 
     1139 
     1140/** 
     1141 * Get number of current accounts. 
     1142 * 
     1143 * @return              Current number of accounts. 
     1144 */ 
     1145PJ_DECL(unsigned) pjsua_acc_get_count(void); 
     1146 
     1147 
     1148/** 
     1149 * Check if the specified account ID is valid. 
     1150 * 
     1151 * @param acc_id        Account ID to check. 
     1152 * 
     1153 * @return              Non-zero if account ID is valid. 
     1154 */ 
     1155PJ_DECL(pj_bool_t) pjsua_acc_is_valid(pjsua_acc_id acc_id); 
     1156 
     1157 
     1158/** 
     1159 * Add a new account to pjsua. PJSUA must have been initialized (with 
     1160 * #pjsua_init()) before calling this function. 
     1161 * 
     1162 * @param cfg           Account configuration. 
     1163 * @param is_default    If non-zero, this account will be set as the default 
     1164 *                      account. The default account will be used when sending 
     1165 *                      outgoing requests (e.g. making call) when no account is 
     1166 *                      specified, and when receiving incoming requests when the 
     1167 *                      request does not match any accounts. It is recommended 
     1168 *                      that default account is set to local/LAN account. 
     1169 * @param p_acc_id      Pointer to receive account ID of the new account. 
     1170 * 
     1171 * @return              PJ_SUCCESS on success, or the appropriate error code. 
     1172 */ 
     1173PJ_DECL(pj_status_t) pjsua_acc_add(const pjsua_acc_config *cfg, 
     1174                                   pj_bool_t is_default, 
     1175                                   pjsua_acc_id *p_acc_id); 
     1176 
     1177 
     1178/** 
     1179 * Add a local account. A local account is used to identify local endpoint 
     1180 * instead of a specific user, and for this reason, a transport ID is needed 
     1181 * to obtain the local address information. 
     1182 * 
     1183 * @param tid           Transport ID to generate account address. 
     1184 * @param is_default    If non-zero, this account will be set as the default 
     1185 *                      account. The default account will be used when sending 
     1186 *                      outgoing requests (e.g. making call) when no account is 
     1187 *                      specified, and when receiving incoming requests when the 
     1188 *                      request does not match any accounts. It is recommended 
     1189 *                      that default account is set to local/LAN account. 
     1190 * @param p_acc_id      Pointer to receive account ID of the new account. 
     1191 * 
     1192 * @return              PJ_SUCCESS on success, or the appropriate error code. 
     1193 */ 
     1194PJ_DECL(pj_status_t) pjsua_acc_add_local(pjsua_transport_id tid, 
     1195                                         pj_bool_t is_default, 
     1196                                         pjsua_acc_id *p_acc_id); 
     1197 
     1198/** 
     1199 * Delete account. 
     1200 * 
     1201 * @param acc_id        Id of the account to be deleted. 
     1202 * 
     1203 * @return              PJ_SUCCESS on success, or the appropriate error code. 
     1204 */ 
     1205PJ_DECL(pj_status_t) pjsua_acc_del(pjsua_acc_id acc_id); 
     1206 
     1207 
     1208/** 
     1209 * Modify account information. 
     1210 * 
     1211 * @param acc_id        Id of the account to be modified. 
     1212 * @param cfg           New account configuration. 
     1213 * 
     1214 * @return              PJ_SUCCESS on success, or the appropriate error code. 
     1215 */ 
     1216PJ_DECL(pj_status_t) pjsua_acc_modify(pjsua_acc_id acc_id, 
     1217                                      const pjsua_acc_config *cfg); 
     1218 
     1219 
     1220/** 
     1221 * Modify account's presence status to be advertised to remote/presence 
     1222 * subscribers. 
     1223 * 
     1224 * @param acc_id        The account ID. 
     1225 * @param is_online     True of false. 
     1226 * 
     1227 * @return              PJ_SUCCESS on success, or the appropriate error code. 
     1228 */ 
     1229PJ_DECL(pj_status_t) pjsua_acc_set_online_status(pjsua_acc_id acc_id, 
     1230                                                 pj_bool_t is_online); 
     1231 
     1232 
     1233/** 
     1234 * Update registration or perform unregistration.  
     1235 * 
     1236 * @param acc_id        The account ID. 
     1237 * @param renew         If renew argument is zero, this will start  
     1238 *                      unregistration process. 
     1239 * 
     1240 * @return              PJ_SUCCESS on success, or the appropriate error code. 
     1241 */ 
     1242PJ_DECL(pj_status_t) pjsua_acc_set_registration(pjsua_acc_id acc_id,  
     1243                                                pj_bool_t renew); 
     1244 
     1245 
     1246/** 
     1247 * Get account information. 
     1248 * 
     1249 * @param acc_id        Account identification. 
     1250 * @param info          Pointer to receive account information. 
     1251 * 
     1252 * @return              PJ_SUCCESS on success, or the appropriate error code. 
     1253 */ 
     1254PJ_DECL(pj_status_t) pjsua_acc_get_info(pjsua_acc_id acc_id, 
     1255                                        pjsua_acc_info *info); 
     1256 
     1257 
     1258/** 
     1259 * Enum accounts all account ids. 
     1260 * 
     1261 * @param ids           Array of account IDs to be initialized. 
     1262 * @param count         In input, specifies the maximum number of elements. 
     1263 *                      On return, it contains the actual number of elements. 
     1264 * 
     1265 * @return              PJ_SUCCESS on success, or the appropriate error code. 
     1266 */ 
     1267PJ_DECL(pj_status_t) pjsua_enum_accs(pjsua_acc_id ids[], 
     1268                                     unsigned *count ); 
     1269 
     1270 
     1271/** 
     1272 * Enum accounts info. 
     1273 * 
     1274 * @param info          Array of account infos to be initialized. 
     1275 * @param count         In input, specifies the maximum number of elements. 
     1276 *                      On return, it contains the actual number of elements. 
     1277 * 
     1278 * @return              PJ_SUCCESS on success, or the appropriate error code. 
     1279 */ 
     1280PJ_DECL(pj_status_t) pjsua_acc_enum_info( pjsua_acc_info info[], 
     1281                                          unsigned *count ); 
     1282 
     1283 
     1284/** 
     1285 * This is an internal function to find the most appropriate account to 
     1286 * used to reach to the specified URL. 
     1287 * 
     1288 * @param url           The remote URL to reach. 
     1289 * 
     1290 * @return              Account id. 
     1291 */ 
     1292PJ_DECL(pjsua_acc_id) pjsua_acc_find_for_outgoing(const pj_str_t *url); 
     1293 
     1294 
     1295/** 
     1296 * This is an internal function to find the most appropriate account to be 
     1297 * used to handle incoming calls. 
     1298 * 
     1299 * @param rdata         The incoming request message. 
     1300 * 
     1301 * @return              Account id. 
     1302 */ 
     1303PJ_DECL(pjsua_acc_id) pjsua_acc_find_for_incoming(pjsip_rx_data *rdata); 
     1304 
     1305 
     1306 
     1307/** 
     1308 * @} 
     1309 */ 
     1310 
     1311 
     1312/***************************************************************************** 
     1313 * CALLS API 
     1314 */ 
     1315 
     1316 
     1317/** 
     1318 * @defgroup PJSUA_LIB_CALL Calls 
     1319 * @ingroup PJSUA_LIB 
     1320 * @brief Call manipulation. 
     1321 * @{ 
     1322 */ 
     1323 
     1324/** 
     1325 * Max simultaneous calls. 
     1326 */ 
     1327#ifndef PJSUA_MAX_CALLS 
     1328#   define PJSUA_MAX_CALLS          32 
     1329#endif 
     1330 
     1331 
     1332 
    8911333/** 
    8921334 * Call media status. 
    … …  
    9701412 
    9711413 
    972  
    973 /** 
    974  * Conference port info. 
    975  */ 
    976 typedef struct pjsua_conf_port_info 
    977 { 
    978     /** Conference port number. */ 
    979     pjsua_conf_port_id  slot_id; 
    980  
    981     /** Port name. */ 
    982     pj_str_t            name; 
    983  
    984     /** Clock rate. */ 
    985     unsigned            clock_rate; 
    986  
    987     /** Number of channels. */ 
    988     unsigned            channel_count; 
    989  
    990     /** Samples per frame */ 
    991     unsigned            samples_per_frame; 
    992  
    993     /** Bits per sample */ 
    994     unsigned            bits_per_sample; 
    995  
    996     /** Number of listeners in the array. */ 
    997     unsigned            listener_cnt; 
    998  
    999     /** Array of listeners (in other words, ports where this port is  
    1000      *  transmitting to. 
    1001      */ 
    1002     pjsua_conf_port_id  listeners[PJSUA_MAX_CONF_PORTS]; 
    1003  
    1004 } pjsua_conf_port_info; 
    1005  
    1006  
    1007 /** 
    1008  * This structure holds information about custom media transport to 
    1009  * be registered to pjsua. 
    1010  */ 
    1011 typedef struct pjsua_media_transport 
    1012 { 
    1013     /** 
    1014      * Media socket information containing the address information 
    1015      * of the RTP and RTCP socket. 
    1016      */ 
    1017     pjmedia_sock_info    skinfo; 
    1018  
    1019     /** 
    1020      * The media transport instance. 
    1021      */ 
    1022     pjmedia_transport   *transport; 
    1023  
    1024 } pjsua_media_transport; 
    1025  
    1026  
    1027 /** 
    1028  * This structure describes additional information to be sent with 
    1029  * outgoing SIP message. 
    1030  */ 
    1031 typedef struct pjsua_msg_data 
    1032 { 
    1033     /** 
    1034      * Additional message headers as linked list. 
    1035      */ 
    1036     pjsip_hdr   hdr_list; 
    1037  
    1038     /** 
    1039      * MIME type of optional message body.  
    1040      */ 
    1041     pj_str_t    content_type; 
    1042  
    1043     /** 
    1044      * Optional message body. 
    1045      */ 
    1046     pj_str_t    msg_body; 
    1047  
    1048 } pjsua_msg_data; 
    1049  
    1050  
    1051 /** 
    1052  * Initialize message data. 
    1053  * 
    1054  * @param msg_data  Message data to be initialized. 
    1055  */ 
    1056 PJ_INLINE(void) pjsua_msg_data_init(pjsua_msg_data *msg_data) 
    1057 { 
    1058     pj_memset(msg_data, 0, sizeof(*msg_data)); 
    1059     pj_list_init(&msg_data->hdr_list); 
    1060 } 
    1061  
    1062  
    1063 /***************************************************************************** 
    1064  * PJSUA Core API 
    1065  */ 
    1066  
    1067  
    1068 /** 
    1069  * Instantiate pjsua application. Application must call this function before 
    1070  * calling any other functions, to make sure that the underlying libraries 
    1071  * are properly initialized. Once this function has returned success, 
    1072  * application must call pjsua_destroy() before quitting. 
    1073  * 
    1074  * @return              PJ_SUCCESS on success, or the appropriate error code. 
    1075  */ 
    1076 PJ_DECL(pj_status_t) pjsua_create(void); 
    1077  
    1078  
    1079 /** 
    1080  * Initialize pjsua with the specified settings. All the settings are  
    1081  * optional, and the default values will be used when the config is not 
    1082  * specified. 
    1083  * 
    1084  * @param ua_cfg        User agent configuration. 
    1085  * @param log_cfg       Optional logging configuration. 
    1086  * @param media_cfg     Optional media configuration. 
    1087  * 
    1088  * @return              PJ_SUCCESS on success, or the appropriate error code. 
    1089  */ 
    1090 PJ_DECL(pj_status_t) pjsua_init(const pjsua_config *ua_cfg, 
    1091                                 const pjsua_logging_config *log_cfg, 
    1092                                 const pjsua_media_config *media_cfg); 
    1093  
    1094  
    1095 /** 
    1096  * Application is recommended to call this function after all initialization 
    1097  * is done, so that the library can do additional checking set up 
    1098  * additional  
    1099  * 
    1100  * @return              PJ_SUCCESS on success, or the appropriate error code. 
    1101  */ 
    1102 PJ_DECL(pj_status_t) pjsua_start(void); 
    1103  
    1104  
    1105 /** 
    1106  * Destroy pjsua. This function must be called once PJSUA is created. To 
    1107  * make it easier for application, application may call this function 
    1108  * several times with no danger. 
    1109  * 
    1110  * @return              PJ_SUCCESS on success, or the appropriate error code. 
    1111  */ 
    1112 PJ_DECL(pj_status_t) pjsua_destroy(void); 
    1113  
    1114  
    1115 /** 
    1116  * Poll pjsua for events, and if necessary block the caller thread for 
    1117  * the specified maximum interval (in miliseconds). 
    1118  * 
    1119  * @param msec_timeout  Maximum time to wait, in miliseconds. 
    1120  * 
    1121  * @return  The number of events that have been handled during the 
    1122  *          poll. Negative value indicates error, and application 
    1123  *          can retrieve the error as (err = -return_value). 
    1124  */ 
    1125 PJ_DECL(int) pjsua_handle_events(unsigned msec_timeout); 
    1126  
    1127  
    1128 /** 
    1129  * Create memory pool. 
    1130  * 
    1131  * @param name          Optional pool name. 
    1132  * @param size          Initial size of the pool. 
    1133  * @param increment     Increment size. 
    1134  * 
    1135  * @return              The pool, or NULL when there's no memory. 
    1136  */ 
    1137 PJ_DECL(pj_pool_t*) pjsua_pool_create(const char *name, pj_size_t init_size, 
    1138                                       pj_size_t increment); 
    1139  
    1140  
    1141 /** 
    1142  * Application can call this function at any time (after pjsua_create(), of 
    1143  * course) to change logging settings. 
    1144  * 
    1145  * @param c             Logging configuration. 
    1146  * 
    1147  * @return              PJ_SUCCESS on success, or the appropriate error code. 
    1148  */ 
    1149 PJ_DECL(pj_status_t) pjsua_reconfigure_logging(const pjsua_logging_config *c); 
    1150  
    1151  
    1152 /** 
    1153  * Internal function to get SIP endpoint instance of pjsua, which is 
    1154  * needed for example to register module, create transports, etc. 
    1155  * Probably is only valid after #pjsua_init() is called. 
    1156  *  
    1157  * @return              SIP endpoint instance. 
    1158  */ 
    1159 PJ_DECL(pjsip_endpoint*) pjsua_get_pjsip_endpt(void); 
    1160  
    1161 /** 
    1162  * Internal function to get media endpoint instance. 
    1163  * Only valid after #pjsua_init() is called. 
    1164  * 
    1165  * @return              Media endpoint instance. 
    1166  */ 
    1167 PJ_DECL(pjmedia_endpt*) pjsua_get_pjmedia_endpt(void); 
    1168  
    1169  
    1170 /***************************************************************************** 
    1171  * PJSUA SIP Transport API. 
    1172  */ 
    1173  
    1174 /** 
    1175  * Create SIP transport. 
    1176  * 
    1177  * @param type          Transport type. 
    1178  * @param cfg           Transport configuration. 
    1179  * @param p_id          Optional pointer to receive transport ID. 
    1180  * 
    1181  * @return              PJ_SUCCESS on success, or the appropriate error code. 
    1182  */ 
    1183 PJ_DECL(pj_status_t) pjsua_transport_create(pjsip_transport_type_e type, 
    1184                                             const pjsua_transport_config *cfg, 
    1185                                             pjsua_transport_id *p_id); 
    1186  
    1187 /** 
    1188  * Register transport that has been created by application. 
    1189  * 
    1190  * @param tp            Transport instance. 
    1191  * @param p_id          Optional pointer to receive transport ID. 
    1192  * 
    1193  * @return              PJ_SUCCESS on success, or the appropriate error code. 
    1194  */ 
    1195 PJ_DECL(pj_status_t) pjsua_transport_register(pjsip_transport *tp, 
    1196                                               pjsua_transport_id *p_id); 
    1197  
    1198  
    1199 /** 
    1200  * Enumerate all transports currently created in the system. 
    1201  * 
    1202  * @param id            Array to receive transport ids. 
    1203  * @param count         In input, specifies the maximum number of elements. 
    1204  *                      On return, it contains the actual number of elements. 
    1205  * 
    1206  * @return              PJ_SUCCESS on success, or the appropriate error code. 
    1207  */ 
    1208 PJ_DECL(pj_status_t) pjsua_enum_transports( pjsua_transport_id id[], 
    1209                                             unsigned *count ); 
    1210  
    1211  
    1212 /** 
    1213  * Get information about transports. 
    1214  * 
    1215  * @param id            Transport ID. 
    1216  * @param info          Pointer to receive transport info. 
    1217  * 
    1218  * @return              PJ_SUCCESS on success, or the appropriate error code. 
    1219  */ 
    1220 PJ_DECL(pj_status_t) pjsua_transport_get_info(pjsua_transport_id id, 
    1221                                               pjsua_transport_info *info); 
    1222  
    1223  
    1224 /** 
    1225  * Disable a transport or re-enable it. By default transport is always  
    1226  * enabled after it is created. Disabling a transport does not necessarily 
    1227  * close the socket, it will only discard incoming messages and prevent 
    1228  * the transport from being used to send outgoing messages. 
    1229  * 
    1230  * @param id            Transport ID. 
    1231  * @param enabled       Non-zero to enable, zero to disable. 
    1232  * 
    1233  * @return              PJ_SUCCESS on success, or the appropriate error code. 
    1234  */ 
    1235 PJ_DECL(pj_status_t) pjsua_transport_set_enable(pjsua_transport_id id, 
    1236                                                 pj_bool_t enabled); 
    1237  
    1238  
    1239 /** 
    1240  * Close the transport. If transport is forcefully closed, it will be 
    1241  * immediately closed, and any pending transactions that are using the 
    1242  * transport may not terminate properly. Otherwise, the system will wait 
    1243  * until all transactions are closed while preventing new users from 
    1244  * using the transport, and will close the transport when it is safe to 
    1245  * do so. 
    1246  * 
    1247  * @param id            Transport ID. 
    1248  * @param force         Non-zero to immediately close the transport. This 
    1249  *                      is not recommended! 
    1250  * 
    1251  * @return              PJ_SUCCESS on success, or the appropriate error code. 
    1252  */ 
    1253 PJ_DECL(pj_status_t) pjsua_transport_close( pjsua_transport_id id, 
    1254                                             pj_bool_t force ); 
    1255  
    1256  
    1257 /***************************************************************************** 
    1258  * PJSUA Media Transport. 
    1259  */ 
    1260  
    1261 /** 
    1262  * Create UDP media transports for all the calls. This function creates 
    1263  * one UDP media transport for each call. 
    1264  * 
    1265  * @param cfg           Media transport configuration. The "port" field in the 
    1266  *                      configuration is used as the start port to bind the 
    1267  *                      sockets. 
    1268  * 
    1269  * @return              PJ_SUCCESS on success, or the appropriate error code. 
    1270  */ 
    1271 PJ_DECL(pj_status_t)  
    1272 pjsua_media_transports_create(const pjsua_transport_config *cfg); 
    1273  
    1274  
    1275 /** 
    1276  * Register custom media transports to be used by calls. There must 
    1277  * enough media transports for all calls. 
    1278  * 
    1279  * @param tp            The media transport array. 
    1280  * @param count         Number of elements in the array. This number MUST 
    1281  *                      match the number of maximum calls configured when 
    1282  *                      pjsua is created. 
    1283  * @param auto_delete   Flag to indicate whether the transports should be 
    1284  *                      destroyed when pjsua is shutdown. 
    1285  * 
    1286  * @return              PJ_SUCCESS on success, or the appropriate error code. 
    1287  */ 
    1288 PJ_DECL(pj_status_t)  
    1289 pjsua_media_transports_attach( pjsua_media_transport tp[], 
    1290                                unsigned count, 
    1291                                pj_bool_t auto_delete); 
    1292  
    1293  
    1294  
    1295 /***************************************************************************** 
    1296  * PJSUA Call API. 
    1297  */ 
    1298  
    12991414/** 
    13001415 * Get maximum number of calls configured in pjsua. 
    … …  
    13281443 * 
    13291444 * @param acc_id        The account to be used. 
    1330  * @param target        URI to be put in the request URI. 
    13311445 * @param dst_uri       URI to be put in the To header (normally is the same 
    13321446 *                      as the target URI). 
    … …  
    15651679                                     const char *indent); 
    15661680 
     1681/** 
     1682 * @} 
     1683 */ 
     1684 
    15671685 
    15681686/***************************************************************************** 
    1569  * PJSUA Account and Client Registration API. 
    1570  */ 
    1571  
    1572  
    1573 /** 
    1574  * Get number of current accounts. 
    1575  * 
    1576  * @return              Current number of accounts. 
    1577  */ 
    1578 PJ_DECL(unsigned) pjsua_acc_get_count(void); 
    1579  
    1580  
    1581 /** 
    1582  * Check if the specified account ID is valid. 
    1583  * 
    1584  * @param acc_id        Account ID to check. 
    1585  * 
    1586  * @return              Non-zero if account ID is valid. 
    1587  */ 
    1588 PJ_DECL(pj_bool_t) pjsua_acc_is_valid(pjsua_acc_id acc_id); 
    1589  
    1590  
    1591 /** 
    1592  * Add a new account to pjsua. PJSUA must have been initialized (with 
    1593  * #pjsua_init()) before calling this function. 
    1594  * 
    1595  * @param cfg           Account configuration. 
    1596  * @param is_default    If non-zero, this account will be set as the default 
    1597  *                      account. The default account will be used when sending 
    1598  *                      outgoing requests (e.g. making call) when no account is 
    1599  *                      specified, and when receiving incoming requests when the 
    1600  *                      request does not match any accounts. It is recommended 
    1601  *                      that default account is set to local/LAN account. 
    1602  * @param p_acc_id      Pointer to receive account ID of the new account. 
    1603  * 
    1604  * @return              PJ_SUCCESS on success, or the appropriate error code. 
    1605  */ 
    1606 PJ_DECL(pj_status_t) pjsua_acc_add(const pjsua_acc_config *cfg, 
    1607                                    pj_bool_t is_default, 
    1608                                    pjsua_acc_id *p_acc_id); 
    1609  
    1610  
    1611 /** 
    1612  * Add a local account. A local account is used to identify local endpoint 
    1613  * instead of a specific user, and for this reason, a transport ID is needed 
    1614  * to obtain the local address information. 
    1615  * 
    1616  * @param tid           Transport ID to generate account address. 
    1617  * @param is_default    If non-zero, this account will be set as the default 
    1618  *                      account. The default account will be used when sending 
    1619  *                      outgoing requests (e.g. making call) when no account is 
    1620  *                      specified, and when receiving incoming requests when the 
    1621  *                      request does not match any accounts. It is recommended 
    1622  *                      that default account is set to local/LAN account. 
    1623  * @param p_acc_id      Pointer to receive account ID of the new account. 
    1624  * 
    1625  * @return              PJ_SUCCESS on success, or the appropriate error code. 
    1626  */ 
    1627 PJ_DECL(pj_status_t) pjsua_acc_add_local(pjsua_transport_id tid, 
    1628                                          pj_bool_t is_default, 
    1629                                          pjsua_acc_id *p_acc_id); 
    1630  
    1631 /** 
    1632  * Delete account. 
    1633  * 
    1634  * @param acc_id        Id of the account to be deleted. 
    1635  * 
    1636  * @return              PJ_SUCCESS on success, or the appropriate error code. 
    1637  */ 
    1638 PJ_DECL(pj_status_t) pjsua_acc_del(pjsua_acc_id acc_id); 
    1639  
    1640  
    1641 /** 
    1642  * Modify account information. 
    1643  * 
    1644  * @param acc_id        Id of the account to be modified. 
    1645  * @param cfg           New account configuration. 
    1646  * 
    1647  * @return              PJ_SUCCESS on success, or the appropriate error code. 
    1648  */ 
    1649 PJ_DECL(pj_status_t) pjsua_acc_modify(pjsua_acc_id acc_id, 
    1650                                       const pjsua_acc_config *cfg); 
    1651  
    1652  
    1653 /** 
    1654  * Modify account's presence status to be advertised to remote/presence 
    1655  * subscribers. 
    1656  * 
    1657  * @param acc_id        The account ID. 
    1658  * @param is_online     True of false. 
    1659  * 
    1660  * @return              PJ_SUCCESS on success, or the appropriate error code. 
    1661  */ 
    1662 PJ_DECL(pj_status_t) pjsua_acc_set_online_status(pjsua_acc_id acc_id, 
    1663                                                  pj_bool_t is_online); 
    1664  
    1665  
    1666 /** 
    1667  * Update registration or perform unregistration.  
    1668  * 
    1669  * @param acc_id        The account ID. 
    1670  * @param renew         If renew argument is zero, this will start  
    1671  *                      unregistration process. 
    1672  * 
    1673  * @return              PJ_SUCCESS on success, or the appropriate error code. 
    1674  */ 
    1675 PJ_DECL(pj_status_t) pjsua_acc_set_registration(pjsua_acc_id acc_id,  
    1676                                                 pj_bool_t renew); 
    1677  
    1678  
    1679 /** 
    1680  * Get account information. 
    1681  * 
    1682  * @param acc_id        Account identification. 
    1683  * @param info          Pointer to receive account information. 
    1684  * 
    1685  * @return              PJ_SUCCESS on success, or the appropriate error code. 
    1686  */ 
    1687 PJ_DECL(pj_status_t) pjsua_acc_get_info(pjsua_acc_id acc_id, 
    1688                                         pjsua_acc_info *info); 
    1689  
    1690  
    1691 /** 
    1692  * Enum accounts all account ids. 
    1693  * 
    1694  * @param ids           Array of account IDs to be initialized. 
    1695  * @param count         In input, specifies the maximum number of elements. 
    1696  *                      On return, it contains the actual number of elements. 
    1697  * 
    1698  * @return              PJ_SUCCESS on success, or the appropriate error code. 
    1699  */ 
    1700 PJ_DECL(pj_status_t) pjsua_enum_accs(pjsua_acc_id ids[], 
    1701                                      unsigned *count ); 
    1702  
    1703  
    1704 /** 
    1705  * Enum accounts info. 
    1706  * 
    1707  * @param info          Array of account infos to be initialized. 
    1708  * @param count         In input, specifies the maximum number of elements. 
    1709  *                      On return, it contains the actual number of elements. 
    1710  * 
    1711  * @return              PJ_SUCCESS on success, or the appropriate error code. 
    1712  */ 
    1713 PJ_DECL(pj_status_t) pjsua_acc_enum_info( pjsua_acc_info info[], 
    1714                                           unsigned *count ); 
    1715  
    1716  
    1717 /** 
    1718  * This is an internal function to find the most appropriate account to 
    1719  * used to reach to the specified URL. 
    1720  * 
    1721  * @param url           The remote URL to reach. 
    1722  * 
    1723  * @return              Account id. 
    1724  */ 
    1725 PJ_DECL(pjsua_acc_id) pjsua_acc_find_for_outgoing(const pj_str_t *url); 
    1726  
    1727  
    1728 /** 
    1729  * This is an internal function to find the most appropriate account to be 
    1730  * used to handle incoming calls. 
    1731  * 
    1732  * @param rdata         The incoming request message. 
    1733  * 
    1734  * @return              Account id. 
    1735  */ 
    1736 PJ_DECL(pjsua_acc_id) pjsua_acc_find_for_incoming(pjsip_rx_data *rdata); 
    1737  
    1738  
    1739  
    1740 /***************************************************************************** 
    1741  * PJSUA Presence (pjsua_pres.c) 
    1742  */ 
     1687 * BUDDY API 
     1688 */ 
     1689 
     1690 
     1691/** 
     1692 * @defgroup PJSUA_LIB_BUDDY Buddy, Presence, and Instant Messaging 
     1693 * @ingroup PJSUA_LIB 
     1694 * @brief Buddy management, buddy's presence, and instant messaging. 
     1695 * @{ 
     1696 */ 
     1697 
     1698/** 
     1699 * Max buddies in buddy list. 
     1700 */ 
     1701#ifndef PJSUA_MAX_BUDDIES 
     1702#   define PJSUA_MAX_BUDDIES        256 
     1703#endif 
     1704 
     1705 
     1706/** 
     1707 * Buddy configuration. 
     1708 */ 
     1709typedef struct pjsua_buddy_config 
     1710{ 
     1711    /** 
     1712     * Buddy URL or name address. 
     1713     */ 
     1714    pj_str_t    uri; 
     1715 
     1716    /** 
     1717     * Specify whether presence subscription should start immediately. 
     1718     */ 
     1719    pj_bool_t   subscribe; 
     1720 
     1721} pjsua_buddy_config; 
     1722 
     1723 
     1724/** 
     1725 * Buddy's online status. 
     1726 */ 
     1727typedef enum pjsua_buddy_status 
     1728{ 
     1729    /** 
     1730     * Online status is unknown (possibly because no presence subscription 
     1731     * has been established). 
     1732     */ 
     1733    PJSUA_BUDDY_STATUS_UNKNOWN, 
     1734 
     1735    /** 
     1736     * Buddy is known to be offline. 
     1737     */ 
     1738    PJSUA_BUDDY_STATUS_ONLINE, 
     1739 
     1740    /** 
     1741     * Buddy is offline. 
     1742     */ 
     1743    PJSUA_BUDDY_STATUS_OFFLINE, 
     1744 
     1745} pjsua_buddy_status; 
     1746 
     1747 
     1748 
     1749/** 
     1750 * Buddy info. 
     1751 */ 
     1752typedef struct pjsua_buddy_info 
     1753{ 
     1754    /** 
     1755     * The buddy ID. 
     1756     */ 
     1757    pjsua_buddy_id      id; 
     1758 
     1759    /** 
     1760     * The full URI of the buddy, as specified in the configuration. 
     1761     */ 
     1762    pj_str_t            uri; 
     1763 
     1764    /** 
     1765     * Buddy's Contact, only available when presence subscription has 
     1766     * been established to the buddy. 
     1767     */ 
     1768    pj_str_t            contact; 
     1769 
     1770    /** 
     1771     * Buddy's online status. 
     1772     */ 
     1773    pjsua_buddy_status  status; 
     1774 
     1775    /** 
     1776     * Text to describe buddy's online status. 
     1777     */ 
     1778    pj_str_t            status_text; 
     1779 
     1780    /** 
     1781     * Flag to indicate that we should monitor the presence information for 
     1782     * this buddy (normally yes, unless explicitly disabled). 
     1783     */ 
     1784    pj_bool_t           monitor_pres; 
     1785 
     1786    /** 
     1787     * Internal buffer. 
     1788     */ 
     1789    char                buf_[256]; 
     1790 
     1791} pjsua_buddy_info; 
     1792 
    17431793 
    17441794/** 
    … …  
    18261876PJ_DECL(void) pjsua_pres_dump(pj_bool_t verbose); 
    18271877 
    1828  
    1829 /***************************************************************************** 
    1830  * PJSUA Instant Messaging (pjsua_im.c) 
    1831  */ 
    18321878 
    18331879/** 
    … …  
    18821928 
    18831929 
     1930/** 
     1931 * @} 
     1932 */ 
     1933 
     1934 
    18841935/***************************************************************************** 
    1885  * Conference bridge manipulation. 
    1886  */ 
     1936 * MEDIA API 
     1937 */ 
     1938 
     1939 
     1940/** 
     1941 * @defgroup PJSUA_LIB_MEDIA Media 
     1942 * @ingroup PJSUA_LIB 
     1943 * @brief Media manipulation. 
     1944 * @{ 
     1945 * 
     1946 * PJSUA has rather powerful media features, which are built around the 
     1947 * PJMEDIA conference bridge. Basically, all media termination (such as 
     1948 * calls, file players, file recorders, sound device, tone generators, etc) 
     1949 * are terminated in the conference bridge, and application can manipulate 
     1950 * the interconnection between these terminations freely. If more than 
     1951 * one media terminations are terminated in the same slot, the conference 
     1952 * bridge will mix the signal automatically. 
     1953 * 
     1954 * Application connects one media termination/slot to another by calling 
     1955 * #pjsua_conf_connect() function. This will establish <b>unidirectional</b> 
     1956 * media flow from the source termination to the sink termination. For 
     1957 * example, to stream a WAV file to remote call, application may use 
     1958 * the following steps: 
     1959 * 
     1960 \code 
     1961   
     1962  pj_status_t stream_to_call( pjsua_call_id call_id ) 
     1963  { 
     1964     pjsua_player_id player_id; 
     1965      
     1966     status = pjsua_player_create("mysong.wav", 0, NULL, &player_id); 
     1967     if (status != PJ_SUCCESS) 
     1968        return status; 
     1969 
     1970     status = pjsua_conf_connect( pjsua_player_get_conf_port(), 
     1971                                  pjsua_call_get_conf_port() ); 
     1972  } 
     1973 \endcode 
     1974 * 
     1975 * 
     1976 * Other features of PJSUA media: 
     1977 *  - efficient N to M interconnections between media terminations. 
     1978 *  - media termination can be connected to itself to create loopback 
     1979 *    media. 
     1980 *  - the media termination may have different clock rates, and resampling 
     1981 *    will be done automatically by conference bridge. 
     1982 *  - media terminations may also have different frame time; the 
     1983 *    conference bridge will perform the necessary bufferring to adjust 
     1984 *    the difference between terminations. 
     1985 *  - interconnections are removed automatically when media termination 
     1986 *    is removed from the bridge. 
     1987 *  - sound device may be changed even when there are active media  
     1988 *    interconnections. 
     1989 *  - correctly report call's media quality (in #pjsua_call_dump()) from 
     1990 *    RTCP packet exchange. 
     1991 */ 
     1992 
     1993/** 
     1994 * Max ports in the conference bridge. 
     1995 */ 
     1996#ifndef PJSUA_MAX_CONF_PORTS 
     1997#   define PJSUA_MAX_CONF_PORTS     254 
     1998#endif 
     1999 
     2000 
     2001 
     2002/** 
     2003 * Media configuration. 
     2004 */ 
     2005struct pjsua_media_config 
     2006{ 
     2007    /** 
     2008     * Clock rate to be applied to the conference bridge. 
     2009     * If value is zero, default clock rate will be used (16KHz). 
     2010     */ 
     2011    unsigned            clock_rate; 
     2012 
     2013    /** 
     2014     * Specify maximum number of media ports to be created in the 
     2015     * conference bridge. Since all media terminate in the bridge 
     2016     * (calls, file player, file recorder, etc), the value must be 
     2017     * large enough to support all of them. However, the larger 
     2018     * the value, the more computations are performed. 
     2019     */ 
     2020    unsigned            max_media_ports; 
     2021 
     2022    /** 
     2023     * Specify whether the media manager should manage its own 
     2024     * ioqueue for the RTP/RTCP sockets. If yes, ioqueue will be created 
     2025     * and at least one worker thread will be created too. If no, 
     2026     * the RTP/RTCP sockets will share the same ioqueue as SIP sockets, 
     2027     * and no worker thread is needed. 
     2028     * 
     2029     * Normally application would say yes here, unless it wants to 
     2030     * run everything from a single thread. 
     2031     */ 
     2032    pj_bool_t           has_ioqueue; 
     2033 
     2034    /** 
     2035     * Specify the number of worker threads to handle incoming RTP 
     2036     * packets. A value of one is recommended for most applications. 
     2037     */ 
     2038    unsigned            thread_cnt; 
     2039 
     2040 
     2041}; 
     2042 
     2043 
     2044/** 
     2045 * Use this function to initialize media config. 
     2046 * 
     2047 * @param cfg   The media config to be initialized. 
     2048 */ 
     2049PJ_INLINE(void) pjsua_media_config_default(pjsua_media_config *cfg) 
     2050{ 
     2051    pj_memset(cfg, 0, sizeof(*cfg)); 
     2052 
     2053    cfg->clock_rate = 16000; 
     2054    cfg->max_media_ports = 32; 
     2055    cfg->has_ioqueue = PJ_TRUE; 
     2056    cfg->thread_cnt = 1; 
     2057} 
     2058 
     2059 
     2060 
     2061/** 
     2062 * Codec config. 
     2063 */ 
     2064typedef struct pjsua_codec_info 
     2065{ 
     2066    /** 
     2067     * Codec unique identification. 
     2068     */ 
     2069    pj_str_t            codec_id; 
     2070 
     2071    /** 
     2072     * Codec priority (integer 0-255). 
     2073     */ 
     2074    pj_uint8_t          priority; 
     2075 
     2076    /** 
     2077     * Internal buffer. 
     2078     */ 
     2079    char                buf_[32]; 
     2080 
     2081} pjsua_codec_info; 
     2082 
     2083 
     2084/** 
     2085 * Conference port info. 
     2086 */ 
     2087typedef struct pjsua_conf_port_info 
     2088{ 
     2089    /** Conference port number. */ 
     2090    pjsua_conf_port_id  slot_id; 
     2091 
     2092    /** Port name. */ 
     2093    pj_str_t            name; 
     2094 
     2095    /** Clock rate. */ 
     2096    unsigned            clock_rate; 
     2097 
     2098    /** Number of channels. */ 
     2099    unsigned            channel_count; 
     2100 
     2101    /** Samples per frame */ 
     2102    unsigned            samples_per_frame; 
     2103 
     2104    /** Bits per sample */ 
     2105    unsigned            bits_per_sample; 
     2106 
     2107    /** Number of listeners in the array. */ 
     2108    unsigned            listener_cnt; 
     2109 
     2110    /** Array of listeners (in other words, ports where this port is  
     2111     *  transmitting to. 
     2112     */ 
     2113    pjsua_conf_port_id  listeners[PJSUA_MAX_CONF_PORTS]; 
     2114 
     2115} pjsua_conf_port_info; 
     2116 
     2117 
     2118/** 
     2119 * This structure holds information about custom media transport to 
     2120 * be registered to pjsua. 
     2121 */ 
     2122typedef struct pjsua_media_transport 
     2123{ 
     2124    /** 
     2125     * Media socket information containing the address information 
     2126     * of the RTP and RTCP socket. 
     2127     */ 
     2128    pjmedia_sock_info    skinfo; 
     2129 
     2130    /** 
     2131     * The media transport instance. 
     2132     */ 
     2133    pjmedia_transport   *transport; 
     2134 
     2135} pjsua_media_transport; 
     2136 
     2137 
     2138 
    18872139 
    18882140/** 
    … …  
    19692221 * 
    19702222 * @param filename      The filename to be played. Currently only 
    1971  *                      WAV files are supported. 
     2223 *                      WAV files are supported, and the WAV file MUST be 
     2224 *                      formatted as 16bit PCM mono/single channel (any 
     2225 *                      clock rate is supported). 
    19722226 * @param options       Options (currently zero). 
    19732227 * @param user_data     Arbitrary user data to be associated with the player. 
    … …  
    21662420 
    21672421 
    2168  
    2169 /***************************************************************************** 
    2170  * Utilities. 
    2171  * 
    2172  */ 
    2173  
    2174 /* 
    2175  * Verify that valid SIP url is given. 
    2176  * 
    2177  * @param c_url         The URL, as NULL terminated string. 
    2178  * 
    2179  * @return              PJ_SUCCESS on success, or the appropriate error code. 
    2180  */ 
    2181 PJ_DECL(pj_status_t) pjsua_verify_sip_url(const char *c_url); 
    2182  
    2183  
    2184 /** 
    2185  * Display error message for the specified error code. 
    2186  * 
    2187  * @param sender        The log sender field. 
    2188  * @param title         Message title for the error. 
    2189  * @param status        Status code. 
    2190  */ 
    2191 PJ_DECL(void) pjsua_perror(const char *sender, const char *title,  
    2192                            pj_status_t status); 
    2193  
     2422/** 
     2423 * Create UDP media transports for all the calls. This function creates 
     2424 * one UDP media transport for each call. 
     2425 * 
     2426 * @param cfg           Media transport configuration. The "port" field in the 
     2427 *                      configuration is used as the start port to bind the 
     2428 *                      sockets. 
     2429 * 
     2430 * @return              PJ_SUCCESS on success, or the appropriate error code. 
     2431 */ 
     2432PJ_DECL(pj_status_t)  
     2433pjsua_media_transports_create(const pjsua_transport_config *cfg); 
     2434 
     2435 
     2436/** 
     2437 * Register custom media transports to be used by calls. There must 
     2438 * enough media transports for all calls. 
     2439 * 
     2440 * @param tp            The media transport array. 
     2441 * @param count         Number of elements in the array. This number MUST 
     2442 *                      match the number of maximum calls configured when 
     2443 *                      pjsua is created. 
     2444 * @param auto_delete   Flag to indicate whether the transports should be 
     2445 *                      destroyed when pjsua is shutdown. 
     2446 * 
     2447 * @return              PJ_SUCCESS on success, or the appropriate error code. 
     2448 */ 
     2449PJ_DECL(pj_status_t)  
     2450pjsua_media_transports_attach( pjsua_media_transport tp[], 
     2451                               unsigned count, 
     2452                               pj_bool_t auto_delete); 
     2453 
     2454 
     2455/** 
     2456 * @} 
     2457 */ 
    21942458 
    21952459 
    … …  
    21982462 
    21992463 
     2464/** 
     2465 * @} 
     2466 */ 
     2467 
     2468 
    22002469#endif  /* __PJSUA_H__ */ 
Note: See TracChangeset for help on using the changeset viewer.