Context Navigation

← Previous Change
Next Change →

pjsua.h

Timestamp:

Jan 4, 2007 10:45:08 PM (17 years ago)

Author:

bennylp

Message:

Just updated and improved the doxygen documentations all over the place

File:

: 1 edited

pjproject/trunk/pjsip/include/pjsua-lib/pjsua.h (modified) (66 diffs)

Legend:

: Unmodified
: Added
: Removed

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

-                      r865
+                      r875
  \code
+ #include <pjsua-lib/pjsua.h>
+ #define THIS_FILE  __FILE__
+ static pj_status_t app_init(void)
+ {
     pjsua_config         ua_cfg;
     pjsua_logging_config log_cfg;
     pjsua_media_config   media_cfg;
+    pj_status_t status;
+    // Must create pjsua before anything else!
+    status = pjsua_create();
+    if (status != PJ_SUCCESS) {
+        pjsua_perror(THIS_FILE, "Error initializing pjsua", status);
+        return status;
+    }
     // Initialize configs with default settings.
 …
           return status;
+    }
+    ..
+    .
+    ...
+ }
  \endcode
+ *
 …
  * may add, modify, or delete accounts, buddies, or change media settings
  * during run-time.
+ *
+ * Sample code:
+ \code
+ static pj_status_t app_run(void)
+ {
+    pj_status_t status;
+    // Start pjsua
+    status = pjsua_start();
+    if (status != PJ_SUCCESS) {
+        pjsua_destroy();
+        pjsua_perror(THIS_FILE, "Error starting pjsua", status);
+        return status;
+    }
+    // Run application loop
+    while (1) {
+        char choice[10];
+        printf("Select menu: ");
+        fgets(choice, sizeof(choice), stdin);
+        ...
+    }
+ }
+ \endcode
  */
 …
 /**
+ * Logging configuration.
+ * Logging configuration, which can be (optionally) specified when calling
+ * #pjsua_init(). Application must call #pjsua_logging_config_default() to
+ * initialize this structure with the default values.
  */
 typedef struct pjsua_logging_config
 …
 /**
+ * Application callbacks.
+ * This structure describes application callback to receive various event
+ * notification from PJSUA-API. All of these callbacks are OPTIONAL,
+ * although definitely application would want to implement some of
+ * the important callbacks (such as \a on_incoming_call).
  */
 typedef struct pjsua_callback
 …
     /**
      * Notify application on call being transfered.
+     * Notify application on call being transfered (i.e. REFER is received).
      * Application can decide to accept/reject transfer request
      * by setting the code (default is 200). When this callback
 …
 /**
+ * PJSUA settings.
+ * This structure describes the settings to control the API and
+ * user agent behavior, and can be specified when calling #pjsua_init().
+ * Before setting the values, application must call #pjsua_config_default()
+ * to initialize this structure with the default values.
  */
 typedef struct pjsua_config
 …
     /**
+     * Maximum calls to support (default: 4)
+     * Maximum calls to support (default: 4). The value specified here
+     * must be smaller than the compile time maximum settings
+     * PJSUA_MAX_CALLS, which by default is 32. To increase this
+     * limit, the library must be recompiled with new PJSUA_MAX_CALLS
+     * value.
      */
     unsigned        max_calls;
 …
     /**
      * Number of outbound proxies in the array.
+     * Number of outbound proxies in the \a outbound_proxy array.
      */
     unsigned        outbound_proxy_cnt;
 …
     /**
      * Array of credentials. These credentials will be used by all accounts,
+     * and can be used to authenticate against outbound proxies.
+     * and can be used to authenticate against outbound proxies. If the
+     * credential is specific to the account, then application should set
+     * the credential in the pjsua_acc_config rather than the credential
+     * here.
      */
     pjsip_cred_info cred_info[PJSUA_ACC_MAX_PROXIES];
     /**
+     * Application callback.
+     * Application callback to receive various event notifications from
+     * the library.
      */
     pjsua_callback  cb;
     /**
+     * User agent string (default empty)
+     * Optional user agent string (default empty). If it's empty, no
+     * User-Agent header will be sent with outgoing requests.
      */
     pj_str_t        user_agent;
 …
 /**
  * This structure describes additional information to be sent with
+ * outgoing SIP message.
+ * outgoing SIP message. It can (optionally) be specified for example
+ * with #pjsua_call_make_call(), #pjsua_call_answer(), #pjsua_call_hangup(),
+ * #pjsua_call_set_hold(), #pjsua_call_send_im(), and many more.
+ *
+ * Application MUST call #pjsua_msg_data_init() to initialize this
+ * structure before setting its values.
  */
 typedef struct pjsua_msg_data
 …
  * specified.
+ *
+ * Note that #pjsua_create() MUST be called before calling this function.
+ *
  * @param ua_cfg        User agent configuration.
  * @param log_cfg       Optional logging configuration.
 …
  * additional
+ *
+ * Application may call this function anytime after #pjsua_init().
+ *
  * @return              PJ_SUCCESS on success, or the appropriate error code.
  */
 …
 /**
+ * Destroy pjsua. This function must be called once PJSUA is created. To
+ * make it easier for application, application may call this function
+ * several times with no danger.
+ * Destroy pjsua. Application is recommended to perform graceful shutdown
+ * before calling this function (such as unregister the account from the SIP
+ * server, terminate presense subscription, and hangup active calls), however,
+ * this function will do all of these if it finds there are active sessions
+ * that need to be terminated. This function will approximately block for
+ * one second to wait for replies from remote.
+ *
+ * Application.may safely call this function more than once if it doesn't
+ * keep track of it's state.
+ *
  * @return              PJ_SUCCESS on success, or the appropriate error code.
 …
  * Poll pjsua for events, and if necessary block the caller thread for
  * the specified maximum interval (in miliseconds).
+ *
+ * Application doesn't normally need to call this function if it has
+ * configured worker thread (\a thread_cnt field) in pjsua_config structure,
+ * because polling then will be done by these worker threads instead.
+ *
  * @param msec_timeout  Maximum time to wait, in miliseconds.
 …
 /**
+ * Create memory pool.
+ * Create memory pool to be used by the application. Once application
+ * finished using the pool, it must be released with pj_pool_release().
+ *
  * @param name          Optional pool name.
 …
  * Internal function to get SIP endpoint instance of pjsua, which is
  * needed for example to register module, create transports, etc.
  * Probably is only valid after #pjsua_init() is called.
+ * Only valid after #pjsua_init() is called.
+ *
  * @return              SIP endpoint instance.
 …
 /**
  * Internal function to get PJSUA pool factory.
  * Only valid after #pjsua_init() is called.
+ * Only valid after #pjsua_create() is called.
+ *
  * @return              Pool factory currently used by PJSUA.
 …
 /**
+ * Verify that valid SIP url is given.
+ * This is a utility function to verify that valid SIP url is given. If the
+ * URL is valid, PJ_SUCCESS will be returned.
+ *
  * @param c_url         The URL, as NULL terminated string.
 …
 /**
+ * Display error message for the specified error code.
+ * This is a utility function to display error message for the specified
+ * error code. The error message will be sent to the log.
+ *
  * @param sender        The log sender field.
 …
 /**
+ * STUN configuration.
+ * This structure describes STUN configuration for SIP and media transport,
+ * and is embedded inside pjsua_transport_config structure.
  */
 typedef struct pjsua_stun_config
 …
 /**
  * Transport configuration for creating transports for both SIP
+ * and media.
+ * and media. Before setting some values to this structure, application
+ * MUST call #pjsua_transport_config_default() to initialize its
+ * values with default settings.
  */
 typedef struct pjsua_transport_config
 …
     /**
+     * TLS settings.
+     * This specifies TLS settings for TLS transport. It is only be used
+     * when this transport config is being used to create a SIP TLS
+     * transport.
      */
     pjsip_tls_setting   tls_setting;
 …
+{
     pj_bzero(cfg, sizeof(*cfg));
+    pjsua_stun_config_default(&cfg->stun_config);
     pjsip_tls_setting_default(&cfg->tls_setting);
+}
 …
 /**
+ * Normalize STUN config.
+ * This is a utility function to normalize STUN config. It's only
+ * used internally by the library.
+ *
+ * @param cfg       The STUN config to be initialized.
  */
 PJ_INLINE(void) pjsua_normalize_stun_config( pjsua_stun_config *cfg )
 …
 /**
+ * Transport info.
+ * This structure describes transport information returned by
+ * #pjsua_transport_get_info() function.
  */
 typedef struct pjsua_transport_info
 …
 /**
+ * Create SIP transport.
+ * Create and start a new SIP transport according to the specified
+ * settings.
+ *
  * @param type          Transport type.
 …
  * Close the transport. If transport is forcefully closed, it will be
  * immediately closed, and any pending transactions that are using the
  * transport may not terminate properly. Otherwise, the system will wait
  * until all transactions are closed while preventing new users from
  * using the transport, and will close the transport when it is safe to
  * do so.
+ * transport may not terminate properly (it may even crash). Otherwise,
+ * the system will wait until all transactions are closed while preventing
+ * new users from using the transport, and will close the transport when
+ * it is safe to do so.
+ *
  * @param id            Transport ID.
 …
 /**
+ * Account configuration.
+ * This structure describes account configuration to be specified when
+ * adding a new account with #pjsua_acc_add(). Application MUST initialize
+ * this structure first by calling #pjsua_acc_config_default().
  */
 typedef struct pjsua_acc_config
 …
     /**
+     * Publish presence?
+     * If this flag is set, the presence information of this account will
+     * be PUBLISH-ed to the server where the account belongs.
      */
     pj_bool_t       publish_enabled;
 …
      * These proxies will be put in the route set for this account, with
      * maintaining the orders (the first proxy in the array will be visited
+     * first).
+     * first). If global outbound proxies are configured in pjsua_config,
+     * then these account proxies will be placed after the global outbound
+     * proxies in the routeset.
      */
     pj_str_t        proxy[PJSUA_ACC_MAX_PROXIES];
 …
 /**
+ * Get default account.
+ * Get default account to be used when receiving incoming requests (calls),
+ * when the destination of the incoming call doesn't match any other
+ * accounts.
+ *
  * @return              The default account ID, or PJSUA_INVALID_ID if no
 …
 /**
  * Add a new account to pjsua. PJSUA must have been initialized (with
+ * #pjsua_init()) before calling this function.
+ * #pjsua_init()) before calling this function. If registration is configured
+ * for this account, this function would also start the SIP registration
+ * session with the SIP registrar server. This SIP registration session
+ * will be maintained internally by the library, and application doesn't
+ * need to do anything to maintain the registration session.
+ *
+ *
  * @param cfg           Account configuration.
 …
 /**
+ * Delete account.
+ * Delete an account. This will unregister the account from the SIP server,
+ * if necessary, and terminate server side presence subscriptions associated
+ * with this account.
+ *
  * @param acc_id        Id of the account to be deleted.
 …
 /**
  * Modify account's presence status to be advertised to remote/presence
+ * subscribers.
+ * subscribers. This would trigger the sending of outgoing NOTIFY request
+ * if there are server side presence subscription for this account.
+ *
  * @param acc_id        The account ID.
 …
 /**
+ * Update registration or perform unregistration.
+ * Update registration or perform unregistration. If registration is
+ * configured for this account, then initial SIP REGISTER will be sent
+ * when the account is added with #pjsua_acc_add(). Application normally
+ * only need to call this function if it wants to manually update the
+ * registration or to unregister from the server.
+ *
  * @param acc_id        The account ID.
 …
 /**
  * Get account information.
+ * Get information about the specified account.
+ *
  * @param acc_id        Account identification.
 …
 /**
+ * Enum accounts all account ids.
+ * Enumerate all account currently active in the library. This will fill
+ * the array with the account Ids, and application can then query the
+ * account information for each id with #pjsua_acc_get_info().
+ *
+ * @see pjsua_acc_enum_info().
+ *
  * @param ids           Array of account IDs to be initialized.
 …
 /**
  * Enum accounts info.
+ * Enumerate account informations.
+ *
  * @param info          Array of account infos to be initialized.
 …
 /**
  * Max simultaneous calls.
+ * Maximum simultaneous calls.
  */
 #ifndef PJSUA_MAX_CALLS
 …
 /**
+ * Call media status.
+ * This enumeration specifies the media status of a call, and it's part
+ * of pjsua_call_info structure.
  */
 typedef enum pjsua_call_media_status
+{
+    /** Call currently has no media */
     PJSUA_CALL_MEDIA_NONE,
+    /** The media is active */
     PJSUA_CALL_MEDIA_ACTIVE,
+    /** The media is currently put on hold by local endpoint */
     PJSUA_CALL_MEDIA_LOCAL_HOLD,
+    /** The media is currently put on hold by remote endpoint */
     PJSUA_CALL_MEDIA_REMOTE_HOLD,
 } pjsua_call_media_status;
 /**
  * Call info.
+ * This structure describes the information and current status of a call.
  */
 typedef struct pjsua_call_info
 …
 /**
+ * Enumerate all active calls.
+ * Enumerate all active calls. Application may then query the information and
+ * state of each call by calling #pjsua_call_get_info().
+ *
  * @param ids           Array of account IDs to be initialized.
 …
 /**
+ * Attach application specific data to the call.
+ * Attach application specific data to the call. Application can then
+ * inspect this data by calling #pjsua_call_get_user_data().
+ *
  * @param call_id       Call identification.
 …
 /**
+ * Get user data attached to the call.
+ * Get user data attached to the call, which has been previously set with
+ * #pjsua_call_set_user_data().
+ *
  * @param call_id       Call identification.
 …
 /**
+ * Send response to incoming INVITE request.
+ * Send response to incoming INVITE request. Depending on the status
+ * code specified as parameter, this function may send provisional
+ * response, establish the call, or terminate the call.
+ *
  * @param call_id       Incoming call identification.
 …
 /**
  * Hangup call by using method that is appropriate according to the
+ * call state.
+ * call state. This function is different than answering the call with
+ * 3xx-6xx response (with #pjsua_call_answer()), in that this function
+ * will hangup the call regardless of the state and role of the call,
+ * while #pjsua_call_answer() only works with incoming calls on EARLY
+ * state.
+ *
  * @param call_id       Call identification.
 …
 /**
+ * Put the specified call on hold.
+ * Put the specified call on hold. This will send re-INVITE with the
+ * appropriate SDP to inform remote that the call is being put on hold.
+ * The final status of the request itself will be reported on the
+ * \a on_call_media_state() callback, which inform the application that
+ * the media state of the call has changed.
+ *
  * @param call_id       Call identification.
 …
 /**
+ * Send re-INVITE (to release hold).
+ * Send re-INVITE to release hold.
+ * The final status of the request itself will be reported on the
+ * \a on_call_media_state() callback, which inform the application that
+ * the media state of the call has changed.
+ *
  * @param call_id       Call identification.
 …
  * REFER request to instruct remote call party to initiate a new INVITE
  * session to the specified destination/target.
+ *
+ * If application is interested to monitor the successfulness and
+ * the progress of the transfer request, it can implement
+ * \a on_call_transfer_status() callback which will report the progress
+ * of the call transfer request.
+ *
  * @param call_id       The call id to be transfered.
 …
 /**
+ * Terminate all calls.
+ * Terminate all calls. This will initiate #pjsua_call_hangup() for all
+ * currently active calls.
  */
 PJ_DECL(void) pjsua_call_hangup_all(void);
 …
 /**
+ * Buddy configuration.
+ * This structure describes buddy configuration when adding a buddy to
+ * the buddy list with #pjsua_buddy_add(). Application MUST initialize
+ * the structure with #pjsua_buddy_config_default() to initialize this
+ * structure with default configuration.
  */
 typedef struct pjsua_buddy_config
 …
 /**
  * Buddy's online status.
+ * This enumeration describes basic buddy's online status.
  */
 typedef enum pjsua_buddy_status
 …
 /**
+ * Buddy info.
+ * This structure describes buddy info, which can be retrieved by calling
+ * #pjsua_buddy_get_info().
  */
 typedef struct pjsua_buddy_info
 …
 /**
+ * Set default values to the buddy config.
+ */
+PJ_INLINE(void) pjsua_buddy_config_default(pjsua_buddy_config *cfg)
+{
+    pj_bzero(cfg, sizeof(*cfg));
+}
+/**
  * Get total number of buddies.
+ *
 …
 /**
+ * Enum buddy IDs.
+ * Enumerate all buddy IDs in the buddy list. Application then can use
+ * #pjsua_buddy_get_info() to get the detail information for each buddy
+ * id.
+ *
  * @param ids           Array of ids to be initialized.
 …
 /**
+ * Add new buddy.
+ * Add new buddy to the buddy list. If presence subscription is enabled
+ * for this buddy, this function will also start the presence subscription
+ * session immediately.
+ *
  * @param cfg           Buddy configuration.
 …
 /**
+ * Delete buddy.
+ * Delete the specified buddy from the buddy list. Any presence subscription
+ * to this buddy will be terminated.
+ *
  * @param buddy_id      Buddy identification.
 …
 /**
+ * Enable/disable buddy's presence monitoring.
+ * Enable/disable buddy's presence monitoring. Once buddy's presence is
+ * subscribed, application will be informed about buddy's presence status
+ * changed via \a on_buddy_state() callback.
+ *
  * @param buddy_id      Buddy identification.
 …
 /**
  * Dump presence subscriptions to log file.
+ * Dump presence subscriptions to log.
+ *
  * @param verbose       Yes or no.
 …
 #endif
+/**
+ * The default clock rate to be used by the conference bridge.
+ */
 #ifndef PJSUA_DEFAULT_CLOCK_RATE
 #   define PJSUA_DEFAULT_CLOCK_RATE     16000
 #endif
+/**
+ * Default codec quality settings.
+ */
 #ifndef PJSUA_DEFAULT_CODEC_QUALITY
 #   define PJSUA_DEFAULT_CODEC_QUALITY  5
 #endif
+/**
+ * Default iLBC mode.
+ */
 #ifndef PJSUA_DEFAULT_ILBC_MODE
 #   define PJSUA_DEFAULT_ILBC_MODE      20
 #endif
+/**
+ * The default echo canceller tail length.
+ */
 #ifndef PJSUA_DEFAULT_EC_TAIL_LEN
 #   define PJSUA_DEFAULT_EC_TAIL_LEN    800
 …
 /**
+ * Media configuration.
+ * This structure describes media configuration, which will be specified
+ * when calling #pjsua_init(). Application MUST initialize this structure
+ * by calling #pjsua_media_config_default().
  */
 struct pjsua_media_config
 …
     /**
      * Clock rate to be applied to the conference bridge.
+     * If value is zero, default clock rate will be used (16KHz).
+     * If value is zero, default clock rate will be used
+     * (PJSUA_DEFAULT_CLOCK_RATE, which by default is 16KHz).
      */
     unsigned            clock_rate;
 …
 /**
+ * Codec config.
+ * This structure describes codec information, which can be retrieved by
+ * calling #pjsua_enum_codecs().
  */
 typedef struct pjsua_codec_info
 …
 /**
+ * Conference port info.
+ * This structure descibes information about a particular media port that
+ * has been registered into the conference bridge. Application can query
+ * this info by calling #pjsua_conf_get_port_info().
  */
 typedef struct pjsua_conf_port_info
 …
 /**
  * Remove arbitrary slot from the conference bridge. Application should only
+ * call this function if it registered the port manually.
+ * call this function if it registered the port manually with previous call
+ * to #pjsua_conf_add_port().
+ *
  * @param id            The slot id of the port to be removed.
 …
 /**
  * Enum sound devices.
+ * Enum all sound devices installed in the system.
+ *
  * @param info          Array of info to be initialized.

Note: See TracChangeset for help on using the changeset viewer.

Context Navigation

Changeset 875 for pjproject/trunk/pjsip/include/pjsua-lib/pjsua.h

Legend:

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

Download in other formats: