|
HOME
SIP/media Features
High Performance SIP
Small Footprint SIP
Symbian Port
FAQ
Documentation
Licensing
Download
Development (Trac)
Projects using pjsip
Mailing List
Open Source Links
About: PJLIB, PJLIB-UTIL, PJSIP, and PJMEDIA are created by: Benny Prijono <bennylp pjsip.org>
|
|
Home --> Documentations --> PJSIP Reference
Detailed Description
The base PJSUA API controls PJSUA creation, initialization, and startup, and also provides various auxiliary functions.
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, 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.
After PJSUA is created, application can initialize PJSUA by calling pjsua_init(). This function takes several optional configuration settings in the argument, if application wants to set them.
Sample code to initialize PJSUA in C code:
Sample code to initialize PJSUA in Python 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)
After PJSUA is initialized with pjsua_init(), application will normally need/want to perform the following tasks:
After all initializations have been done, application must call pjsua_start() to start PJSUA. This function will check that all settings 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.
Sample code: static pj_status_t app_run(void)
{
pj_status_t status;
status = pjsua_start();
if (status != PJ_SUCCESS) {
pjsua_destroy();
pjsua_perror(THIS_FILE, "Error starting pjsua", status);
return status;
}
while (1) {
char choice[10];
printf("Select menu: ");
fgets(choice, sizeof(choice), stdin);
...
}
}
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.
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
|
Data Structures |
| struct | pjsua_logging_config |
| struct | pjsua_callback |
| struct | pjsua_config |
| struct | pjsua_msg_data |
Defines |
| #define | PJSUA_INVALID_ID (-1) |
| #define | PJSUA_ACC_MAX_PROXIES 8 |
| #define | PJSUA_DEFAULT_USE_SRTP PJMEDIA_SRTP_DISABLED |
| #define | PJSUA_DEFAULT_SRTP_SECURE_SIGNALING 1 |
| #define | pjsip_cred_dup pjsip_cred_info_dup |
Typedefs |
| typedef int | pjsua_call_id |
| typedef int | pjsua_acc_id |
| typedef int | pjsua_buddy_id |
| typedef int | pjsua_player_id |
| typedef int | pjsua_recorder_id |
| typedef int | pjsua_conf_port_id |
| typedef struct pjsua_media_config | pjsua_media_config |
Functions |
| void | pjsua_logging_config_default (pjsua_logging_config *cfg) |
| void | pjsua_logging_config_dup (pj_pool_t *pool, pjsua_logging_config *dst, const pjsua_logging_config *src) |
| void | pjsua_config_default (pjsua_config *cfg) |
| void | pjsua_config_dup (pj_pool_t *pool, pjsua_config *dst, const pjsua_config *src) |
| void | pjsua_msg_data_init (pjsua_msg_data *msg_data) |
| pj_status_t | pjsua_create (void) |
| pj_status_t | pjsua_init (const pjsua_config *ua_cfg, const pjsua_logging_config *log_cfg, const pjsua_media_config *media_cfg) |
| pj_status_t | pjsua_start (void) |
| pj_status_t | pjsua_destroy (void) |
| int | pjsua_handle_events (unsigned msec_timeout) |
| pj_pool_t * | pjsua_pool_create (const char *name, pj_size_t init_size, pj_size_t increment) |
| pj_status_t | pjsua_reconfigure_logging (const pjsua_logging_config *c) |
| pjsip_endpoint * | pjsua_get_pjsip_endpt (void) |
| pjmedia_endpt * | pjsua_get_pjmedia_endpt (void) |
| pj_pool_factory * | pjsua_get_pool_factory (void) |
| pj_status_t | pjsua_detect_nat_type (void) |
| pj_status_t | pjsua_get_nat_type (pj_stun_nat_type *type) |
| pj_status_t | pjsua_verify_sip_url (const char *url) |
| void | pjsua_perror (const char *sender, const char *title, pj_status_t status) |
| void | pjsua_dump (pj_bool_t detail) |
Define Documentation
| #define PJSUA_INVALID_ID (-1) |
Constant to identify invalid ID for all sorts of IDs.
| #define PJSUA_ACC_MAX_PROXIES 8 |
Maximum proxies in account.
Default value of SRTP mode usage. Valid values are PJMEDIA_SRTP_DISABLED, PJMEDIA_SRTP_OPTIONAL, and PJMEDIA_SRTP_MANDATORY.
| #define PJSUA_DEFAULT_SRTP_SECURE_SIGNALING 1 |
Default value of secure signaling requirement for SRTP. Valid values are: 0: SRTP does not require secure signaling 1: SRTP requires secure transport such as TLS 2: SRTP requires secure end-to-end transport (SIPS)
| #define pjsip_cred_dup pjsip_cred_info_dup |
The implementation has been moved to sip_auth.h
Typedef Documentation
File player identification
File recorder identification
Conference port identification
Function Documentation
Use this function to initialize logging config.
- Parameters:
-
| cfg | The logging config to be initialized. |
- Python Syntax:
- The Python function instantiates and initialize the logging config:
logging_cfg = py_pjsua.logging_config_default()
Use this function to duplicate logging config.
- Parameters:
-
| pool | Pool to use. |
| dst | Destination config. |
| src | Source config. |
- Python Syntax:
- Not available (for now). Ideally we should be able to just assign one config to another, but this has not been tested.
Use this function to initialize pjsua config.
- Parameters:
-
| cfg | pjsua config to be initialized. |
- Python Sample Syntax:
- The corresponding Python function creates an instance of the config and initializes it to the default settings:
cfg = py_pjsua.config_default()
Duplicate pjsua_config.
- Parameters:
-
| pool | The pool to get memory from. |
| dst | Destination config. |
| src | Source config. |
Initialize message data.
- Parameters:
-
| msg_data | Message data to be initialized. |
- Python
- The corresponding Python function creates and initializes the structure:
msg_data = py_pjsua.msg_data_init()
Instantiate pjsua application. Application must call this function before calling any other functions, to make sure that the underlying libraries are properly initialized. Once this function has returned success, application must call pjsua_destroy() before quitting.
- Returns:
- PJ_SUCCESS on success, or the appropriate error code.
- Python:
status = py_pjsua.create()
Initialize pjsua with the specified settings. All the settings are optional, and the default values will be used when the config is not specified.
Note that pjsua_create() MUST be called before calling this function.
- Parameters:
-
| ua_cfg | User agent configuration. |
| log_cfg | Optional logging configuration. |
| media_cfg | Optional media configuration. |
- Returns:
- PJ_SUCCESS on success, or the appropriate error code.
- Python:
- The function is similar in Python:
status = py_pjsua.init(ua_cfg, log_cfg, media_cfg)
Note that ua_cfg, log_cfg, and media_cfg are optional, and the Python script may pass None if it doesn't want to configure the setting.
Application is recommended to call this function after all initialization is done, so that the library can do additional checking set up additional
Application may call this function anytime after pjsua_init().
- Returns:
- PJ_SUCCESS on success, or the appropriate error code.
- Python:
- The function is similar in Python:
status = py_pjsua.start()
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.
- Returns:
- PJ_SUCCESS on success, or the appropriate error code.
- Python:
- The function is similar in Python:
status = py_pjsua.destroy()
| int pjsua_handle_events |
( |
unsigned |
msec_timeout |
) |
|
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 (thread_cnt field) in pjsua_config structure, because polling then will be done by these worker threads instead.
- Parameters:
-
| msec_timeout | Maximum time to wait, in miliseconds. |
- Returns:
- The number of events that have been handled during the poll. Negative value indicates error, and application can retrieve the error as (status = -return_value).
- Python:
- The function is similar in Python:
n = py_pjsua.handle_events(msec_timeout)
Create memory pool to be used by the application. Once application finished using the pool, it must be released with pj_pool_release().
- Parameters:
-
| name | Optional pool name. |
| init_size | Initial size of the pool. |
| increment | Increment size. |
- Returns:
- The pool, or NULL when there's no memory.
- Python:
- Python script may also create a pool object from the script:
pool = py_pjsua.pool_create(name, init_size, increment)
Application can call this function at any time (after pjsua_create(), of course) to change logging settings.
- Parameters:
-
- Returns:
- PJ_SUCCESS on success, or the appropriate error code.
- Python:
- The function is similar in Python:
status = py_pjsua.reconfigure_logging(log_cfg)
Internal function to get SIP endpoint instance of pjsua, which is needed for example to register module, create transports, etc. Only valid after pjsua_init() is called.
- Returns:
- SIP endpoint instance.
- Python:
- Application may retrieve the SIP endpoint instance:
endpt = py_pjsua.get_pjsip_endpt()
However currently the object is just an opaque object and does not have any use for Python scripts.
Internal function to get media endpoint instance. Only valid after pjsua_init() is called.
- Returns:
- Media endpoint instance.
- Python:
- Application may retrieve the media endpoint instance:
endpt = py_pjsua.get_pjmedia_endpt()
However currently the object is just an opaque object and does not have any use for Python scripts.
Internal function to get PJSUA pool factory. Only valid after pjsua_create() is called.
- Returns:
- Pool factory currently used by PJSUA.
- Python:
- Application may retrieve the pool factory instance:
endpt = py_pjsua.get_pool_factory()
However currently the object is just an opaque object and does not have any use for Python scripts.
This is a utility function to detect NAT type in front of this endpoint. Once invoked successfully, this function will complete asynchronously and report the result in on_nat_detect() callback of pjsua_callback.
After NAT has been detected and the callback is called, application can get the detected NAT type by calling pjsua_get_nat_type(). Application can also perform NAT detection by calling pjsua_detect_nat_type() again at later time.
Note that STUN must be enabled to run this function successfully.
- Returns:
- PJ_SUCCESS on success, or the appropriate error code.
Get the NAT type as detected by pjsua_detect_nat_type() function. This function will only return useful NAT type after pjsua_detect_nat_type() has completed successfully and on_nat_detect() callback has been called.
- Parameters:
-
- Returns:
- When detection is in progress, this function will return PJ_EPENDING and type will be set to PJ_STUN_NAT_TYPE_UNKNOWN. After NAT type has been detected successfully, this function will return PJ_SUCCESS and type will be set to the correct value. Other return values indicate error and type will be set to PJ_STUN_NAT_TYPE_ERR_UNKNOWN.
- See also:
- pjsua_call_get_rem_nat_type()
This is a utility function to verify that valid SIP url is given. If the URL is valid, PJ_SUCCESS will be returned.
- Parameters:
-
| url | The URL, as NULL terminated string. |
- Returns:
- PJ_SUCCESS on success, or the appropriate error code.
- Python:
status = py_pjsua.verify_sip_url(url)
| void pjsua_perror |
( |
const char * |
sender, |
|
|
const char * |
title, |
|
|
pj_status_t |
status | |
|
) |
| | |
This is a utility function to display error message for the specified error code. The error message will be sent to the log.
- Parameters:
-
| sender | The log sender field. |
| title | Message title for the error. |
| status | Status code. |
- Python:
py_pjsua.perror(sender, title, status)
This is a utility function to dump the stack states to log, using verbosity level 3.
- Parameters:
-
| detail | Will print detailed output (such as list of SIP transactions) when non-zero. |
PJSIP Open Source, high performance, small footprint, and very very portable SIP stack
(C)2003-2008 Benny Prijono
|
|