From 4d82c2e0f6790422e6e319ad80983e1e002fca85 Mon Sep 17 00:00:00 2001 From: Benny Prijono Date: Sun, 28 May 2006 14:58:12 +0000 Subject: More changes in pjsua API to make it more complete high level API git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@482 74dad513-b988-da41-8d7b-12977e46ad98 --- pjsip/include/pjsua-lib/pjsua.h | 463 ++++++++++++++++++++++++++++------------ 1 file changed, 323 insertions(+), 140 deletions(-) (limited to 'pjsip/include/pjsua-lib') diff --git a/pjsip/include/pjsua-lib/pjsua.h b/pjsip/include/pjsua-lib/pjsua.h index 6484d729..cb2e8b7a 100644 --- a/pjsip/include/pjsua-lib/pjsua.h +++ b/pjsip/include/pjsua-lib/pjsua.h @@ -68,63 +68,6 @@ PJ_BEGIN_DECL #endif - -/** - * Structure to be attached to invite dialog. - * Given a dialog "dlg", application can retrieve this structure - * by accessing dlg->mod_data[pjsua.mod.id]. - */ -struct pjsua_call -{ - unsigned index; /**< Index in pjsua array. */ - pjsip_inv_session *inv; /**< The invite session. */ - pj_time_val start_time;/**< First INVITE sent/received. */ - pj_time_val res_time; /**< First response sent/received. */ - pj_time_val conn_time; /**< Connected/confirmed time. */ - pj_time_val dis_time; /**< Disconnect time. */ - int acc_index; /**< Account index being used. */ - pjmedia_session *session; /**< The media session. */ - unsigned conf_slot; /**< Slot # in conference bridge. */ - pjsip_evsub *xfer_sub; /**< Xfer server subscription, if this - call was triggered by xfer. */ - pjmedia_sock_info skinfo; /**< Preallocated media sockets. */ - pjmedia_transport *med_tp; /**< Media transport. */ - void *app_data; /**< Application data. */ - pj_timer_entry refresh_tm;/**< Timer to send re-INVITE. */ - pj_timer_entry hangup_tm; /**< Timer to hangup call. */ -}; - -typedef struct pjsua_call pjsua_call; - - -/** - * Buddy data. - */ -struct pjsua_buddy -{ - pj_str_t uri; /**< Buddy URI */ - int acc_index; /**< Which account to use. */ - pj_bool_t monitor; /**< Should we monitor? */ - pjsip_evsub *sub; /**< Buddy presence subscription */ - pjsip_pres_status status; /**< Buddy presence status. */ -}; - -typedef struct pjsua_buddy pjsua_buddy; - - -/** - * Server presence subscription list head. - */ -struct pjsua_srv_pres -{ - PJ_DECL_LIST_MEMBER(struct pjsua_srv_pres); - pjsip_evsub *sub; - char *remote; -}; - -typedef struct pjsua_srv_pres pjsua_srv_pres; - - /** * Account configuration. */ @@ -160,35 +103,6 @@ struct pjsua_acc_config typedef struct pjsua_acc_config pjsua_acc_config; -/** - * Account - */ -struct pjsua_acc -{ - int index; /**< Index in accounts array. */ - pj_str_t user_part; /**< User part of local URI. */ - pj_str_t host_part; /**< Host part of local URI. */ - - pjsip_regc *regc; /**< Client registration session. */ - pj_timer_entry reg_timer; /**< Registration timer. */ - pj_status_t reg_last_err; /**< Last registration error. */ - int reg_last_code; /**< Last status last register. */ - - pjsip_route_hdr route_set; /**< Route set. */ - - pj_bool_t online_status; /**< Our online status. */ - pjsua_srv_pres pres_srv_list; /**< Server subscription list. */ - - void *app_data; /**< Application data. */ -}; - - -/** - * @see pjsua_acc - */ -typedef struct pjsua_acc pjsua_acc; - - /** * PJSUA settings. */ @@ -247,6 +161,12 @@ struct pjsua_config /** Second STUN server port number */ unsigned stun_port2; + /** Sound player device ID (default: 0) */ + unsigned snd_player_id; + + /** Sound capture device ID (default: 0) */ + unsigned snd_capture_id; + /** Internal clock rate (to be applied to sound devices and conference * bridge, default is 0/follows the codec, or 44100 for MacOS). */ @@ -339,17 +259,38 @@ typedef struct pjsua_config pjsua_config; struct pjsua_callback { /** - * Notify UI when invite state has changed. + * Notify application when invite state has changed. + * Application may then query the call info to get the + * detail call states. */ void (*on_call_state)(int call_index, pjsip_event *e); /** - * Notify UI when registration status has changed. + * Notify application on call being transfered. + * Application can decide to accept/reject transfer request + * by setting the code (default is 200). When this callback + * is not defined, the default behavior is to accept the + * transfer. + */ + void (*on_call_transfered)(int call_index, + const pj_str_t *dst, + pjsip_status_code *code); + + /** + * Notify application when registration status has changed. + * Application may then query the account info to get the + * registration details. */ void (*on_reg_state)(int acc_index); /** - * Notify UI on incoming pager (i.e. MESSAGE request). + * Notify application when the buddy state has changed. + * Application may then query the buddy into to get the details. + */ + void (*on_buddy_state)(int buddy_index); + + /** + * Notify application on incoming pager (i.e. MESSAGE request). * Argument call_index will be -1 if MESSAGE request is not related to an * existing call. */ @@ -357,7 +298,7 @@ struct pjsua_callback const pj_str_t *to, const pj_str_t *txt); /** - * Notify UI about typing indication. + * Notify application about typing indication. */ void (*on_typing)(int call_index, const pj_str_t *from, const pj_str_t *to, pj_bool_t is_typing); @@ -370,55 +311,79 @@ struct pjsua_callback typedef struct pjsua_callback pjsua_callback; -/* PJSUA application variables. */ -struct pjsua +/** + * Call info. + */ +struct pjsua_call_info { - /* Control: */ - pj_caching_pool cp; /**< Global pool factory. */ - pjsip_endpoint *endpt; /**< Global endpoint. */ - pj_pool_t *pool; /**< pjsua's private pool. */ - pjsip_module mod; /**< pjsua's PJSIP module. */ - - - /* Config: */ - pjsua_config config; /**< PJSUA configs */ - - /* Application callback: */ - pjsua_callback cb; /**< Application callback. */ - - /* Media: */ - pjmedia_endpt *med_endpt; /**< Media endpoint. */ - pjmedia_conf *mconf; /**< Media conference. */ - unsigned wav_slot; /**< WAV player slot in bridge */ - pjmedia_port *file_port; /**< WAV player port. */ + unsigned index; + pj_bool_t active; + pjsip_role_e role; + pj_str_t local_info; + pj_str_t remote_info; + pjsip_inv_state state; + pj_str_t state_text; + pj_time_val connect_duration; + pj_time_val total_duration; + pjsip_status_code cause; + pj_str_t cause_text; + pj_bool_t has_media; + unsigned conf_slot; +}; +typedef struct pjsua_call_info pjsua_call_info; - /* Account: */ - pjsua_acc acc[PJSUA_MAX_ACC]; /** Client regs array. */ +enum pjsua_buddy_status +{ + PJSUA_BUDDY_STATUS_UNKNOWN, + PJSUA_BUDDY_STATUS_ONLINE, + PJSUA_BUDDY_STATUS_OFFLINE, +}; - /* Threading (optional): */ - pj_thread_t *threads[8]; /**< Thread instances. */ - pj_bool_t quit_flag; /**< To signal thread to quit. */ +typedef enum pjsua_buddy_status pjsua_buddy_status; - /* Transport (UDP): */ - pj_sock_t sip_sock; /**< SIP UDP socket. */ - pj_sockaddr_in sip_sock_name; /**< Public/STUN UDP socket addr. */ +/** + * Buddy info. + */ +struct pjsua_buddy_info +{ + unsigned index; + pj_bool_t is_valid; + pj_str_t name; + pj_str_t display_name; + pj_str_t host; + unsigned port; + pj_str_t uri; + pjsua_buddy_status status; + pj_str_t status_text; + pj_bool_t monitor; +}; - /* PJSUA Calls: */ - int call_cnt; /**< Number of calls. */ - pjsua_call calls[PJSUA_MAX_CALLS]; /** Calls array. */ +typedef struct pjsua_buddy_info pjsua_buddy_info; - /* SIMPLE and buddy status: */ - int buddy_cnt; - pjsua_buddy buddies[PJSUA_MAX_BUDDIES]; +/** + * Account info. + */ +struct pjsua_acc_info +{ + unsigned index; + pj_str_t acc_id; + pj_bool_t has_registration; + int expires; + pjsip_status_code status; + pj_str_t status_text; + pj_bool_t online_status; + char buf[PJ_ERR_MSG_SIZE]; }; +typedef struct pjsua_acc_info pjsua_acc_info; -/** PJSUA instance. */ -extern struct pjsua pjsua; + +typedef int pjsua_player_id; +typedef int pjsua_recorder_id; @@ -433,7 +398,7 @@ PJ_DECL(void) pjsua_default_config(pjsua_config *cfg); /** - * Test configuration. + * Validate configuration. */ PJ_DECL(pj_status_t) pjsua_test_config(const pjsua_config *cfg, char *errmsg, @@ -441,9 +406,8 @@ PJ_DECL(pj_status_t) pjsua_test_config(const pjsua_config *cfg, /** - * Create pjsua application. - * This initializes pjlib/pjlib-util, and creates memory pool factory to - * be used by application. + * Instantiate pjsua application. This initializes pjlib/pjlib-util, and + * creates memory pool factory to be used by application. */ PJ_DECL(pj_status_t) pjsua_create(void); @@ -469,22 +433,78 @@ PJ_DECL(pj_status_t) pjsua_init(const pjsua_config *cfg, */ PJ_DECL(pj_status_t) pjsua_start(void); - /** * Destroy pjsua. */ PJ_DECL(pj_status_t) pjsua_destroy(void); +/** + * Get SIP endpoint instance. + * Only valid after pjsua_init(). + */ +PJ_DECL(pjsip_endpoint*) pjsua_get_pjsip_endpt(void); + +/** + * Get media endpoint instance. + * Only valid after pjsua_init(). + */ +PJ_DECL(pjmedia_endpt*) pjsua_get_pjmedia_endpt(void); + +/** + * Replace media transport. + */ +PJ_DECL(pj_status_t) pjsua_set_call_media_transport(unsigned call_index, + const pjmedia_sock_info *i, + pjmedia_transport *tp); + /***************************************************************************** * PJSUA Call API (defined in pjsua_call.c). */ +/** + * Get maximum number of calls configured in pjsua. + */ +PJ_DECL(unsigned) pjsua_get_max_calls(void); + +/** + * Get current number of active calls. + */ +PJ_DECL(unsigned) pjsua_get_call_count(void); + +/** + * Check if the specified call has active INVITE session and the INVITE + * session has not been disconnected. + */ +PJ_DECL(pj_bool_t) pjsua_call_is_active(unsigned call_index); + + +/** + * Check if call has a media session. + */ +PJ_DECL(pj_bool_t) pjsua_call_has_media(unsigned call_index); + + +/** + * Get call info. + */ +PJ_DECL(pj_status_t) pjsua_get_call_info(unsigned call_index, + pjsua_call_info *info); + + +/** + * Duplicate call info. + */ +PJ_DECL(void) pjsua_dup_call_info(pj_pool_t *pool, + pjsua_call_info *dst_info, + const pjsua_call_info *src_info); + + /** * Make outgoing call. */ -PJ_DECL(pj_status_t) pjsua_make_call(int acc_index, - const char *cstr_dest_uri, +PJ_DECL(pj_status_t) pjsua_make_call(unsigned acc_index, + const pj_str_t *dst_uri, int *p_call_index); @@ -514,13 +534,19 @@ PJ_DECL(void) pjsua_call_reinvite(int call_index); /** * Transfer call. */ -PJ_DECL(void) pjsua_call_xfer(int call_index, const char *dest); +PJ_DECL(void) pjsua_call_xfer(unsigned call_index, const pj_str_t *dest); + +/** + * Dial DTMF. + */ +PJ_DECL(pj_status_t) pjsua_call_dial_dtmf(unsigned call_index, + const pj_str_t *digits); /** * Send instant messaging inside INVITE session. */ -PJ_DECL(void) pjsua_call_send_im(int call_index, const char *text); +PJ_DECL(void) pjsua_call_send_im(int call_index, const pj_str_t *text); /** @@ -535,14 +561,44 @@ PJ_DECL(void) pjsua_call_hangup_all(void); /***************************************************************************** - * PJSUA Client Registration API (defined in pjsua_reg.c). + * PJSUA Account and Client Registration API (defined in pjsua_reg.c). + */ + + +/** + * Get number of accounts. */ +PJ_DECL(unsigned) pjsua_get_acc_count(void); + +/** + * Get account info. + */ +PJ_DECL(pj_status_t) pjsua_acc_get_info(unsigned acc_index, + pjsua_acc_info *info); + +/** + * Add a new account. + * This function should be called after pjsua_init(). + * Application should call pjsua_acc_set_registration() to start + * registration for this account. + */ +PJ_DECL(pj_status_t) pjsua_acc_add(const pjsua_acc_config *cfg, + int *acc_index); + + +/** + * Set account's presence status. + * Must call pjsua_pres_refresh() after this. + */ +PJ_DECL(pj_status_t) pjsua_acc_set_online_status(unsigned acc_index, + pj_bool_t is_online); + /** * Update registration or perform unregistration. If renew argument is zero, * this will start unregistration process. */ -PJ_DECL(void) pjsua_regc_update(int acc_index, pj_bool_t renew); +PJ_DECL(void) pjsua_acc_set_registration(unsigned acc_index, pj_bool_t renew); @@ -551,6 +607,33 @@ PJ_DECL(void) pjsua_regc_update(int acc_index, pj_bool_t renew); * PJSUA Presence (pjsua_pres.c) */ +/** + * Get buddy count. + */ +PJ_DECL(unsigned) pjsua_get_buddy_count(void); + + +/** + * Get buddy info. + */ +PJ_DECL(pj_status_t) pjsua_buddy_get_info(unsigned buddy_index, + pjsua_buddy_info *info); + +/** + * Add new buddy. + */ +PJ_DECL(pj_status_t) pjsua_buddy_add(const pj_str_t *uri, + int *buddy_index); + + +/** + * Enable/disable buddy's presence monitoring. + * Must call pjsua_pres_refresh() after this. + */ +PJ_DECL(pj_status_t) pjsua_buddy_subscribe_pres(unsigned buddy_index, + pj_bool_t monitor); + + /** * Refresh both presence client and server subscriptions. */ @@ -576,18 +659,111 @@ extern const pjsip_method pjsip_message_method; /** * Send IM outside dialog. */ -PJ_DECL(pj_status_t) pjsua_im_send(int acc_index, const char *dst_uri, - const char *text); +PJ_DECL(pj_status_t) pjsua_im_send(int acc_index, const pj_str_t *dst_uri, + const pj_str_t *text); /** * Send typing indication outside dialog. */ -PJ_DECL(pj_status_t) pjsua_im_typing(int acc_index, const char *dst_uri, +PJ_DECL(pj_status_t) pjsua_im_typing(int acc_index, const pj_str_t *dst_uri, pj_bool_t is_typing); +/***************************************************************************** + * Media. + */ + +/** + * Get maxinum number of conference ports. + */ +PJ_DECL(unsigned) pjsua_conf_max_ports(void); + + +/** + * Enum all conference ports. + */ +PJ_DECL(pj_status_t) pjsua_conf_enum_ports(unsigned *count, + pjmedia_conf_port_info info[]); + + +/** + * Connect conference port. + */ +PJ_DECL(pj_status_t) pjsua_conf_connect(unsigned src_port, + unsigned dst_port); + + +/** + * Connect conference port connection. + */ +PJ_DECL(pj_status_t) pjsua_conf_disconnect(unsigned src_port, + unsigned dst_port); + + +/** + * Create a file player. + */ +PJ_DECL(pj_status_t) pjsua_player_create(const pj_str_t *filename, + pjsua_player_id *id); + + +/** + * Get conference port associated with player. + */ +PJ_DECL(unsigned) pjsua_player_get_conf_port(pjsua_player_id id); + + +/** + * Set playback position. + */ +PJ_DECL(pj_status_t) pjsua_player_set_pos(pjsua_player_id id, + pj_uint32_t samples); + + +/** + * Destroy player. + */ +PJ_DECL(pj_status_t) pjsua_player_destroy(pjsua_player_id id); + + + +/** + * Create a file recorder. + */ +PJ_DECL(pj_status_t) pjsua_recorder_create(const pj_str_t *filename, + pjsua_recorder_id *id); + + +/** + * Get conference port associated with recorder. + */ +PJ_DECL(unsigned) pjsua_recorder_get_conf_port(pjsua_recorder_id id); + + +/** + * Destroy recorder (will complete recording). + */ +PJ_DECL(pj_status_t) pjsua_recorder_destroy(pjsua_recorder_id id); + + +/** + * Enum sound devices. + */ +PJ_DECL(pj_status_t) pjsua_enum_snd_devices(unsigned *count, + pjmedia_snd_dev_info info[]); + + +/** + * Select or change sound device. + * This will only change the device ID in configuration (not changing + * the current device). + */ +PJ_DECL(pj_status_t) pjsua_set_snd_dev(int snd_capture_id, + int snd_player_id); + + /***************************************************************************** * Utilities. * @@ -608,8 +784,15 @@ PJ_DECL(pj_status_t) pjsua_parse_args(int argc, char *argv[], PJ_DECL(pj_status_t) pjsua_load_settings(const char *filename, pjsua_config *cfg); +/** + * Get pjsua running config. + */ +PJ_DECL(const pjsua_config*) pjsua_get_config(void); + + /** * Dump settings. + * If cfg is NULL, it will dump current settings. */ PJ_DECL(int) pjsua_dump_settings(const pjsua_config *cfg, char *buf, pj_size_t max); -- cgit v1.2.3