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

1 files changed, 323 insertions, 140 deletions

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.
  */
@@ -161,35 +104,6 @@ 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.
  */
 struct pjsua_config
@@ -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);
 
 
 
@@ -552,6 +608,33 @@ PJ_DECL(void) pjsua_regc_update(int acc_index, pj_bool_t renew);
  */
 
 /**
+ * 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 @@ 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.
  *
  */
@@ -609,7 +785,14 @@ 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);