From 10961f86b5142d327b6327072b29172046451b2c Mon Sep 17 00:00:00 2001 From: Benny Prijono Date: Wed, 31 Jan 2007 20:53:31 +0000 Subject: Updated PJSUA-API docs for Python and some bug fixes in Python module git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@918 74dad513-b988-da41-8d7b-12977e46ad98 --- pjsip/include/pjsua-lib/pjsua.h | 1205 ++++++++++++++++++++++++++++++++++++--- 1 file changed, 1129 insertions(+), 76 deletions(-) (limited to 'pjsip/include/pjsua-lib/pjsua.h') diff --git a/pjsip/include/pjsua-lib/pjsua.h b/pjsip/include/pjsua-lib/pjsua.h index efa21b32..36368bb1 100644 --- a/pjsip/include/pjsua-lib/pjsua.h +++ b/pjsip/include/pjsua-lib/pjsua.h @@ -47,19 +47,26 @@ #include +PJ_BEGIN_DECL + + /** - * @defgroup PJSUA_LIB PJSUA API + * @defgroup PJSUA_LIB PJSUA API - High Level Softphone API for C/C++ and Python * @ingroup PJSIP * @brief Very high level API for constructing SIP UA applications. * @{ * - * PJSUA API is very high level API for constructing SIP user agent + * @section pjsua_api_intro A SIP User Agent API for C/C++ and Python + * + * PJSUA API is very high level API, available for C/C++ and Python language, + * for constructing SIP multimedia user agent * applications. It wraps together the signaling and media functionalities * into an easy to use call API, provides account management, buddy * management, presence, instant messaging, along with multimedia * features such as conferencing, file streaming, local playback, * voice recording, and so on. * + * @subsection pjsua_for_c_cpp C/C++ Binding * Application must link with pjsua-lib to use this API. In addition, * this library depends on the following libraries: * - pjsip-ua, @@ -70,18 +77,49 @@ * - pjlib-util, and * - pjlib, * - * so application must also link with these libraries as well. + * so application must also link with these libraries as well. For more + * information, please refer to + * Getting Started with PJSIP + * page. * - * @section root_using_pjsua_lib Using PJSUA API + * @subsection pjsua_for_python Python Binding * - * Please refer to @ref using_pjsua_lib on how to use PJSUA API. - */ + * The Python binding for PJSUA-API is implemented by py_pjsua + * module, in pjsip-apps/py_pjsua directory. This module is + * built by building py_pjsua project in pjsip_apps + * Visual Studio workspace, or by invoking the usual setup.py + * Python installer script. + * + * The Python script then can import the PJSUA-API Python module by + * using import py_pjsua construct as usual. + * + * + * @section pjsua_samples + * + * Few samples are provided both in C and Python. + * + - @ref page_pjsip_sample_simple_pjsuaua_c\n + Very simple SIP User Agent with registration, call, and media, using + PJSUA-API, all in under 200 lines of code. -PJ_BEGIN_DECL + - @ref page_pjsip_samples_pjsua\n + This is the reference implementation for PJSIP and PJMEDIA. + PJSUA is a console based application, designed to be simple enough + to be readble, but powerful enough to demonstrate all features + available in PJSIP and PJMEDIA.\n + - Python sample\n + For a real simple Python sample application, have a look at + + pjsip-apps/src/py_pjsua/pjsua_app.py file. + + * @section root_using_pjsua_lib Using PJSUA API + * + * Please refer to @ref PJSUA_LIB_BASE on how to create and initialize the API. + * And then see the Modules on the bottom of this page for more information + * about specific subject. + */ -/** Forward declaration */ -typedef struct pjsua_media_config pjsua_media_config; /***************************************************************************** @@ -89,7 +127,7 @@ typedef struct pjsua_media_config pjsua_media_config; */ /** - * @defgroup PJSUA_LIB_BASE Base API + * @defgroup PJSUA_LIB_BASE PJSUA-API Basic API * @ingroup PJSUA_LIB * @brief Basic application creation/initialization, logging configuration, etc. * @{ @@ -101,18 +139,23 @@ typedef struct pjsua_media_config pjsua_media_config; * * @subsection creating_pjsua_lib Creating PJSUA * - * Before anything else, application must create PJSUA by calling #pjsua_create(). + * Before anything else, application must create PJSUA by calling #pjsua_create() + * (or py_pjsua.create() from Python). * This, among other things, will initialize PJLIB, which is crucial before - * any PJLIB functions can be called. + * any PJLIB functions can be called, PJLIB-UTIL, and create a SIP endpoint. + * + * After this function is called, application can create a memory pool (with + * #pjsua_pool_create()) and read configurations from command line or file to + * build the settings to initialize PJSUA below. * * @subsection init_pjsua_lib Initializing PJSUA * * After PJSUA is created, application can initialize PJSUA by calling - * #pjsua_init(). This function takes several configuration settings in the - * argument, so application normally would want to set these configuration - * before passing them to #pjsua_init(). + * #pjsua_init(). This function takes several optional configuration settings + * in the argument, if application wants to set them. * - * Sample code to initialize PJSUA: + * @subsubsection init_pjsua_lib_c_cpp PJSUA-LIB Initialization (in C) + * Sample code to initialize PJSUA in C code: \code #include @@ -159,15 +202,72 @@ typedef struct pjsua_media_config pjsua_media_config; } \endcode * + * + * @subsubsection init_pjsua_lib_python PJSUA-LIB Initialization (in Python) + * Sample code to initialize PJSUA in Python code: + + \code + +import py_pjsua + +# +# Initialize pjsua. +# +def app_init(): + # Create pjsua before anything else + status = py_pjsua.create() + if status != 0: + err_exit("pjsua create() error", status) + + # We use default logging config for this sample + log_cfg = py_pjsua.logging_config_default() + + # Create and initialize pjsua config + # Note: for this Python module, thread_cnt must be 0 since Python + # doesn't like to be called from alien thread (pjsua's thread + # in this case) + ua_cfg = py_pjsua.config_default() + ua_cfg.thread_cnt = 0 + ua_cfg.user_agent = "PJSUA/Python 0.1" + + # Override callbacks. At the very least application would want to + # override the call callbacks in pjsua_config + ua_cfg.cb.on_incoming_call = ... + ua_cfg.cb.on_call_state = ... + + # Use default media config for this cample + med_cfg = py_pjsua.media_config_default() + + # + # Initialize pjsua!! + # + status = py_pjsua.init(ua_cfg, log_cfg, med_cfg) + if status != 0: + err_exit("pjsua init() error", status) + + + +# Utility: display PJ error and exit +# +def err_exit(title, rc): + py_pjsua.perror(THIS_FILE, title, rc) + exit(1) + + \endcode + + * @subsection other_init_pjsua_lib Other Initialization * * After PJSUA is initialized with #pjsua_init(), application will normally * need/want to perform the following tasks: * - * - create SIP transport with #pjsua_transport_create(). Please see + * - create SIP transport with #pjsua_transport_create(). Application would + * to call #pjsua_transport_create() for each transport types that it + * wants to support (for example, UDP, TCP, and TLS). Please see * @ref PJSUA_LIB_TRANSPORT section for more info. * - create one or more SIP accounts with #pjsua_acc_add() or - * #pjsua_acc_add_local(). Please see @ref PJSUA_LIB_ACC for more info. + * #pjsua_acc_add_local(). The SIP account is used for registering with + * the SIP server, if any. Please see @ref PJSUA_LIB_ACC for more info. * - add one or more buddies with #pjsua_buddy_add(). Please see * @ref PJSUA_LIB_BUDDY section for more info. * - optionally configure the sound device, codec settings, and other @@ -178,13 +278,14 @@ typedef struct pjsua_media_config pjsua_media_config; * * After all initializations have been done, application must call * #pjsua_start() to start PJSUA. This function will check that all settings - * are properly configured, and apply default settings when it's not, or - * report error status when it is unable to recover from missing setting. + * have been properly configured, and apply default settings when they haven't, + * or report error status when it is unable to recover from missing settings. * * Most settings can be changed during run-time. For example, application * may add, modify, or delete accounts, buddies, or change media settings * during run-time. * + * @subsubsection starting_pjsua_lib_c C Example for Starting PJSUA * Sample code: \code static pj_status_t app_run(void) @@ -208,6 +309,64 @@ typedef struct pjsua_media_config pjsua_media_config; ... } } + \endcode + + * @subsubsection starting_pjsua_lib_python Python Example for starting PJSUA + * For Python, starting PJSUA-LIB takes one more step, that is to initialize + * Python worker thread to poll PJSUA-LIB. This step is necessary because + * Python doesn't like it when it is called by an "alien" thread (that is, + * thread that is not created using Python API). + * + * Because of this, we cannot use a worker thread in PJSUA-LIB, because then + * the Python callback will be called by an "alien" thread and this would + * crash Python (or raise assert() probably). + * + * So because worker thread is disabled, we need to create a worker thread + * in Python. Note that this may not be necessary if we're creating a + * GUI application, because then we can attach, for example, a GUI timer + * object to poll the PJSUA-LIB. But because we're creating a console + * application which will block at sys.stdin.readline(), we need + * to have a worker thread to poll PJSUA-LIB. + + \code + +import thread + +C_QUIT = 0 + + +def app_start(): + # Done with initialization, start pjsua!! + # + status = py_pjsua.start() + if status != 0: + py_pjsua.destroy() + err_exit("Error starting pjsua!", status) + + # Start worker thread + thr = thread.start_new(worker_thread_main, (0,)) + + print "PJSUA Started!!" + +# +# Worker thread function. +# Python doesn't like it when it's called from an alien thread +# (pjsua's worker thread, in this case), so for Python we must +# disable worker thread in pjsua and poll pjsua from Python instead. +# +def worker_thread_main(arg): + global C_QUIT + thread_desc = 0 + status = py_pjsua.thread_register("python worker", thread_desc) + if status != 0: + py_pjsua.perror(THIS_FILE, "Error registering thread", status) + else: + while C_QUIT == 0: + py_pjsua.handle_events(50) + print "Worker thread quitting.." + C_QUIT = 2 + + \endcode */ @@ -247,6 +406,14 @@ typedef int pjsua_conf_port_id; * 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. + * + * \par Sample Python Syntax: + * \code + # Python type: py_pjsua.Logging_Config + + log_cfg = py_pjsua.logging_config_default() + log_cfg.level = 4 + * \endcode */ typedef struct pjsua_logging_config { @@ -279,6 +446,16 @@ typedef struct pjsua_logging_config * Optional callback function to be called to write log to * application specific device. This function will be called for * log messages on input verbosity level. + * + * \par Sample Python Syntax: + * \code + # level: integer + # data: string + # len: integer + + def cb(level, data, len): + print data, + * \endcode */ void (*cb)(int level, const char *data, pj_size_t len); @@ -290,6 +467,12 @@ typedef struct pjsua_logging_config * Use this function to initialize logging config. * * @param cfg The logging config to be initialized. + * + * \par Python Syntax: + * The Python function instantiates and initialize the logging config: + * \code + logging_cfg = py_pjsua.logging_config_default() + * \endcode */ PJ_INLINE(void) pjsua_logging_config_default(pjsua_logging_config *cfg) { @@ -308,6 +491,10 @@ PJ_INLINE(void) pjsua_logging_config_default(pjsua_logging_config *cfg) * @param pool Pool to use. * @param dst Destination config. * @param src Source config. + * + * \par Python Syntax: + * Not available (for now). Ideally we should be able to just assign + * one config to another, but this has not been tested. */ PJ_INLINE(void) pjsua_logging_config_dup(pj_pool_t *pool, pjsua_logging_config *dst, @@ -324,16 +511,28 @@ PJ_INLINE(void) pjsua_logging_config_dup(pj_pool_t *pool, * 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). + * + * \par Python Syntax: + * This callback structure is embedded on pjsua_config structure. */ typedef struct pjsua_callback { /** * Notify application when invite state has changed. * Application may then query the call info to get the - * detail call states. + * detail call states by calling pjsua_call_get_info() function. * * @param call_id The call index. * @param e Event which causes the call state to change. + * + * \par Python Syntax: + * \code + # call_id: integer + # e: an opaque object + + def on_call_state(call_id, e): + return + * \endcode */ void (*on_call_state)(pjsua_call_id call_id, pjsip_event *e); @@ -344,6 +543,16 @@ typedef struct pjsua_callback * @param call_id The call id that has just been created for * the call. * @param rdata The incoming INVITE request. + * + * \par Python Syntax: + * \code + # acc_id: integer + # call_id: integer + # rdata: an opaque object + + def on_incoming_call(acc_id, call_id, rdata): + return + * \endcode */ void (*on_incoming_call)(pjsua_acc_id acc_id, pjsua_call_id call_id, pjsip_rx_data *rdata); @@ -354,6 +563,14 @@ typedef struct pjsua_callback * to connect the call's media to sound device. * * @param call_id The call index. + * + * \par Python Syntax: + * \code + # call_id: integer + + def on_call_media_state(call_id): + return + * \endcode */ void (*on_call_media_state)(pjsua_call_id call_id); @@ -362,6 +579,15 @@ typedef struct pjsua_callback * * @param call_id The call index. * @param digit DTMF ASCII digit. + * + * \par Python Syntax: + * \code + # call_id: integer + # digit: integer + + def on_dtmf_digit(call_id, digit): + return + * \endcode */ void (*on_dtmf_digit)(pjsua_call_id call_id, int digit); @@ -377,6 +603,17 @@ typedef struct pjsua_callback * transfered to. * @param code Status code to be returned for the call transfer * request. On input, it contains status code 200. + * + * \par Python Syntax: + * \code + # call_id: integer + # dst: string + # code: integer + + def on_call_transfer_request(call_id, dst, code): + return code + + * \endcode */ void (*on_call_transfer_request)(pjsua_call_id call_id, const pj_str_t *dst, @@ -389,19 +626,33 @@ typedef struct pjsua_callback * terminate existing call. * * @param call_id Call ID. - * @param status_code Status progress of the transfer request. - * @param status_text Status progress text. + * @param st_code Status progress of the transfer request. + * @param st_text Status progress text. * @param final If non-zero, no further notification will - * be reported. The status_code specified in + * be reported. The st_code specified in * this callback is the final status. * @param p_cont Initially will be set to non-zero, application * can set this to FALSE if it no longer wants * to receie further notification (for example, * after it hangs up the call). + * + * \par Python Syntax: + * \code + # call_id: integer + # st_code: integer + # st_text: string + # final: integer + # cont: integer + + # return: cont + + def on_call_transfer_status(call_id, st_code, st_text, final, cont): + return cont + * \endcode */ void (*on_call_transfer_status)(pjsua_call_id call_id, - int status_code, - const pj_str_t *status_text, + int st_code, + const pj_str_t *st_text, pj_bool_t final, pj_bool_t *p_cont); @@ -414,6 +665,19 @@ typedef struct pjsua_callback * @param st_code Status code to be set by application. Application * should only return a final status (200-699). * @param st_text Optional status text to be set by application. + * + * \par Python Syntax: + * \code + # call_id: integer + # rdata: an opaque object + # st_code: integer + # st_text: string + + # return: (st_code, st_text) tuple + + def on_call_replace_request(call_id, rdata, st_code, st_text): + return st_code, st_text + * \endcode */ void (*on_call_replace_request)(pjsua_call_id call_id, pjsip_rx_data *rdata, @@ -432,6 +696,15 @@ typedef struct pjsua_callback * new call. * @param new_call_id The new call. * @param rdata The incoming INVITE with Replaces request. + * + * \par Python Syntax: + * \code + # old_call_id: integer + # new_call_id: integer + + def on_call_replaced(old_call_id, new_call_id): + return + * \endcode */ void (*on_call_replaced)(pjsua_call_id old_call_id, pjsua_call_id new_call_id); @@ -443,6 +716,14 @@ typedef struct pjsua_callback * registration details. * * @param acc_id Account ID. + * + * \par Python Syntax: + * \code + # acc_id: account ID (integer) + + def on_reg_state(acc_id): + return + * \endcode */ void (*on_reg_state)(pjsua_acc_id acc_id); @@ -451,6 +732,14 @@ typedef struct pjsua_callback * Application may then query the buddy into to get the details. * * @param buddy_id The buddy id. + * + * \par Python Syntax: + * \code + # buddy_id: integer + + def on_buddy_state(buddy_id): + return + * \endcode */ void (*on_buddy_state)(pjsua_buddy_id buddy_id); @@ -467,6 +756,19 @@ typedef struct pjsua_callback * @param contact The Contact URI of the sender, if present. * @param mime_type MIME type of the message. * @param body The message content. + * + * \par Python Syntax: + * \code + # call_id: integer + # from: string + # to: string + # contact: string + # mime_type: string + # body: string + + def on_pager(call_id, from, to, contact, mime_type, body): + return + * \endcode */ void (*on_pager)(pjsua_call_id call_id, const pj_str_t *from, const pj_str_t *to, const pj_str_t *contact, @@ -485,6 +787,19 @@ typedef struct pjsua_callback * IM message. * @param status Delivery status. * @param reason Delivery status reason. + * + * \par Python Syntax + * \code + # call_id: integer + # to: string + # body: string + # user_data: string + # status: integer + # reason: string + + def on_pager_status(call_id, to, body, user_data, status, reason): + return + * \endcode */ void (*on_pager_status)(pjsua_call_id call_id, const pj_str_t *to, @@ -504,6 +819,18 @@ typedef struct pjsua_callback * @param contact The Contact URI of the sender, if present. * @param is_typing Non-zero if peer is typing, or zero if peer * has stopped typing a message. + * + * \par Python Syntax + * \code + # call_id: string + # from: string + # to: string + # contact: string + # is_typing: integer + + def on_typing(call_id, from, to, contact, is_typing): + return + * \endcode */ void (*on_typing)(pjsua_call_id call_id, const pj_str_t *from, const pj_str_t *to, const pj_str_t *contact, @@ -519,6 +846,13 @@ typedef struct pjsua_callback * 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. + * + * \par Python Sample Syntax: + * The pjsua_config type in Python is py_pjsua.Config. Application + * creates the instance by calling py_pjsua.config_default(): + * \code + cfg = py_pjsua.config_default() + * \endcode */ typedef struct pjsua_config { @@ -601,6 +935,14 @@ typedef struct pjsua_config * Use this function to initialize pjsua config. * * @param cfg pjsua config to be initialized. + * + * \par Python Sample Syntax: + * The corresponding Python function creates an instance of the config and + * initializes it to the default settings: + * \code + cfg = py_pjsua.config_default() + * \endcode + */ PJ_INLINE(void) pjsua_config_default(pjsua_config *cfg) { @@ -613,6 +955,14 @@ PJ_INLINE(void) pjsua_config_default(pjsua_config *cfg) /** * Duplicate credential. + * + * @param pool The memory pool. + * @param dst Destination credential. + * @param src Source credential. + * + * \par Python: + * Not applicable (for now). Probably we could just assign one credential + * variable to another, but this has not been tested. */ PJ_INLINE(void) pjsip_cred_dup( pj_pool_t *pool, pjsip_cred_info *dst, @@ -628,6 +978,10 @@ PJ_INLINE(void) pjsip_cred_dup( pj_pool_t *pool, /** * Duplicate pjsua_config. + * + * @param pool The pool to get memory from. + * @param dst Destination config. + * @param src Source config. */ PJ_INLINE(void) pjsua_config_dup(pj_pool_t *pool, pjsua_config *dst, @@ -659,11 +1013,26 @@ PJ_INLINE(void) pjsua_config_dup(pj_pool_t *pool, * * Application MUST call #pjsua_msg_data_init() to initialize this * structure before setting its values. + * + * \par Python Syntax + * The data type in Python is py_pjsua.Msg_Data. Application is + * recommended to instantiate the structure by using this construct: + * \code + msg_data = py_pjsua.msg_data_init() + * \endcode */ typedef struct pjsua_msg_data { /** * Additional message headers as linked list. + * + * \par Python: + * This field is implemented as string linked-list in Python, where each + * string describes the header. For example: + \code + msg_data = py_pjsua.Msg_Data() + msg_data.hdr_list = ["Subject: Hello py_pjsua!", "Priority: very low"] + \endcode */ pjsip_hdr hdr_list; @@ -684,6 +1053,12 @@ typedef struct pjsua_msg_data * Initialize message data. * * @param msg_data Message data to be initialized. + * + * \par Python + * The corresponding Python function creates and initializes the structure: + * \code + msg_data = py_pjsua.msg_data_init() + * \endcode */ PJ_INLINE(void) pjsua_msg_data_init(pjsua_msg_data *msg_data) { @@ -700,10 +1075,19 @@ PJ_INLINE(void) pjsua_msg_data_init(pjsua_msg_data *msg_data) * application must call pjsua_destroy() before quitting. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * \code + status = py_pjsua.create() + * \endcode */ PJ_DECL(pj_status_t) pjsua_create(void); +/* Forward declaration */ +typedef struct pjsua_media_config pjsua_media_config; + + /** * Initialize pjsua with the specified settings. All the settings are * optional, and the default values will be used when the config is not @@ -716,6 +1100,15 @@ PJ_DECL(pj_status_t) pjsua_create(void); * @param media_cfg Optional media configuration. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * The function is similar in Python: + * \code + status = py_pjsua.init(ua_cfg, log_cfg, media_cfg) + * \endcode + * Note that \a ua_cfg, \a log_cfg, and \a media_cfg are optional, and + * the Python script may pass None if it doesn't want to configure the + * setting. */ PJ_DECL(pj_status_t) pjsua_init(const pjsua_config *ua_cfg, const pjsua_logging_config *log_cfg, @@ -730,6 +1123,12 @@ PJ_DECL(pj_status_t) pjsua_init(const pjsua_config *ua_cfg, * Application may call this function anytime after #pjsua_init(). * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * The function is similar in Python: + * \code + status = py_pjsua.start() + * \endcode */ PJ_DECL(pj_status_t) pjsua_start(void); @@ -746,6 +1145,12 @@ PJ_DECL(pj_status_t) pjsua_start(void); * keep track of it's state. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * The function is similar in Python: + * \code + status = py_pjsua.destroy() + * \endcode */ PJ_DECL(pj_status_t) pjsua_destroy(void); @@ -762,7 +1167,13 @@ PJ_DECL(pj_status_t) pjsua_destroy(void); * * @return The number of events that have been handled during the * poll. Negative value indicates error, and application - * can retrieve the error as (err = -return_value). + * can retrieve the error as (status = -return_value). + * + * \par Python: + * The function is similar in Python: + * \code + n = py_pjsua.handle_events(msec_timeout) + * \endcode */ PJ_DECL(int) pjsua_handle_events(unsigned msec_timeout); @@ -776,6 +1187,12 @@ PJ_DECL(int) pjsua_handle_events(unsigned msec_timeout); * @param increment Increment size. * * @return The pool, or NULL when there's no memory. + * + * \par Python: + * Python script may also create a pool object from the script: + * \code + pool = py_pjsua.pool_create(name, init_size, increment) + * \endcode */ PJ_DECL(pj_pool_t*) pjsua_pool_create(const char *name, pj_size_t init_size, pj_size_t increment); @@ -788,6 +1205,12 @@ PJ_DECL(pj_pool_t*) pjsua_pool_create(const char *name, pj_size_t init_size, * @param c Logging configuration. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * The function is similar in Python: + * \code + status = py_pjsua.reconfigure_logging(log_cfg) + * \endcode */ PJ_DECL(pj_status_t) pjsua_reconfigure_logging(const pjsua_logging_config *c); @@ -798,6 +1221,14 @@ PJ_DECL(pj_status_t) pjsua_reconfigure_logging(const pjsua_logging_config *c); * Only valid after #pjsua_init() is called. * * @return SIP endpoint instance. + * + * \par Python: + * Application may retrieve the SIP endpoint instance: + * \code + endpt = py_pjsua.get_pjsip_endpt() + * \endcode + * However currently the object is just an opaque object and does not have + * any use for Python scripts. */ PJ_DECL(pjsip_endpoint*) pjsua_get_pjsip_endpt(void); @@ -806,6 +1237,14 @@ PJ_DECL(pjsip_endpoint*) pjsua_get_pjsip_endpt(void); * Only valid after #pjsua_init() is called. * * @return Media endpoint instance. + * + * \par Python: + * Application may retrieve the media endpoint instance: + * \code + endpt = py_pjsua.get_pjmedia_endpt() + * \endcode + * However currently the object is just an opaque object and does not have + * any use for Python scripts. */ PJ_DECL(pjmedia_endpt*) pjsua_get_pjmedia_endpt(void); @@ -814,6 +1253,14 @@ PJ_DECL(pjmedia_endpt*) pjsua_get_pjmedia_endpt(void); * Only valid after #pjsua_create() is called. * * @return Pool factory currently used by PJSUA. + * + * \par Python: + * Application may retrieve the pool factory instance: + * \code + endpt = py_pjsua.get_pool_factory() + * \endcode + * However currently the object is just an opaque object and does not have + * any use for Python scripts. */ PJ_DECL(pj_pool_factory*) pjsua_get_pool_factory(void); @@ -828,11 +1275,16 @@ PJ_DECL(pj_pool_factory*) pjsua_get_pool_factory(void); * 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. + * @param url The URL, as NULL terminated string. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * \code + status = py_pjsua.verify_sip_url(url) + * \endcode */ -PJ_DECL(pj_status_t) pjsua_verify_sip_url(const char *c_url); +PJ_DECL(pj_status_t) pjsua_verify_sip_url(const char *url); /** @@ -842,6 +1294,11 @@ PJ_DECL(pj_status_t) pjsua_verify_sip_url(const char *c_url); * @param sender The log sender field. * @param title Message title for the error. * @param status Status code. + * + * \par Python: + * \code + py_pjsua.perror(sender, title, status) + * \endcode */ PJ_DECL(void) pjsua_perror(const char *sender, const char *title, pj_status_t status); @@ -860,16 +1317,19 @@ PJ_DECL(void) pjsua_perror(const char *sender, const char *title, */ /** - * @defgroup PJSUA_LIB_TRANSPORT Signaling Transport + * @defgroup PJSUA_LIB_TRANSPORT PJSUA-API Signaling Transport * @ingroup PJSUA_LIB * @brief API for managing SIP transports * @{ - * SIP transport must be created before adding an account. SIP transport is - * created by calling #pjsua_transport_create() function. + * + * PJSUA-API supports creating multiple transport instances, for example UDP, + * TCP, and TLS transport. SIP transport must be created before adding an + * account. */ -/** SIP transport identification */ +/** SIP transport identification. + */ typedef int pjsua_transport_id; @@ -909,8 +1369,17 @@ typedef struct pjsua_stun_config /** * Call this function to initialize STUN config with default values. + * STUN config is normally embedded inside pjsua_transport_config, so + * normally there is no need to call this function and rather just + * call pjsua_transport_config_default() instead. * * @param cfg The STUN config to be initialized. + * + * \par Python: + * The corresponding Python function creates and initialize the config: + * \code + stun_cfg = py_pjsua.stun_config_default() + * \endcode */ PJ_INLINE(void) pjsua_stun_config_default(pjsua_stun_config *cfg) { @@ -923,6 +1392,13 @@ PJ_INLINE(void) pjsua_stun_config_default(pjsua_stun_config *cfg) * and media. Before setting some values to this structure, application * MUST call #pjsua_transport_config_default() to initialize its * values with default settings. + * + * \par Python: + * The data type in Python is py_pjsua.Transport_Config, + * although application can just do this to create the instance: + * \code + transport_cfg = py_pjsua.transport_config_default() + * \endcode */ typedef struct pjsua_transport_config { @@ -982,6 +1458,12 @@ typedef struct pjsua_transport_config * Call this function to initialize UDP config with default values. * * @param cfg The UDP config to be initialized. + * + * \par Python: + * The corresponding Python function is rather different: + * \code + transport_cfg = py_pjsua.transport_config_default() + * \endcode */ PJ_INLINE(void) pjsua_transport_config_default(pjsua_transport_config *cfg) { @@ -996,6 +1478,11 @@ PJ_INLINE(void) pjsua_transport_config_default(pjsua_transport_config *cfg) * used internally by the library. * * @param cfg The STUN config to be initialized. + * + * \par Python: + * \code + py_pjsua.normalize_stun_config(cfg) + * \code */ PJ_INLINE(void) pjsua_normalize_stun_config( pjsua_stun_config *cfg ) { @@ -1022,6 +1509,14 @@ PJ_INLINE(void) pjsua_normalize_stun_config( pjsua_stun_config *cfg ) /** * Duplicate transport config. + * + * @param pool The pool. + * @param dst The destination config. + * @param src The source config. + * + * \par Python: + * Not applicable. One should be able to just copy one variable instance + * to another in Python. */ PJ_INLINE(void) pjsua_transport_config_dup(pj_pool_t *pool, pjsua_transport_config *dst, @@ -1047,6 +1542,9 @@ PJ_INLINE(void) pjsua_transport_config_dup(pj_pool_t *pool, /** * This structure describes transport information returned by * #pjsua_transport_get_info() function. + * + * \par Python: + * The corresponding data type in Python is py_pjsua.Transport_Info. */ typedef struct pjsua_transport_info { @@ -1108,31 +1606,52 @@ typedef struct pjsua_transport_info * @param p_id Optional pointer to receive transport ID. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * The corresponding Python function returns (status,id) tuple: + * \code + status, transport_id = py_pjsua.transport_create(type, cfg) + * \endcode */ PJ_DECL(pj_status_t) pjsua_transport_create(pjsip_transport_type_e type, const pjsua_transport_config *cfg, pjsua_transport_id *p_id); /** - * Register transport that has been created by application. + * Register transport that has been created by application. This function + * is useful if application wants to implement custom SIP transport and use + * it with pjsua. * * @param tp Transport instance. * @param p_id Optional pointer to receive transport ID. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * Not applicable (for now), because one cannot create a custom transport + * from Python script. */ PJ_DECL(pj_status_t) pjsua_transport_register(pjsip_transport *tp, pjsua_transport_id *p_id); /** - * Enumerate all transports currently created in the system. + * Enumerate all transports currently created in the system. This function + * will return all transport IDs, and application may then call + * #pjsua_transport_get_info() function to retrieve detailed information + * about the transport. * * @param id Array to receive transport ids. * @param count In input, specifies the maximum number of elements. * On return, it contains the actual number of elements. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * The function returns list of integers representing transport ids: + * \code + [int] = py_pjsua.enum_transports() + * \endcode */ PJ_DECL(pj_status_t) pjsua_enum_transports( pjsua_transport_id id[], unsigned *count ); @@ -1145,6 +1664,12 @@ PJ_DECL(pj_status_t) pjsua_enum_transports( pjsua_transport_id id[], * @param info Pointer to receive transport info. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * \code + transport_info = py_pjsua.transport_get_info(id) + * \endcode + * The Python function returns None on error. */ PJ_DECL(pj_status_t) pjsua_transport_get_info(pjsua_transport_id id, pjsua_transport_info *info); @@ -1160,6 +1685,11 @@ PJ_DECL(pj_status_t) pjsua_transport_get_info(pjsua_transport_id id, * @param enabled Non-zero to enable, zero to disable. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * \code + status = py_pjsua.transport_set_enable(id, enabled) + * \endcode */ PJ_DECL(pj_status_t) pjsua_transport_set_enable(pjsua_transport_id id, pj_bool_t enabled); @@ -1178,6 +1708,11 @@ PJ_DECL(pj_status_t) pjsua_transport_set_enable(pjsua_transport_id id, * is not recommended! * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * \code + status = py_pjsua.transport_close(id, force) + * \endcode */ PJ_DECL(pj_status_t) pjsua_transport_close( pjsua_transport_id id, pj_bool_t force ); @@ -1195,24 +1730,32 @@ PJ_DECL(pj_status_t) pjsua_transport_close( pjsua_transport_id id, /** - * @defgroup PJSUA_LIB_ACC Account Management + * @defgroup PJSUA_LIB_ACC PJSUA-API Accounts Management * @ingroup PJSUA_LIB - * @brief PJSUA supports multiple accounts.. + * @brief PJSUA Accounts management * @{ + * * PJSUA accounts provide identity (or identities) of the user who is currently - * using the application. More than one account maybe created with PJSUA. + * using the application. In SIP terms, the identity is used as the From + * header in outgoing requests. + * + * PJSUA-API supports creating and managing multiple accounts. The maximum + * number of accounts is limited by a compile time constant + * PJSUA_MAX_ACC. * * Account may or may not have client registration associated with it. * An account is also associated with route set and some authentication * credentials, which are used when sending SIP request messages using the * account. An account also has presence's online status, which - * will be reported to remote peer when the subscribe to the account's - * presence. + * will be reported to remote peer when they subscribe to the account's + * presence, or which is published to a presence server if presence + * publication is enabled for the account. * * At least one account MUST be created in the application. If no user * association is required, application can create a userless account by * calling #pjsua_acc_add_local(). A userless account identifies local endpoint - * instead of a particular user. + * instead of a particular user, and it correspond with a particular + * transport instance. * * Also one account must be set as the default account, which is used as * the account to use when PJSUA fails to match a request with any other @@ -1261,6 +1804,14 @@ PJ_DECL(pj_status_t) pjsua_transport_close( pjsua_transport_id id, * 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(). + * + * \par Python: + * The data type in Python is py_pjsua.Acc_Config, but normally + * application can just use the snippet below to create and initialize + * the account config: + * \code + acc_cfg = py_pjsua.acc_config_default() + * \endcode */ typedef struct pjsua_acc_config { @@ -1303,6 +1854,9 @@ typedef struct pjsua_acc_config /** * Number of proxies in the proxy array below. + * + * \par Python: + * Not applicable, as \a proxy is implemented as list of strings. */ unsigned proxy_cnt; @@ -1318,6 +1872,9 @@ typedef struct pjsua_acc_config * 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. + * + * \par Python: + * This will be list of strings. */ pj_str_t proxy[PJSUA_ACC_MAX_PROXIES]; @@ -1329,6 +1886,9 @@ typedef struct pjsua_acc_config /** * Number of credentials in the credential array. + * + * \par Python: + * Not applicable, since \a cred_info is a list of credentials. */ unsigned cred_count; @@ -1338,6 +1898,9 @@ typedef struct pjsua_acc_config * against the service provider. More credentials can be specified, for * example when the requests are expected to be challenged by the * proxies in the route set. + * + * \par Python: + * This field is a list of credentials. */ pjsip_cred_info cred_info[PJSUA_ACC_MAX_PROXIES]; @@ -1361,6 +1924,13 @@ typedef struct pjsua_acc_config * Call this function to initialize account config with default values. * * @param cfg The account config to be initialized. + * + * \par Python: + * In Python, this function both creates and initializes the account + * config: + * \code + acc_cfg = py_pjsua.acc_config_default() + * \endcode */ PJ_INLINE(void) pjsua_acc_config_default(pjsua_acc_config *cfg) { @@ -1375,6 +1945,9 @@ PJ_INLINE(void) pjsua_acc_config_default(pjsua_acc_config *cfg) /** * Account info. Application can query account info by calling * #pjsua_acc_get_info(). + * + * \par Python: + * The data type in Python is py_pjsua.Acc_Info. */ typedef struct pjsua_acc_info { @@ -1434,6 +2007,11 @@ typedef struct pjsua_acc_info * Get number of current accounts. * * @return Current number of accounts. + * + * \par Python: + * \code + count = py_pjsua.acc_get_count() + * \endcode */ PJ_DECL(unsigned) pjsua_acc_get_count(void); @@ -1444,6 +2022,11 @@ PJ_DECL(unsigned) pjsua_acc_get_count(void); * @param acc_id Account ID to check. * * @return Non-zero if account ID is valid. + * + * \par Python: + * \code + is_valid = py_pjsua.acc_is_valid(acc_id) + * \endcode */ PJ_DECL(pj_bool_t) pjsua_acc_is_valid(pjsua_acc_id acc_id); @@ -1455,6 +2038,11 @@ PJ_DECL(pj_bool_t) pjsua_acc_is_valid(pjsua_acc_id acc_id); * @param acc_id The account ID to be used as default. * * @return PJ_SUCCESS on success. + * + * \par Python: + * \code + status = py_pjsua.acc_set_default(acc_id) + * \endcode */ PJ_DECL(pj_status_t) pjsua_acc_set_default(pjsua_acc_id acc_id); @@ -1466,6 +2054,11 @@ PJ_DECL(pj_status_t) pjsua_acc_set_default(pjsua_acc_id acc_id); * * @return The default account ID, or PJSUA_INVALID_ID if no * default account is configured. + * + * \par Python: + * \code + acc_id = py_pjsua.acc_get_default() + * \endcode */ PJ_DECL(pjsua_acc_id) pjsua_acc_get_default(void); @@ -1479,7 +2072,7 @@ PJ_DECL(pjsua_acc_id) pjsua_acc_get_default(void); * need to do anything to maintain the registration session. * * - * @param cfg Account configuration. + * @param acc_cfg Account configuration. * @param is_default If non-zero, this account will be set as the default * account. The default account will be used when sending * outgoing requests (e.g. making call) when no account is @@ -1489,8 +2082,14 @@ PJ_DECL(pjsua_acc_id) pjsua_acc_get_default(void); * @param p_acc_id Pointer to receive account ID of the new account. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * The function returns (status, account_id) tuple: + * \code + status, account_id = py_pjsua.acc_add(acc_cfg, is_default) + * \endcode */ -PJ_DECL(pj_status_t) pjsua_acc_add(const pjsua_acc_config *cfg, +PJ_DECL(pj_status_t) pjsua_acc_add(const pjsua_acc_config *acc_cfg, pj_bool_t is_default, pjsua_acc_id *p_acc_id); @@ -1510,6 +2109,12 @@ PJ_DECL(pj_status_t) pjsua_acc_add(const pjsua_acc_config *cfg, * @param p_acc_id Pointer to receive account ID of the new account. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * The function returns (status, account_id) tuple: + * \code + status, account_id = py_pjsua.acc_add_local(tid, is_default) + * \endcode */ PJ_DECL(pj_status_t) pjsua_acc_add_local(pjsua_transport_id tid, pj_bool_t is_default, @@ -1523,6 +2128,11 @@ PJ_DECL(pj_status_t) pjsua_acc_add_local(pjsua_transport_id tid, * @param acc_id Id of the account to be deleted. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * \code + status = py_pjsua.acc_del(acc_id) + * \endcode */ PJ_DECL(pj_status_t) pjsua_acc_del(pjsua_acc_id acc_id); @@ -1531,12 +2141,17 @@ PJ_DECL(pj_status_t) pjsua_acc_del(pjsua_acc_id acc_id); * Modify account information. * * @param acc_id Id of the account to be modified. - * @param cfg New account configuration. + * @param acc_cfg New account configuration. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * \code + status = py_pjsua.acc_modify(acc_id, acc_cfg) + * \endcode */ PJ_DECL(pj_status_t) pjsua_acc_modify(pjsua_acc_id acc_id, - const pjsua_acc_config *cfg); + const pjsua_acc_config *acc_cfg); /** @@ -1548,6 +2163,11 @@ PJ_DECL(pj_status_t) pjsua_acc_modify(pjsua_acc_id acc_id, * @param is_online True of false. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * \code + status = py_pjsua.acc_set_online_status(acc_id, is_online) + * \endcode */ PJ_DECL(pj_status_t) pjsua_acc_set_online_status(pjsua_acc_id acc_id, pj_bool_t is_online); @@ -1565,6 +2185,11 @@ PJ_DECL(pj_status_t) pjsua_acc_set_online_status(pjsua_acc_id acc_id, * unregistration process. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * \code + status = py_pjsua.acc_set_registration(acc_id, renew) + * \endcode */ PJ_DECL(pj_status_t) pjsua_acc_set_registration(pjsua_acc_id acc_id, pj_bool_t renew); @@ -1577,6 +2202,12 @@ PJ_DECL(pj_status_t) pjsua_acc_set_registration(pjsua_acc_id acc_id, * @param info Pointer to receive account information. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * \code + acc_info = py_pjsua.acc_get_info(acc_id) + * \endcode + * The function returns None if account ID is not valid. */ PJ_DECL(pj_status_t) pjsua_acc_get_info(pjsua_acc_id acc_id, pjsua_acc_info *info); @@ -1594,6 +2225,12 @@ PJ_DECL(pj_status_t) pjsua_acc_get_info(pjsua_acc_id acc_id, * On return, it contains the actual number of elements. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * The function takes no argument and returns list of account Ids: + * \code + [acc_ids] = py_pjsua.enum_accs() + * \endcode */ PJ_DECL(pj_status_t) pjsua_enum_accs(pjsua_acc_id ids[], unsigned *count ); @@ -1607,6 +2244,12 @@ PJ_DECL(pj_status_t) pjsua_enum_accs(pjsua_acc_id ids[], * On return, it contains the actual number of elements. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * The function takes no argument and returns list of account infos: + * \code + [acc_info] = py_pjsua.acc_enum_info() + * \endcode */ PJ_DECL(pj_status_t) pjsua_acc_enum_info( pjsua_acc_info info[], unsigned *count ); @@ -1619,6 +2262,11 @@ PJ_DECL(pj_status_t) pjsua_acc_enum_info( pjsua_acc_info info[], * @param url The remote URL to reach. * * @return Account id. + * + * \par Python: + * \code + acc_id = py_pjsua.acc_find_for_outgoing(url) + * \endcode */ PJ_DECL(pjsua_acc_id) pjsua_acc_find_for_outgoing(const pj_str_t *url); @@ -1630,6 +2278,11 @@ PJ_DECL(pjsua_acc_id) pjsua_acc_find_for_outgoing(const pj_str_t *url); * @param rdata The incoming request message. * * @return Account id. + * + * \par Python: + * \code + acc_id = py_pjsua.acc_find_for_outgoing(url) + * \endcode */ PJ_DECL(pjsua_acc_id) pjsua_acc_find_for_incoming(pjsip_rx_data *rdata); @@ -1644,6 +2297,12 @@ PJ_DECL(pjsua_acc_id) pjsua_acc_find_for_incoming(pjsip_rx_data *rdata); * @param uri Destination URI of the request. * * @return PJ_SUCCESS on success, other on error. + * + * \par Python: + * This function is still experimental in Python: + * \code + uri = py_pjsua.acc_create_uac_contact(pool, acc_id, uri) + * \endcode */ PJ_DECL(pj_status_t) pjsua_acc_create_uac_contact( pj_pool_t *pool, pj_str_t *contact, @@ -1662,6 +2321,12 @@ PJ_DECL(pj_status_t) pjsua_acc_create_uac_contact( pj_pool_t *pool, * @param rdata Incoming request. * * @return PJ_SUCCESS on success, other on error. + * + * \par Python: + * This function is still experimental in Python: + * \code + uri = py_pjsua.acc_create_uas_contact(pool, acc_id, rdata) + * \endcode */ PJ_DECL(pj_status_t) pjsua_acc_create_uas_contact( pj_pool_t *pool, pj_str_t *contact, @@ -1685,6 +2350,9 @@ PJ_DECL(pj_status_t) pjsua_acc_create_uas_contact( pj_pool_t *pool, * @param tp_id The transport ID. * * @return PJ_SUCCESS on success. + * + * \par Python: + * Not yet implemented. */ PJ_DECL(pj_status_t) pjsua_acc_set_transport(pjsua_acc_id acc_id, pjsua_transport_id tp_id); @@ -1701,7 +2369,7 @@ PJ_DECL(pj_status_t) pjsua_acc_set_transport(pjsua_acc_id acc_id, /** - * @defgroup PJSUA_LIB_CALL Calls + * @defgroup PJSUA_LIB_CALL PJSUA-API Calls Management * @ingroup PJSUA_LIB * @brief Call manipulation. * @{ @@ -1739,6 +2407,9 @@ typedef enum pjsua_call_media_status /** * This structure describes the information and current status of a call. + * + * \par Python: + * The type name is py_pjsua.Call_Info. */ typedef struct pjsua_call_info { @@ -1813,6 +2484,11 @@ typedef struct pjsua_call_info * Get maximum number of calls configured in pjsua. * * @return Maximum number of calls configured. + * + * \par Python: + * \code + count = py_pjsua.call_get_max_count() + * \endcode */ PJ_DECL(unsigned) pjsua_call_get_max_count(void); @@ -1820,6 +2496,11 @@ PJ_DECL(unsigned) pjsua_call_get_max_count(void); * Get number of currently active calls. * * @return Number of currently active calls. + * + * \par Python: + * \code + count = py_pjsua.call_get_count() + * \endcode */ PJ_DECL(unsigned) pjsua_call_get_count(void); @@ -1832,6 +2513,12 @@ PJ_DECL(unsigned) pjsua_call_get_count(void); * On return, it contains the actual number of elements. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * This function takes no argument and return list of call Ids. + * \code + [call_ids] = py_pjsua.enum_calls() + * \endcode */ PJ_DECL(pj_status_t) pjsua_enum_calls(pjsua_call_id ids[], unsigned *count); @@ -1851,6 +2538,15 @@ PJ_DECL(pj_status_t) pjsua_enum_calls(pjsua_call_id ids[], * @param p_call_id Pointer to receive call identification. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * The Python function returns (status, call_id) tuple: + * \code + status, call_id = py_pjsua.call_make_call(acc_id, dst_uri, options, + user_data, msg_data) + * \endcode + * Note: the \a user_data in Python function is an integer, and the + * \a msg_data can be set to None if not required. */ PJ_DECL(pj_status_t) pjsua_call_make_call(pjsua_acc_id acc_id, const pj_str_t *dst_uri, @@ -1867,6 +2563,11 @@ PJ_DECL(pj_status_t) pjsua_call_make_call(pjsua_acc_id acc_id, * @param call_id Call identification. * * @return Non-zero if call is active. + * + * \par Python: + * \code + bool = py_pjsua.call_is_active(call_id) + * \endcode */ PJ_DECL(pj_bool_t) pjsua_call_is_active(pjsua_call_id call_id); @@ -1877,6 +2578,11 @@ PJ_DECL(pj_bool_t) pjsua_call_is_active(pjsua_call_id call_id); * @param call_id Call identification. * * @return Non-zero if yes. + * + * \par Python: + * \code + bool = py_pjsua.call_has_media(call_id) + * \endcode */ PJ_DECL(pj_bool_t) pjsua_call_has_media(pjsua_call_id call_id); @@ -1888,6 +2594,11 @@ PJ_DECL(pj_bool_t) pjsua_call_has_media(pjsua_call_id call_id); * * @return Conference port ID, or PJSUA_INVALID_ID when the * media has not been established or is not active. + * + * \par Python: + * \code + slot = py_pjsua.call_get_conf_port(call_id) + * \endcode */ PJ_DECL(pjsua_conf_port_id) pjsua_call_get_conf_port(pjsua_call_id call_id); @@ -1898,6 +2609,12 @@ PJ_DECL(pjsua_conf_port_id) pjsua_call_get_conf_port(pjsua_call_id call_id); * @param info Call info to be initialized. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * \code + call_info = py_pjsua.call_get_info(call_id) + * \endcode + * \a call_info return value will be set to None if call_id is not valid. */ PJ_DECL(pj_status_t) pjsua_call_get_info(pjsua_call_id call_id, pjsua_call_info *info); @@ -1911,6 +2628,12 @@ PJ_DECL(pj_status_t) pjsua_call_get_info(pjsua_call_id call_id, * @param user_data Arbitrary data to be attached to the call. * * @return The user data. + * + * \par Python: + * \code + status = py_pjsua.call_set_user_data(call_id, user_data) + * \endcode + * The \a user_data is an integer in the Python function. */ PJ_DECL(pj_status_t) pjsua_call_set_user_data(pjsua_call_id call_id, void *user_data); @@ -1923,6 +2646,12 @@ PJ_DECL(pj_status_t) pjsua_call_set_user_data(pjsua_call_id call_id, * @param call_id Call identification. * * @return The user data. + * + * \par Python: + * \code + user_data = py_pjsua.call_get_user_data(call_id) + * \endcode + * The \a user_data is an integer. */ PJ_DECL(void*) pjsua_call_get_user_data(pjsua_call_id call_id); @@ -1940,6 +2669,12 @@ PJ_DECL(void*) pjsua_call_get_user_data(pjsua_call_id call_id); * response message. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * \code + status = py_pjsua.call_answer(call_id, code, reason, msg_data) + * \endcode + * Arguments \a reason and \a msg_data may be set to None if not required. */ PJ_DECL(pj_status_t) pjsua_call_answer(pjsua_call_id call_id, unsigned code, @@ -1964,6 +2699,12 @@ PJ_DECL(pj_status_t) pjsua_call_answer(pjsua_call_id call_id, * request/response message. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * \code + status = py_pjsua.call_hangup(call_id, code, reason, msg_data) + * \endcode + * Arguments \a reason and \a msg_data may be set to None if not required. */ PJ_DECL(pj_status_t) pjsua_call_hangup(pjsua_call_id call_id, unsigned code, @@ -1983,6 +2724,12 @@ PJ_DECL(pj_status_t) pjsua_call_hangup(pjsua_call_id call_id, * the request. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * \code + status = py_pjsua.call_set_hold(call_id, msg_data) + * \endcode + * Argument \a msg_data may be set to None if not required. */ PJ_DECL(pj_status_t) pjsua_call_set_hold(pjsua_call_id call_id, const pjsua_msg_data *msg_data); @@ -2001,6 +2748,12 @@ PJ_DECL(pj_status_t) pjsua_call_set_hold(pjsua_call_id call_id, * the request. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * \code + status = py_pjsua.call_reinvite(call_id, unhold, msg_data) + * \endcode + * Argument \a msg_data may be set to None if not required. */ PJ_DECL(pj_status_t) pjsua_call_reinvite(pjsua_call_id call_id, pj_bool_t unhold, @@ -2023,6 +2776,12 @@ PJ_DECL(pj_status_t) pjsua_call_reinvite(pjsua_call_id call_id, * the request. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * \code + status = py_pjsua.call_xfer(call_id, dest, msg_data) + * \endcode + * Argument \a msg_data may be set to None if not required. */ PJ_DECL(pj_status_t) pjsua_call_xfer(pjsua_call_id call_id, const pj_str_t *dest, @@ -2051,6 +2810,12 @@ PJ_DECL(pj_status_t) pjsua_call_xfer(pjsua_call_id call_id, * the request. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * \code + status = py_pjsua.call_xfer_replaces(call_id, dest_call_id, options, msg_data) + * \endcode + * Argument \a msg_data may be set to None if not required. */ PJ_DECL(pj_status_t) pjsua_call_xfer_replaces(pjsua_call_id call_id, pjsua_call_id dest_call_id, @@ -2061,9 +2826,14 @@ PJ_DECL(pj_status_t) pjsua_call_xfer_replaces(pjsua_call_id call_id, * Send DTMF digits to remote using RFC 2833 payload formats. * * @param call_id Call identification. - * @param digits DTMF digits to be sent. + * @param digits DTMF string digits to be sent. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * \code + status = py_pjsua.call_dial_dtmf(call_id, digits) + * \endcode */ PJ_DECL(pj_status_t) pjsua_call_dial_dtmf(pjsua_call_id call_id, const pj_str_t *digits); @@ -2082,6 +2852,12 @@ PJ_DECL(pj_status_t) pjsua_call_dial_dtmf(pjsua_call_id call_id, * the IM callback is called. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * \code + status = py_pjsua.call_send_im(call_id, mime_type, content, msg_data, user_data) + * \endcode + * Note that the \a user_data argument is an integer in Python. */ PJ_DECL(pj_status_t) pjsua_call_send_im( pjsua_call_id call_id, const pj_str_t *mime_type, @@ -2100,6 +2876,12 @@ PJ_DECL(pj_status_t) pjsua_call_send_im( pjsua_call_id call_id, * request. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * \code + status = py_pjsua.call_send_typing_ind(call_id, is_typing, msg_data) + * \endcode + * Argument \a msg_data may be set to None if not required. */ PJ_DECL(pj_status_t) pjsua_call_send_typing_ind(pjsua_call_id call_id, pj_bool_t is_typing, @@ -2108,6 +2890,11 @@ PJ_DECL(pj_status_t) pjsua_call_send_typing_ind(pjsua_call_id call_id, /** * Terminate all calls. This will initiate #pjsua_call_hangup() for all * currently active calls. + * + * \par Python: + * \code + py_pjsua.call_hangup_all() + * \endcode */ PJ_DECL(void) pjsua_call_hangup_all(void); @@ -2122,6 +2909,12 @@ PJ_DECL(void) pjsua_call_hangup_all(void); * @param indent Spaces for left indentation. * * @return PJ_SUCCESS on success. + * + * \par Python: + * \code + string = py_pjsua.call_dump(call_id, with_media, max_len, indent) + * \endcode + * The \a max_len argument is the desired maximum length to be allocated. */ PJ_DECL(pj_status_t) pjsua_call_dump(pjsua_call_id call_id, pj_bool_t with_media, @@ -2140,10 +2933,13 @@ PJ_DECL(pj_status_t) pjsua_call_dump(pjsua_call_id call_id, /** - * @defgroup PJSUA_LIB_BUDDY Buddy, Presence, and Instant Messaging + * @defgroup PJSUA_LIB_BUDDY PJSUA-API Buddy, Presence, and Instant Messaging * @ingroup PJSUA_LIB * @brief Buddy management, buddy's presence, and instant messaging. * @{ + * + * This section describes PJSUA-APIs related to buddies management, + * presence management, and instant messaging. */ /** @@ -2159,6 +2955,14 @@ PJ_DECL(pj_status_t) pjsua_call_dump(pjsua_call_id call_id, * the buddy list with #pjsua_buddy_add(). Application MUST initialize * the structure with #pjsua_buddy_config_default() to initialize this * structure with default configuration. + * + * \par Python: + * In Python this structure is py_pjsua.Buddy_Config. However + * it is recommended that application instantiates the buddy config + * by calling: + * \code + buddy_cfg = py_pjsua.buddy_config_default() + * \endcode */ typedef struct pjsua_buddy_config { @@ -2203,6 +3007,9 @@ typedef enum pjsua_buddy_status /** * This structure describes buddy info, which can be retrieved by calling * #pjsua_buddy_get_info(). + * + * \par Python: + * This structure in Python is py_pjsua.Buddy_Info. */ typedef struct pjsua_buddy_info { @@ -2248,6 +3055,11 @@ typedef struct pjsua_buddy_info /** * Set default values to the buddy config. + * + * \par Python: + * \code + buddy_cfg = py_pjsua.buddy_config_default() + * \endcode */ PJ_INLINE(void) pjsua_buddy_config_default(pjsua_buddy_config *cfg) { @@ -2259,6 +3071,11 @@ PJ_INLINE(void) pjsua_buddy_config_default(pjsua_buddy_config *cfg) * Get total number of buddies. * * @return Number of buddies. + * + * \par Python: + * \code + buddy_count = py_pjsua.get_buddy_count() + * \endcode */ PJ_DECL(unsigned) pjsua_get_buddy_count(void); @@ -2269,6 +3086,11 @@ PJ_DECL(unsigned) pjsua_get_buddy_count(void); * @param buddy_id Buddy ID to check. * * @return Non-zero if buddy ID is valid. + * + * \par Python: + * \code + is_valid = py_pjsua.buddy_is_valid(buddy_id) + * \endcode */ PJ_DECL(pj_bool_t) pjsua_buddy_is_valid(pjsua_buddy_id buddy_id); @@ -2284,6 +3106,12 @@ PJ_DECL(pj_bool_t) pjsua_buddy_is_valid(pjsua_buddy_id buddy_id); * that have been initialized. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * The Python function takes no argument and returns list of buddy IDs: + * \code + [buddy_ids] = py_pjsua.enum_buddies() + * \endcode */ PJ_DECL(pj_status_t) pjsua_enum_buddies(pjsua_buddy_id ids[], unsigned *count); @@ -2295,6 +3123,12 @@ PJ_DECL(pj_status_t) pjsua_enum_buddies(pjsua_buddy_id ids[], * @param info Pointer to receive information about buddy. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * \code + buddy_info = py_pjsua.buddy_get_info(buddy_id) + * \endcode + * The function returns None if buddy_id is not valid. */ PJ_DECL(pj_status_t) pjsua_buddy_get_info(pjsua_buddy_id buddy_id, pjsua_buddy_info *info); @@ -2304,12 +3138,18 @@ PJ_DECL(pj_status_t) pjsua_buddy_get_info(pjsua_buddy_id buddy_id, * for this buddy, this function will also start the presence subscription * session immediately. * - * @param cfg Buddy configuration. + * @param buddy)cfg Buddy configuration. * @param p_buddy_id Pointer to receive buddy ID. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * The function returns (status, buddy_id) tuple: + * \code + status, buddy_id = py_pjsua.buddy_add(buddy_cfg) + * \endcode */ -PJ_DECL(pj_status_t) pjsua_buddy_add(const pjsua_buddy_config *cfg, +PJ_DECL(pj_status_t) pjsua_buddy_add(const pjsua_buddy_config *buddy_cfg, pjsua_buddy_id *p_buddy_id); @@ -2320,6 +3160,11 @@ PJ_DECL(pj_status_t) pjsua_buddy_add(const pjsua_buddy_config *cfg, * @param buddy_id Buddy identification. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * \code + status = py_pjsua.buddy_del(buddy_id) + * \endcode */ PJ_DECL(pj_status_t) pjsua_buddy_del(pjsua_buddy_id buddy_id); @@ -2334,6 +3179,11 @@ PJ_DECL(pj_status_t) pjsua_buddy_del(pjsua_buddy_id buddy_id); * the specified buddy. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * \code + status = py_pjsua.buddy_subscribe_pres(buddy_id, subscribe) + * \endcode */ PJ_DECL(pj_status_t) pjsua_buddy_subscribe_pres(pjsua_buddy_id buddy_id, pj_bool_t subscribe); @@ -2343,6 +3193,11 @@ PJ_DECL(pj_status_t) pjsua_buddy_subscribe_pres(pjsua_buddy_id buddy_id, * Dump presence subscriptions to log. * * @param verbose Yes or no. + * + * \par Python: + * \code + py_pjsua.pres_dump() + * \endcode */ PJ_DECL(void) pjsua_pres_dump(pj_bool_t verbose); @@ -2370,6 +3225,12 @@ extern const pjsip_method pjsip_message_method; * the IM callback is called. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * \code + status = py_pjsua.im_send(acc_id, to, mime_type, content, msg_data, user_data) + * \endcode + * Arguments \a mime_type and \a msg_data may be set to None if not required. */ PJ_DECL(pj_status_t) pjsua_im_send(pjsua_acc_id acc_id, const pj_str_t *to, @@ -2390,6 +3251,12 @@ PJ_DECL(pj_status_t) pjsua_im_send(pjsua_acc_id acc_id, * request. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * \code + status = py_pjsua.im_typing(acc_id, to, is_typing, msg_data) + * \endcode + * Argument \a msg_data may be set to None if not requried. */ PJ_DECL(pj_status_t) pjsua_im_typing(pjsua_acc_id acc_id, const pj_str_t *to, @@ -2409,23 +3276,32 @@ PJ_DECL(pj_status_t) pjsua_im_typing(pjsua_acc_id acc_id, /** - * @defgroup PJSUA_LIB_MEDIA Media + * @defgroup PJSUA_LIB_MEDIA PJSUA-API Media Manipulation * @ingroup PJSUA_LIB * @brief Media manipulation. * @{ * * PJSUA has rather powerful media features, which are built around the - * PJMEDIA conference bridge. Basically, all media termination (such as - * calls, file players, file recorders, sound device, tone generators, etc) + * PJMEDIA conference bridge. Basically, all media "ports" (such as calls, WAV + * players, WAV playlist, file recorders, sound device, tone generators, etc) * are terminated in the conference bridge, and application can manipulate - * the interconnection between these terminations freely. If more than - * one media terminations are terminated in the same slot, the conference - * bridge will mix the signal automatically. + * the interconnection between these terminations freely. + * + * The conference bridge provides powerful switching and mixing functionality + * for application. With the conference bridge, each conference slot (e.g. + * a call) can transmit to multiple destinations, and one destination can + * receive from multiple sources. If more than one media terminations are + * terminated in the same slot, the conference bridge will mix the signal + * automatically. * * Application connects one media termination/slot to another by calling * #pjsua_conf_connect() function. This will establish unidirectional - * media flow from the source termination to the sink termination. For - * example, to stream a WAV file to remote call, application may use + * media flow from the source termination to the sink termination. To + * establish bidirectional media flow, application wound need to make another + * call to #pjsua_conf_connect(), this time inverting the source and + * destination slots in the parameter. + * + * For example, to stream a WAV file to remote call, application may use * the following steps: * \code @@ -2501,6 +3377,14 @@ PJ_DECL(pj_status_t) pjsua_im_typing(pjsua_acc_id acc_id, * This structure describes media configuration, which will be specified * when calling #pjsua_init(). Application MUST initialize this structure * by calling #pjsua_media_config_default(). + * + * \par Python: + * This data type in Python is py_pjsua.Media_Config. To create + * an object of this type, it is recommended to call + * py_pjsua.media_config_default() function instead: + * \code + media_cfg = py_pjsua.media_config_default() + * \endcode */ struct pjsua_media_config { @@ -2637,6 +3521,11 @@ struct pjsua_media_config * Use this function to initialize media config. * * @param cfg The media config to be initialized. + * + * \par Python: + * \code + media_cfg = py_pjsua.media_config_default() + * \endcode */ PJ_INLINE(void) pjsua_media_config_default(pjsua_media_config *cfg) { @@ -2682,6 +3571,9 @@ typedef struct pjsua_codec_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(). + * + * \par Python: + * In Python, this type is py_pjsua.Conf_Port_Info. */ typedef struct pjsua_conf_port_info { @@ -2717,6 +3609,9 @@ typedef struct pjsua_conf_port_info /** * This structure holds information about custom media transport to * be registered to pjsua. + * + * \par Python: + * Not applicable. */ typedef struct pjsua_media_transport { @@ -2740,6 +3635,11 @@ typedef struct pjsua_media_transport * Get maxinum number of conference ports. * * @return Maximum number of ports in the conference bridge. + * + * \par Python: + * \code + port_count = py_pjsua.conf_get_max_ports() + * \endcode */ PJ_DECL(unsigned) pjsua_conf_get_max_ports(void); @@ -2748,6 +3648,11 @@ PJ_DECL(unsigned) pjsua_conf_get_max_ports(void); * Get current number of active ports in the bridge. * * @return The number. + * + * \par Python: + * \code + count = py_pjsua.conf_get_active_ports() + * \endcode */ PJ_DECL(unsigned) pjsua_conf_get_active_ports(void); @@ -2761,6 +3666,12 @@ PJ_DECL(unsigned) pjsua_conf_get_active_ports(void); * that have been initialized. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * The Python functions returns list of conference port Ids: + * \code + [port_ids] = py_pjsua.enum_conf_ports() + * \endcode */ PJ_DECL(pj_status_t) pjsua_enum_conf_ports(pjsua_conf_port_id id[], unsigned *count); @@ -2769,12 +3680,18 @@ PJ_DECL(pj_status_t) pjsua_enum_conf_ports(pjsua_conf_port_id id[], /** * Get information about the specified conference port * - * @param id Port identification. + * @param port_id Port identification. * @param info Pointer to store the port info. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * \code + port_info = py_pjsua.conf_get_port_info(port_id) + * \endcode + * The function will return None if \a port_id is not valid. */ -PJ_DECL(pj_status_t) pjsua_conf_get_port_info( pjsua_conf_port_id id, +PJ_DECL(pj_status_t) pjsua_conf_get_port_info( pjsua_conf_port_id port_id, pjsua_conf_port_info *info); @@ -2791,6 +3708,9 @@ PJ_DECL(pj_status_t) pjsua_conf_get_port_info( pjsua_conf_port_id id, * slot id. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * Not applicable (for now) */ PJ_DECL(pj_status_t) pjsua_conf_add_port(pj_pool_t *pool, pjmedia_port *port, @@ -2802,11 +3722,16 @@ PJ_DECL(pj_status_t) pjsua_conf_add_port(pj_pool_t *pool, * 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. + * @param port_id The slot id of the port to be removed. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * \code + status = py_pjsua.conf_remove_port(port_id) + * \endcode */ -PJ_DECL(pj_status_t) pjsua_conf_remove_port(pjsua_conf_port_id id); +PJ_DECL(pj_status_t) pjsua_conf_remove_port(pjsua_conf_port_id port_id); /** @@ -2824,6 +3749,11 @@ PJ_DECL(pj_status_t) pjsua_conf_remove_port(pjsua_conf_port_id id); * @param sink Port ID of the destination media/received. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * \code + status = py_pjsua.conf_connect(source, sink) + * \endcode */ PJ_DECL(pj_status_t) pjsua_conf_connect(pjsua_conf_port_id source, pjsua_conf_port_id sink); @@ -2836,6 +3766,11 @@ PJ_DECL(pj_status_t) pjsua_conf_connect(pjsua_conf_port_id source, * @param sink Port ID of the destination media/received. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * \code + status = py_pjsua.conf_disconnect(source, sink) + * \endcode */ PJ_DECL(pj_status_t) pjsua_conf_disconnect(pjsua_conf_port_id source, pjsua_conf_port_id sink); @@ -2850,6 +3785,9 @@ PJ_DECL(pj_status_t) pjsua_conf_disconnect(pjsua_conf_port_id source, * adjustment, while value 0 means to mute the port. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * Not implemented (yet) */ PJ_DECL(pj_status_t) pjsua_conf_adjust_tx_level(pjsua_conf_port_id slot, float level); @@ -2863,6 +3801,9 @@ PJ_DECL(pj_status_t) pjsua_conf_adjust_tx_level(pjsua_conf_port_id slot, * adjustment, while value 0 means to mute the port. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * Not implemented (yet) */ PJ_DECL(pj_status_t) pjsua_conf_adjust_rx_level(pjsua_conf_port_id slot, float level); @@ -2881,16 +3822,14 @@ PJ_DECL(pj_status_t) pjsua_conf_adjust_rx_level(pjsua_conf_port_id slot, * port to the bridge). * * @return PJ_SUCCESS on success. + * + * \par Python: + * Not implemented (yet) */ PJ_DECL(pj_status_t) pjsua_conf_get_signal_level(pjsua_conf_port_id slot, unsigned *tx_level, unsigned *rx_level); -/** - * - */ - - /***************************************************************************** * File player and playlist. @@ -2908,6 +3847,12 @@ PJ_DECL(pj_status_t) pjsua_conf_get_signal_level(pjsua_conf_port_id slot, * @param p_id Pointer to receive player ID. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * The function returns (status, id) tuple: + * \code + status, id = py_pjsua.player_create(filename, options) + * \endcode */ PJ_DECL(pj_status_t) pjsua_player_create(const pj_str_t *filename, unsigned options, @@ -2928,6 +3873,9 @@ PJ_DECL(pj_status_t) pjsua_player_create(const pj_str_t *filename, * @param p_id Optional pointer to receive player ID. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * Not implemented yet. */ PJ_DECL(pj_status_t) pjsua_playlist_create(const pj_str_t file_names[], unsigned file_count, @@ -2941,6 +3889,11 @@ PJ_DECL(pj_status_t) pjsua_playlist_create(const pj_str_t file_names[], * @param id The file player ID. * * @return Conference port ID associated with this player. + * + * \par Python: + * \code + port_id = py_pjsua.player_get_conf_port(id) + * \endcode */ PJ_DECL(pjsua_conf_port_id) pjsua_player_get_conf_port(pjsua_player_id id); @@ -2952,6 +3905,9 @@ PJ_DECL(pjsua_conf_port_id) pjsua_player_get_conf_port(pjsua_player_id id); * @param p_port The media port associated with the player. * * @return PJ_SUCCESS on success. + * + * \par Python: + * Not applicable. */ PJ_DECL(pj_status_t) pjsua_player_get_port(pjsua_recorder_id id, pjmedia_port **p_port); @@ -2964,6 +3920,11 @@ PJ_DECL(pj_status_t) pjsua_player_get_port(pjsua_recorder_id id, * specify zero to re-start the playback. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * \code + status = py_pjsua.player_set_pos(id, samples) + * \endcode */ PJ_DECL(pj_status_t) pjsua_player_set_pos(pjsua_player_id id, pj_uint32_t samples); @@ -2976,6 +3937,11 @@ PJ_DECL(pj_status_t) pjsua_player_set_pos(pjsua_player_id id, * @param id The file player ID. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * \code + status = py_pjsua.player_destroy(id) + * \endcode */ PJ_DECL(pj_status_t) pjsua_player_destroy(pjsua_player_id id); @@ -3008,6 +3974,12 @@ PJ_DECL(pj_status_t) pjsua_player_destroy(pjsua_player_id id); * @param p_id Pointer to receive the recorder instance. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * \code + status, id = py_pjsua.recorder_create(filename, enc_type, enc_param, max_size, options) + * \endcode + * The \a enc_param is a string in Python. */ PJ_DECL(pj_status_t) pjsua_recorder_create(const pj_str_t *filename, unsigned enc_type, @@ -3023,6 +3995,11 @@ PJ_DECL(pj_status_t) pjsua_recorder_create(const pj_str_t *filename, * @param id The recorder ID. * * @return Conference port ID associated with this recorder. + * + * \par Python: + * \code + port_id = py_pjsua.recorder_get_conf_port(id) + * \endcode */ PJ_DECL(pjsua_conf_port_id) pjsua_recorder_get_conf_port(pjsua_recorder_id id); @@ -3034,6 +4011,9 @@ PJ_DECL(pjsua_conf_port_id) pjsua_recorder_get_conf_port(pjsua_recorder_id id); * @param p_port The media port associated with the recorder. * * @return PJ_SUCCESS on success. + * + * \par Python: + * Not applicable. */ PJ_DECL(pj_status_t) pjsua_recorder_get_port(pjsua_recorder_id id, pjmedia_port **p_port); @@ -3045,6 +4025,11 @@ PJ_DECL(pj_status_t) pjsua_recorder_get_port(pjsua_recorder_id id, * @param id The recorder ID. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * \code + status = py_pjsua.recorder_destroy(id) + * \endcode */ PJ_DECL(pj_status_t) pjsua_recorder_destroy(pjsua_recorder_id id); @@ -3062,6 +4047,14 @@ PJ_DECL(pj_status_t) pjsua_recorder_destroy(pjsua_recorder_id id); * that have been initialized. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * + * \par Python: + * The function returns list of sound device info: + * \code + [dev_infos] = py_pjsua.enum_snd_devs() + * \endcode + * */ PJ_DECL(pj_status_t) pjsua_enum_snd_devs(pjmedia_snd_dev_info info[], unsigned *count); @@ -3079,6 +4072,12 @@ PJ_DECL(pj_status_t) pjsua_enum_snd_devs(pjmedia_snd_dev_info info[], * device ID of the playback device. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * The function takes no argument and return a tuple: + * \code + capture_dev, playback_dev = py_pjsua.get_snd_dev() + * \endcode */ PJ_DECL(pj_status_t) pjsua_get_snd_dev(int *capture_dev, int *playback_dev); @@ -3092,6 +4091,11 @@ PJ_DECL(pj_status_t) pjsua_get_snd_dev(int *capture_dev, * @param playback_dev Device ID of the playback device. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * \code + status = py_pjsua.set_snd_dev(capture_dev, playback_dev) + * \endcode */ PJ_DECL(pj_status_t) pjsua_set_snd_dev(int capture_dev, int playback_dev); @@ -3103,6 +4107,11 @@ PJ_DECL(pj_status_t) pjsua_set_snd_dev(int capture_dev, * any hardware. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * \code + status = py_pjsua.set_null_snd_dev() + * \endcode */ PJ_DECL(pj_status_t) pjsua_set_null_snd_dev(void); @@ -3114,6 +4123,9 @@ PJ_DECL(pj_status_t) pjsua_set_null_snd_dev(void); * @return The port interface of the conference bridge, * so that application can connect this to it's own * sound device or master port. + * + * \par Python: + * Not applicable (for now). */ PJ_DECL(pjmedia_port*) pjsua_set_no_snd_dev(void); @@ -3127,6 +4139,11 @@ PJ_DECL(pjmedia_port*) pjsua_set_no_snd_dev(void); * Normally the value should be zero. * * @return PJ_SUCCESS on success. + * + * \par Python: + * \code + status = py_pjsua.set_ec(tail_ms, options) + * \endcode */ PJ_DECL(pj_status_t) pjsua_set_ec(unsigned tail_ms, unsigned options); @@ -3138,6 +4155,11 @@ PJ_DECL(pj_status_t) pjsua_set_ec(unsigned tail_ms, unsigned options); * If AEC is disabled, the value will be zero. * * @return PJ_SUCCESS on success. + * + * \par Python: + * \code + tail_ms = py_pjsua.get_ec_tail() + * \endcode */ PJ_DECL(pj_status_t) pjsua_get_ec_tail(unsigned *p_tail_ms); @@ -3156,6 +4178,12 @@ PJ_DECL(pj_status_t) pjsua_get_ec_tail(unsigned *p_tail_ms); * that have been initialized. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * This function takes no argument and returns list of codec infos: + * \code + [codec_info] = py_pjsua.enum_codecs() + * \endcode */ PJ_DECL(pj_status_t) pjsua_enum_codecs( pjsua_codec_info id[], unsigned *count ); @@ -3164,37 +4192,57 @@ PJ_DECL(pj_status_t) pjsua_enum_codecs( pjsua_codec_info id[], /** * Change codec priority. * - * @param id Codec ID. + * @param codec_id Codec ID, which is a string that uniquely identify + * the codec (such as "speex/8000"). Please see pjsua + * manual or pjmedia codec reference for details. * @param priority Codec priority, 0-255, where zero means to disable * the codec. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * \code + status = py_pjsua.codec_set_priority(codec_id, priority) + * \endcode */ -PJ_DECL(pj_status_t) pjsua_codec_set_priority( const pj_str_t *id, +PJ_DECL(pj_status_t) pjsua_codec_set_priority( const pj_str_t *codec_id, pj_uint8_t priority ); /** * Get codec parameters. * - * @param id Codec ID. + * @param codec_id Codec ID. * @param param Structure to receive codec parameters. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * The Python function is experimental: + * \code + codec_param = py_pjsua.codec_get_param(codec_id) + * \endcode */ -PJ_DECL(pj_status_t) pjsua_codec_get_param( const pj_str_t *id, +PJ_DECL(pj_status_t) pjsua_codec_get_param( const pj_str_t *codec_id, pjmedia_codec_param *param ); /** * Set codec parameters. * - * @param id Codec ID. + * @param codec_id Codec ID. * @param param Codec parameter to set. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * The Python function is experimental: + * \code + status = py_pjsua.codec_set_param(codec_id, param) + * \endcode + */ -PJ_DECL(pj_status_t) pjsua_codec_set_param( const pj_str_t *id, +PJ_DECL(pj_status_t) pjsua_codec_set_param( const pj_str_t *codec_id, const pjmedia_codec_param *param); @@ -3209,6 +4257,9 @@ PJ_DECL(pj_status_t) pjsua_codec_set_param( const pj_str_t *id, * sockets. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * Not implemented yet. */ PJ_DECL(pj_status_t) pjsua_media_transports_create(const pjsua_transport_config *cfg); @@ -3226,6 +4277,9 @@ pjsua_media_transports_create(const pjsua_transport_config *cfg); * destroyed when pjsua is shutdown. * * @return PJ_SUCCESS on success, or the appropriate error code. + * + * \par Python: + * Note applicable. */ PJ_DECL(pj_status_t) pjsua_media_transports_attach( pjsua_media_transport tp[], @@ -3239,12 +4293,11 @@ pjsua_media_transports_attach( pjsua_media_transport tp[], -PJ_END_DECL - - /** * @} */ +PJ_END_DECL + #endif /* __PJSUA_H__ */ -- cgit v1.2.3