More changes in pjsua API to make it more complete high level API
git-svn-id: https://svn.pjsip.org/repos/pjproject/trunk@482 74dad513-b988-da41-8d7b-12977e46ad98
diff --git a/pjsip/include/pjsua-lib/pjsua.h b/pjsip/include/pjsua-lib/pjsua.h
index 6484d72..cb2e8b7 100644
--- a/pjsip/include/pjsua-lib/pjsua.h
+++ b/pjsip/include/pjsua-lib/pjsua.h
@@ -68,63 +68,6 @@
#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.
*/
@@ -161,35 +104,6 @@
/**
- * 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.
*/
struct pjsua_config
@@ -247,6 +161,12 @@
/** 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 @@
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 @@
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 @@
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. */
-
-
- /* Account: */
- pjsua_acc acc[PJSUA_MAX_ACC]; /** Client regs array. */
-
-
- /* Threading (optional): */
- pj_thread_t *threads[8]; /**< Thread instances. */
- pj_bool_t quit_flag; /**< To signal thread to quit. */
-
- /* Transport (UDP): */
- pj_sock_t sip_sock; /**< SIP UDP socket. */
- pj_sockaddr_in sip_sock_name; /**< Public/STUN UDP socket addr. */
-
-
- /* PJSUA Calls: */
- int call_cnt; /**< Number of calls. */
- pjsua_call calls[PJSUA_MAX_CALLS]; /** Calls array. */
-
-
- /* SIMPLE and buddy status: */
- int buddy_cnt;
- pjsua_buddy buddies[PJSUA_MAX_BUDDIES];
+ 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;
-/** PJSUA instance. */
-extern struct pjsua pjsua;
+
+enum pjsua_buddy_status
+{
+ PJSUA_BUDDY_STATUS_UNKNOWN,
+ PJSUA_BUDDY_STATUS_ONLINE,
+ PJSUA_BUDDY_STATUS_OFFLINE,
+};
+
+typedef enum pjsua_buddy_status pjsua_buddy_status;
+
+
+/**
+ * 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;
+};
+
+typedef struct pjsua_buddy_info pjsua_buddy_info;
+
+
+/**
+ * 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;
+
+
+typedef int pjsua_player_id;
+typedef int pjsua_recorder_id;
@@ -433,7 +398,7 @@
/**
- * Test configuration.
+ * Validate configuration.
*/
PJ_DECL(pj_status_t) pjsua_test_config(const pjsua_config *cfg,
char *errmsg,
@@ -441,9 +406,8 @@
/**
- * 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_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 @@
/**
* 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 @@
/*****************************************************************************
- * 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);
@@ -552,6 +608,33 @@
*/
/**
+ * 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.
*/
PJ_DECL(void) pjsua_pres_refresh(int acc_index);
@@ -576,19 +659,112 @@
/**
* 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.
*
*/
@@ -609,7 +785,14 @@
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);