Group PJSUA2_UA

group PJSUA2_UA

Typedefs

typedef std::vector<SslCertName> SslCertNameVector

Array of SSL certificate type and name.

struct OnNatDetectionCompleteParam

#include <endpoint.hpp>

Argument to Endpoint::onNatDetectionComplete() callback.

Public Members

pj_status_t status

Status of the detection process. If this value is not PJ_SUCCESS, the detection has failed and nat_type field will contain PJ_STUN_NAT_TYPE_UNKNOWN.

string reason

The text describing the status, if the status is not PJ_SUCCESS.

pj_stun_nat_type natType

This contains the NAT type as detected by the detection procedure. This value is only valid when the status is PJ_SUCCESS.

string natTypeName

Text describing that NAT type.

struct OnNatCheckStunServersCompleteParam

#include <endpoint.hpp>

Argument to Endpoint::onNatCheckStunServersComplete() callback.

Public Members

Token userData

Arbitrary user data that was passed to Endpoint::natCheckStunServers() function.

pj_status_t status

This will contain PJ_SUCCESS if at least one usable STUN server is found, otherwise it will contain the last error code during the operation.

string name

The server name that yields successful result. This will only contain value if status is successful.

SocketAddress addr

The server IP address and port in “IP:port” format. This will only contain value if status is successful.

struct OnTimerParam

#include <endpoint.hpp>

Parameter of Endpoint::onTimer() callback.

Public Members

Token userData

Arbitrary user data that was passed to Endpoint::utilTimerSchedule() function.

unsigned msecDelay

The interval of this timer, in miliseconds.

struct SslCertName

#include <endpoint.hpp>

SSL certificate type and name structure.

Public Functions

inline SslCertName()

Default constructor

Public Members

pj_ssl_cert_name_type type

Name type

string name

The name

struct SslCertInfo

#include <endpoint.hpp>

SSL certificate information.

Public Functions

SslCertInfo()

Constructor.

bool isEmpty() const

Check if the info is set with empty values.

Returns:

True if the info is empty.

void fromPj(const pj_ssl_cert_info &info)

Convert from pjsip

Public Members

unsigned version

Certificate version

unsigned char serialNo[20]

Serial number, array of octets, first index is MSB

string subjectCn

Subject common name

string subjectInfo

One line subject, fields are separated by slash, e.g: “CN=sample.org/OU=HRD”

string issuerCn

Issuer common name

string issuerInfo

One line subject, fields are separated by slash

TimeVal validityStart

Validity start

TimeVal validityEnd

Validity end

bool validityGmt

Flag if validity date/time use GMT

SslCertNameVector subjectAltName

Subject alternative name extension

string raw

Raw certificate in PEM format, only available for remote certificate

struct TlsInfo

#include <endpoint.hpp>

TLS transport information.

Public Functions

TlsInfo()

Constructor.

bool isEmpty() const

Check if the info is set with empty values.

Returns:

True if the info is empty.

void fromPj(const pjsip_tls_state_info &info)

Convert from pjsip

Public Members

bool established

Describes whether secure socket connection is established, i.e: TLS/SSL handshaking has been done successfully.

unsigned protocol

Describes secure socket protocol being used, see pj_ssl_sock_proto. Use bitwise OR operation to combine the protocol type.

pj_ssl_cipher cipher

Describes cipher suite being used, this will only be set when connection is established.

string cipherName

Describes cipher name being used, this will only be set when connection is established.

SocketAddress localAddr

Describes local address.

SocketAddress remoteAddr

Describes remote address.

SslCertInfo localCertInfo

Describes active local certificate info. Use SslCertInfo.isEmpty() to check if the local cert info is available.

SslCertInfo remoteCertInfo

Describes active remote certificate info. Use SslCertInfo.isEmpty() to check if the remote cert info is available.

unsigned verifyStatus

Status of peer certificate verification.

StringVector verifyMsgs

Error messages (if any) of peer certificate verification, based on the field verifyStatus above.

struct OnTransportStateParam

#include <endpoint.hpp>

Parameter of Endpoint::onTransportState() callback.

Public Members

TransportHandle hnd

The transport handle.

string type

The transport type.

pjsip_transport_state state

Transport current state.

pj_status_t lastError

The last error code related to the transport state.

TlsInfo tlsInfo

TLS transport info, only used if transport type is TLS. Use TlsInfo.isEmpty() to check if this info is available.

struct OnSelectAccountParam

#include <endpoint.hpp>

Parameter of Endpoint::onSelectAccount() callback.

Public Members

SipRxData rdata

The incoming request.

int accountIndex

The account index to be used to handle the request. Upon entry, this will be filled by the account index chosen by the library. Application may change it to another value to use another account.

struct IpChangeParam

#include <endpoint.hpp>

Parameter of Endpoint::handleIpChange().

Public Functions

IpChangeParam()

Constructor.

pjsua_ip_change_param toPj() const

Export to pjsua_ip_change_param.

void fromPj(const pjsua_ip_change_param &param)

Convert from pjsip

Public Members

bool restartListener

If set to PJ_TRUE, this will restart the transport listener.

Default : PJ_TRUE

unsigned restartLisDelay

If restartListener is set to PJ_TRUE, some delay might be needed for the listener to be restarted. Use this to set the delay.

Default : PJSUA_TRANSPORT_RESTART_DELAY_TIME

bool shutdownTransport

If set to PJ_TRUE, this will forcefully shutdown all transports. Note that this will shutdown TCP/TLS transports only, UDP transport should be restarted via restart_listener.

Default : PJ_TRUE

struct RegProgressParam

#include <endpoint.hpp>

Information of Update contact on IP change progress.

Public Members

bool isRegister

Indicate if this is a Register or Un-Register message.

int code

SIP status code received.

struct OnIpChangeProgressParam

#include <endpoint.hpp>

Parameter of Endpoint::onIpChangeProgress().

Public Members

pjsua_ip_change_op op

The IP change progress operation.

pj_status_t status

The operation progress status.

TransportId transportId

Information of the transport id. This is only available when the operation is PJSUA_IP_CHANGE_OP_RESTART_LIS.

int accId

Information of the account id. This is only available when the operation is:

• PJSUA_IP_CHANGE_OP_ACC_SHUTDOWN_TP

• PJSUA_IP_CHANGE_OP_ACC_UPDATE_CONTACT

• PJSUA_IP_CHANGE_OP_ACC_HANGUP_CALLS

• PJSUA_IP_CHANGE_OP_ACC_REINVITE_CALLS

int callId

Information of the call id. This is only available when the operation is PJSUA_IP_CHANGE_OP_ACC_HANGUP_CALLS or PJSUA_IP_CHANGE_OP_ACC_REINVITE_CALLS

RegProgressParam regInfo

Registration information. This is only available when the operation is PJSUA_IP_CHANGE_OP_ACC_UPDATE_CONTACT

struct OnMediaEventParam

#include <endpoint.hpp>

Parameter of Endpoint::onCallMediaEvent() callback.

Public Members

MediaEvent ev

The media event.

struct OnRejectedIncomingCallParam

#include <endpoint.hpp>

Parameter of Endpoint::onRejectedIncomingCall() callback.

Public Members

pjsua_call_id callId

The incoming call id. This will be set to PJSUA_INVALID_ID when there is no available call slot at the time.

std::string localInfo

Local URI.

std::string remoteInfo

Remote URI.

int statusCode

Rejection code.

std::string reason

Rejection text.

SipRxData rdata

The original INVITE message, on some cases it is not available.

struct DigestChallenge

#include <endpoint.hpp>

This structure describes authentication challenge used in Proxy-Authenticate or WWW-Authenticate for digest authentication scheme.

Public Functions

void fromPj(const pjsip_digest_challenge &prm)

Convert from pjsip

pjsip_digest_challenge toPj() const

Convert to pjsip

Public Members

std::string realm

Realm for the challenge.

StringToStringMap otherParam

Other parameters.

std::string domain

Domain.

std::string nonce

Nonce challenge.

std::string opaque

Opaque value.

int stale

Stale parameter.

std::string algorithm

Algorithm parameter.

std::string qop

Quality of protection.

struct DigestCredential

#include <endpoint.hpp>

This structure describe credential used in Authorization and Proxy-Authorization header for digest authentication scheme.

Public Functions

void fromPj(const pjsip_digest_credential &prm)

Convert from pjsip

pjsip_digest_credential toPj() const

Convert to pjsip

Public Members

std::string realm

Realm of the credential

StringToStringMap otherParam

Other parameters.

std::string username

Username parameter.

std::string nonce

Nonce parameter.

std::string uri

URI parameter.

std::string response

Response digest.

std::string algorithm

Algorithm.

std::string cnonce

Cnonce.

std::string opaque

Opaque value.

std::string qop

Quality of protection.

std::string nc

Nonce count.

struct OnCredAuthParam

#include <endpoint.hpp>

Parameter of Endpoint::onCredAuth() callback.

Public Members

DigestChallenge digestChallenge

Digest challenge. The authentication challenge sent by server in 401 or 401 response, as either Proxy-Authenticate or WWW-Authenticate header.

AuthCredInfo credentialInfo

Credential info.

std::string method

The request method.

DigestCredential digestCredential

The digest credential where the digest response will be placed to.

Upon calling this function, the nonce, nc, cnonce, qop, uri, and realm fields of this structure must be set by the caller.

Upon return, the callback must set the response in DigestCredential.response.

struct UaConfig : public pj::PersistentObject

#include <endpoint.hpp>

SIP User Agent related settings.

Public Functions

UaConfig()

Default constructor to initialize with default values.

void fromPj(const pjsua_config &ua_cfg)

Construct from pjsua_config.

pjsua_config toPj() const

Export to pjsua_config

virtual void readObject(const ContainerNode &node)

Read this object from a container.

Parameters:

node – Container to write values from.

virtual void writeObject(ContainerNode &node) const

Write this object to a container.

Parameters:

node – Container to write values to.

Public Members

unsigned maxCalls

Maximum calls to support (default: 4). The value specified here must be smaller than the compile time maximum settings PJSUA_MAX_CALLS, which by default is 32. To increase this limit, the library must be recompiled with new PJSUA_MAX_CALLS value.

unsigned threadCnt

Number of worker threads. Normally application will want to have at least one worker thread, unless when it wants to poll the library periodically, which in this case the worker thread can be set to zero.

bool mainThreadOnly

When this flag is non-zero, all callbacks that come from thread other than main thread will be posted to the main thread and to be executed by Endpoint::libHandleEvents() function. This includes the logging callback. Note that this will only work if threadCnt is set to zero and Endpoint::libHandleEvents() is performed by main thread. By default, the main thread is set from the thread that invoke Endpoint::libCreate()

Default: false

StringVector nameserver

Array of nameservers to be used by the SIP resolver subsystem. The order of the name server specifies the priority (first name server will be used first, unless it is not reachable).

StringVector outboundProxies

Specify the URL of outbound proxies to visit for all outgoing requests. The outbound proxies will be used for all accounts, and it will be used to build the route set for outgoing requests. The final route set for outgoing requests will consists of the outbound proxies and the proxy configured in the account.

string userAgent

Optional user agent string (default empty). If it’s empty, no User-Agent header will be sent with outgoing requests.

StringVector stunServer

Array of STUN servers to try. The library will try to resolve and contact each of the STUN server entry until it finds one that is usable. Each entry may be a domain name, host name, IP address, and it may contain an optional port number. For example:

• ”pjsip.org” (domain name)

• ”sip.pjsip.org” (host name)

• ”pjsip.org:33478” (domain name and a non-standard port number)

• ”10.0.0.1:3478” (IP address and port number)

When nameserver is configured in the pjsua_config.nameserver field, if entry is not an IP address, it will be resolved with DNS SRV resolution first, and it will fallback to use DNS A resolution if this fails. Port number may be specified even if the entry is a domain name, in case the DNS SRV resolution should fallback to a non-standard port.

When nameserver is not configured, entries will be resolved with pj_gethostbyname() if it’s not an IP address. Port number may be specified if the server is not listening in standard STUN port.

bool stunTryIpv6

This specifies if the library should try to do an IPv6 resolution of the STUN servers if the IPv4 resolution fails. It can be useful in an IPv6-only environment, including on NAT64.

Default: FALSE

bool stunIgnoreFailure

This specifies if the library startup should ignore failure with the STUN servers. If this is set to PJ_FALSE, the library will refuse to start if it fails to resolve or contact any of the STUN servers.

Default: TRUE

int natTypeInSdp

Support for adding and parsing NAT type in the SDP to assist troubleshooting. The valid values are:

• 0: no information will be added in SDP, and parsing is disabled.

• 1: only the NAT type number is added.

• 2: add both NAT type number and name.

Default: 1

bool mwiUnsolicitedEnabled

Handle unsolicited NOTIFY requests containing message waiting indication (MWI) info. Unsolicited MWI is incoming NOTIFY requests which are not requested by client with SUBSCRIBE request.

If this is enabled, the library will respond 200/OK to the NOTIFY request and forward the request to Endpoint::onMwiInfo() callback.

Note: the callback will not be invoked and 481/”No account to handle” response will be sent if this is enabled but no account is configured.

See also AccountMwiConfig.enabled.

Default: PJ_TRUE

bool enableUpnp

Specify whether to enable UPnP.

Note that this setting can be further customized in account configuration (pjsua_acc_config).

Default: FALSE

string upnpIfName

Specify which interface to use for UPnP. If empty, UPnP will use the first suitable interface found.

Note that this setting is only applicable if UPnP is enabled.

Default: empty string

struct LogEntry

#include <endpoint.hpp>

Data containing log entry to be written by the LogWriter.

Public Members

int level

Log verbosity level of this message

string msg

The log message

long threadId

ID of current thread

string threadName

The name of the thread that writes this log

class LogWriter

#include <endpoint.hpp>

Interface for writing log messages. Applications can inherit this class and supply it in the LogConfig structure to implement custom log writing facility.

Public Functions

inline virtual ~LogWriter()

Destructor

virtual void write(const LogEntry &entry) = 0

Write a log entry.

struct LogConfig : public pj::PersistentObject

#include <endpoint.hpp>

Logging configuration, which can be (optionally) specified when calling Lib::init().

Public Functions

LogConfig()

Default constructor initialises with default values

void fromPj(const pjsua_logging_config &lc)

Construct from pjsua_logging_config

pjsua_logging_config toPj() const

Generate pjsua_logging_config.

virtual void readObject(const ContainerNode &node)

Read this object from a container.

Parameters:

node – Container to write values from.

virtual void writeObject(ContainerNode &node) const

Write this object to a container.

Parameters:

node – Container to write values to.

Public Members

unsigned msgLogging

Log incoming and outgoing SIP message? Yes!

unsigned level

Input verbosity level. Value 5 is reasonable.

unsigned consoleLevel

Verbosity level for console. Value 4 is reasonable.

unsigned decor

Log decoration.

string filename

Optional log filename if app wishes the library to write to log file.

unsigned fileFlags

Additional flags to be given to pj_file_open() when opening the log file. By default, the flag is PJ_O_WRONLY. Application may set PJ_O_APPEND here so that logs are appended to existing file instead of overwriting it.

Default is 0.

LogWriter *writer

Custom log writer, if required. This instance will be destroyed by the endpoint when the endpoint is destroyed.

struct MediaConfig : public pj::PersistentObject

#include <endpoint.hpp>

This structure describes media configuration, which will be specified when calling Lib::init().

Public Functions

MediaConfig()

Default constructor initialises with default values

void fromPj(const pjsua_media_config &mc)

Construct from pjsua_media_config.

pjsua_media_config toPj() const

Export

virtual void readObject(const ContainerNode &node)

Read this object from a container.

Parameters:

node – Container to write values from.

virtual void writeObject(ContainerNode &node) const

Write this object to a container.

Parameters:

node – Container to write values to.

Public Members

unsigned clockRate

Clock rate to be applied to the conference bridge. If value is zero, default clock rate will be used (PJSUA_DEFAULT_CLOCK_RATE, which by default is 16KHz).

unsigned sndClockRate

Clock rate to be applied when opening the sound device. If value is zero, conference bridge clock rate will be used.

bool sndUseSwClock

Sound device uses Clock Generator instead of native sound device clock, generally this will be able to reduce jitter and clock drift.

This option is not applicable for encoded/non-PCM format.

Default value: PJSUA_DEFAULT_SND_USE_SW_CLOCK

unsigned channelCount

Channel count be applied when opening the sound device and conference bridge.

unsigned audioFramePtime

Specify audio frame ptime. The value here will affect the samples per frame of both the sound device and the conference bridge. Specifying lower ptime will normally reduce the latency.

Default value: PJSUA_DEFAULT_AUDIO_FRAME_PTIME

unsigned maxMediaPorts

Specify maximum number of media ports to be created in the conference bridge. Since all media terminate in the bridge (calls, file player, file recorder, etc), the value must be large enough to support all of them. However, the larger the value, the more computations are performed.

Default value: PJSUA_MAX_CONF_PORTS

bool hasIoqueue

Specify whether the media manager should manage its own ioqueue for the RTP/RTCP sockets. If yes, ioqueue will be created and at least one worker thread will be created too. If no, the RTP/RTCP sockets will share the same ioqueue as SIP sockets, and no worker thread is needed.

Normally application would say yes here, unless it wants to run everything from a single thread.

unsigned threadCnt

Specify the number of worker threads to handle incoming RTP packets. A value of one is recommended for most applications.

unsigned quality

Media quality, 0-10, according to this table: 5-10: resampling use large filter, 3-4: resampling use small filter, 1-2: resampling use linear. The media quality also sets speex codec quality/complexity to the number.

Default: PJSUA_DEFAULT_CODEC_QUALITY.

unsigned ptime

Specify default codec ptime.

Default: 0 (codec specific)

bool noVad

Disable VAD?

Default: 0 (codec specific)

unsigned ilbcMode

iLBC mode (20 or 30).

Default: 30 (PJSUA_DEFAULT_ILBC_MODE)

unsigned txDropPct

Percentage of RTP packet to drop in TX direction (to simulate packet lost).

Default: 0

unsigned rxDropPct

Percentage of RTP packet to drop in RX direction (to simulate packet lost).

Default: 0

unsigned ecOptions

Echo canceller options (see pjmedia_echo_create()). Specify PJMEDIA_ECHO_USE_SW_ECHO here if application wishes to use software echo canceller instead of device EC.

Default: 0.

unsigned ecTailLen

Echo canceller tail length, in miliseconds. Setting this to zero will disable echo cancellation.

Default: PJSUA_DEFAULT_EC_TAIL_LEN

unsigned sndRecLatency

Audio capture buffer length, in milliseconds.

Default: PJMEDIA_SND_DEFAULT_REC_LATENCY

unsigned sndPlayLatency

Audio playback buffer length, in milliseconds.

Default: PJMEDIA_SND_DEFAULT_PLAY_LATENCY

int jbInit

Jitter buffer initial prefetch delay in msec. The value must be between jb_min_pre and jb_max_pre below. If the value is 0, prefetching will be disabled.

Default: -1 (to use default stream settings, currently 0)

int jbMinPre

Jitter buffer minimum prefetch delay in msec.

Default: -1 (to use default stream settings, currently codec ptime)

int jbMaxPre

Jitter buffer maximum prefetch delay in msec.

Default: -1 (to use default stream settings, currently 80% of jbMax)

int jbMax

Set maximum delay that can be accomodated by the jitter buffer msec.

Default: -1 (to use default stream settings, currently 500 msec)

pjmedia_jb_discard_algo jbDiscardAlgo

Set the algorithm the jitter buffer uses to discard frames in order to adjust the latency.

Default: PJMEDIA_JB_DISCARD_PROGRESSIVE

int sndAutoCloseTime

Specify idle time of sound device before it is automatically closed, in seconds. Use value -1 to disable the auto-close feature of sound device

Default : 1

bool vidPreviewEnableNative

Specify whether built-in/native preview should be used if available. In some systems, video input devices have built-in capability to show preview window of the device. Using this built-in preview is preferable as it consumes less CPU power. If built-in preview is not available, the library will perform software rendering of the input. If this field is set to PJ_FALSE, software preview will always be used.

Default: PJ_TRUE

struct EpConfig : public pj::PersistentObject

#include <endpoint.hpp>

Endpoint configuration

Public Functions

virtual void readObject(const ContainerNode &node)

Read this object from a container.

Parameters:

node – Container to write values from.

virtual void writeObject(ContainerNode &node) const

Write this object to a container.

Parameters:

node – Container to write values to.

Public Members

UaConfig uaConfig

UA config

LogConfig logConfig

Logging config

MediaConfig medConfig

Media config

struct PendingJob

Public Functions

virtual void execute(bool is_pending) = 0

Perform the job

inline virtual ~PendingJob()

Virtual destructor

class Endpoint

#include <endpoint.hpp>

Endpoint represents an instance of pjsua library. There can only be one instance of pjsua library in an application, hence this class is a singleton.

Public Functions

Endpoint()

Default constructor

virtual ~Endpoint()

Virtual destructor

Version libVersion() const

Get library version.

void libCreate()

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 libDestroy() before quitting.

pjsua_state libGetState() const

Get library state.

Returns:

library state.

void libInit(const EpConfig &prmEpConfig)

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 create() MUST be called before calling this function.

Parameters:

prmEpConfig – Endpoint configurations

void libStart()

Call this function after all initialization is done, so that the library can do additional checking set up. Application may call this function any time after init().

void libRegisterThread(const string &name)

Register a thread that was created by external or native API to the library. Note that each time this function is called, it will allocate some memory to store the thread description, which will only be freed when the library is destroyed.

Parameters:

name – The optional name to be assigned to the thread.

bool libIsThreadRegistered()

Check if this thread has been registered to the library. Note that this function is only applicable for library main & worker threads and external/native threads registered using libRegisterThread().

void libStopWorkerThreads()

Stop all worker threads.

int libHandleEvents(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.

If EpConfig::UaConfig::mainThreadOnly is enabled and this function is called from the main thread (by default the main thread is thread that calls libCreate()), this function will also scan and run any pending jobs in the list.

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).

void libDestroy(unsigned prmFlags = 0)

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 block for few seconds 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.

Parameters:

prmFlags – Combination of pjsua_destroy_flag enumeration.

string utilStrError(pj_status_t prmErr)

Retrieve the error string for the specified status code.

Parameters:

prmErr – The error code.

void utilLogWrite(int prmLevel, const string &prmSender, const string &prmMsg)

Write a log message.

Parameters:

• prmLevel – Log verbosity level (1-5)

• prmSender – The log sender.

• prmMsg – The log message.

void utilLogWrite(LogEntry &e)

Write a log entry. Application must implement its own custom LogWriter and this function will then call the LogWriter::write() method. Note that this function does not call PJSIP’s internal logging functionality. For that, you should use utilLogWrite(prmLevel, prmSender, prmMsg) above.

Parameters:

e – The log entry.

pj_status_t utilVerifySipUri(const string &prmUri)

This is a utility function to verify that valid SIP url is given. If the URL is a valid SIP/SIPS scheme, PJ_SUCCESS will be returned.

See also

utilVerifyUri()

Parameters:

prmUri – The URL string.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t utilVerifyUri(const string &prmUri)

This is a utility function to verify that valid URI is given. Unlike utilVerifySipUri(), this function will return PJ_SUCCESS if tel: URI is given.

See also

pjsua_verify_sip_url()

Parameters:

prmUri – The URL string.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

Token utilTimerSchedule(unsigned prmMsecDelay, Token prmUserData)

Schedule a timer with the specified interval and user data. When the interval elapsed, onTimer() callback will be called. Note that the callback may be executed by different thread, depending on whether worker thread is enabled or not.

Parameters:

• prmMsecDelay – The time interval in msec.

• prmUserData – Arbitrary user data, to be given back to application in the callback.

Returns:

Token to identify the timer, which could be given to utilTimerCancel().

void utilTimerCancel(Token prmToken)

Cancel previously scheduled timer with the specified timer token.

Parameters:

prmToken – The timer token, which was returned from previous utilTimerSchedule() call.

void utilAddPendingJob(PendingJob *job)

Utility to register a pending job to be executed by main thread. If EpConfig::UaConfig::mainThreadOnly is false, the job will be executed immediately.

Parameters:

job – The job class.

IntVector utilSslGetAvailableCiphers()

Get cipher list supported by SSL/TLS backend.

void natDetectType(void)

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 onNatDetectionComplete().

After NAT has been detected and the callback is called, application can get the detected NAT type by calling natGetType(). Application can also perform NAT detection by calling natDetectType() again at later time.

Note that STUN must be enabled to run this function successfully.

pj_stun_nat_type natGetType()

Get the NAT type as detected by natDetectType() function. This function will only return useful NAT type after natDetectType() has completed successfully and onNatDetectionComplete() callback has been called.

Exception: if this function is called while detection is in progress, PJ_EPENDING exception will be raised.

void natUpdateStunServers(const StringVector &prmServers, bool prmWait)

Update the STUN servers list. The libInit() must have been called before calling this function.

Parameters:

• prmServers – Array of STUN servers to try. The endpoint will try to resolve and contact each of the STUN server entry until it finds one that is usable. Each entry may be a domain name, host name, IP address, and it may contain an optional port number. For example:

  • ”pjsip.org” (domain name)

  • ”sip.pjsip.org” (host name)

  • ”pjsip.org:33478” (domain name and a non- standard port number)

  • ”10.0.0.1:3478” (IP address and port number)

• prmWait – Specify if the function should block until it gets the result. In this case, the function will block while the resolution is being done, and the callback onNatCheckStunServersComplete() will be called before this function returns.

void natCheckStunServers(const StringVector &prmServers, bool prmWait, Token prmUserData)

Auxiliary function to resolve and contact each of the STUN server entries (sequentially) to find which is usable. The libInit() must have been called before calling this function.

See also

natCancelCheckStunServers()

Parameters:

• prmServers – Array of STUN servers to try. The endpoint will try to resolve and contact each of the STUN server entry until it finds one that is usable. Each entry may be a domain name, host name, IP address, and it may contain an optional port number. For example:

  • ”pjsip.org” (domain name)

  • ”sip.pjsip.org” (host name)

  • ”pjsip.org:33478” (domain name and a non- standard port number)

  • ”10.0.0.1:3478” (IP address and port number)

• prmWait – Specify if the function should block until it gets the result. In this case, the function will block while the resolution is being done, and the callback will be called before this function returns.

• prmUserData – Arbitrary user data to be passed back to application in the callback.

void natCancelCheckStunServers(Token token, bool notify_cb = false)

Cancel pending STUN resolution which match the specified token.

Exception: PJ_ENOTFOUND if there is no matching one, or other error.

Parameters:

• token – The token to match. This token was given to natCheckStunServers()

• notify_cb – Boolean to control whether the callback should be called for cancelled resolutions. When the callback is called, the status in the result will be set as PJ_ECANCELLED.

TransportId transportCreate(pjsip_transport_type_e type, const TransportConfig &cfg)

Create and start a new SIP transport according to the specified settings.

Parameters:

• type – Transport type.

• cfg – Transport configuration.

Returns:

The transport ID.

IntVector transportEnum() const

Enumerate all transports currently created in the system. This function will return all transport IDs, and application may then call transportGetInfo() function to retrieve detailed information about the transport.

Returns:

Array of transport IDs.

TransportInfo transportGetInfo(TransportId id) const

Get information about transport.

Parameters:

id – Transport ID.

Returns:

Transport info.

void transportClose(TransportId id)

Close the transport. The system will wait until all transactions are closed while preventing new users from using the transport, and will close the transport when its usage count reaches zero.

Parameters:

id – Transport ID.

void transportShutdown(TransportHandle tp)

Start graceful shutdown procedure for this transport handle. After graceful shutdown has been initiated, no new reference can be obtained for the transport. However, existing objects that currently uses the transport may still use this transport to send and receive packets. After all objects release their reference to this transport, the transport will be destroyed immediately.

Note: application normally uses this API after obtaining the handle from onTransportState() callback.

Parameters:

tp – The transport.

void hangupAllCalls(void)

Terminate all calls. This will initiate call hangup for all currently active calls.

void mediaAdd(AudioMedia &media)

Add media to the media list.

Parameters:

media – media to be added.

void mediaRemove(AudioMedia &media)

Remove media from the media list.

Parameters:

media – media to be removed.

bool mediaExists(const AudioMedia &media) const

Check if media has been added to the media list.

Parameters:

media – media to be check.

Returns:

True if media has been added, false otherwise.

unsigned mediaMaxPorts() const

Get maximum number of media port.

Returns:

Maximum number of media port in the conference bridge.

unsigned mediaActivePorts() const

Get current number of active media port in the bridge.

Returns:

The number of active media port.

const AudioMediaVector &mediaEnumPorts() const

Warning: deprecated, use mediaEnumPorts2() instead. This function is not safe in multithreaded environment.

Enumerate all media port.

Returns:

The list of media port.

AudioMediaVector2 mediaEnumPorts2() const

Enumerate all audio media port.

Returns:

The list of audio media port.

VideoMediaVector mediaEnumVidPorts() const

Enumerate all video media port.

Returns:

The list of video media port.

AudDevManager &audDevManager()

Get the instance of Audio Device Manager.

Returns:

The Audio Device Manager.

VidDevManager &vidDevManager()

Get the instance of Video Device Manager.

Returns:

The Video Device Manager.

const CodecInfoVector &codecEnum()

Warning: deprecated, use codecEnum2() instead. This function is not safe in multithreaded environment.

Enum all supported codecs in the system.

Returns:

Array of codec info.

CodecInfoVector2 codecEnum2() const

Enum all supported codecs in the system.

Returns:

Array of codec info.

void codecSetPriority(const string &codec_id, pj_uint8_t priority)

Change codec priority.

Parameters:

• codec_id – Codec ID, which is a string that uniquely identify the codec (such as “speex/8000”).

• priority – Codec priority, 0-255, where zero means to disable the codec.

CodecParam codecGetParam(const string &codec_id) const

Get codec parameters.

Parameters:

codec_id – Codec ID.

Returns:

Codec parameters. If codec is not found, Error will be thrown.

void codecSetParam(const string &codec_id, const CodecParam param)

Set codec parameters.

Parameters:

• codec_id – Codec ID.

• param – Codec parameter to set. Set to NULL to reset codec parameter to library default settings.

const CodecInfoVector &videoCodecEnum()

Warning: deprecated, use videoCodecEnum2() instead. This function is not safe in multithreaded environment.

Enum all supported video codecs in the system.

Returns:

Array of video codec info.

CodecInfoVector2 videoCodecEnum2() const

Enum all supported video codecs in the system.

Returns:

Array of video codec info.

void videoCodecSetPriority(const string &codec_id, pj_uint8_t priority)

Change video codec priority.

Parameters:

• codec_id – Codec ID, which is a string that uniquely identify the codec (such as “H263/90000”). Please see pjsua manual or pjmedia codec reference for details.

• priority – Codec priority, 0-255, where zero means to disable the codec.

VidCodecParam getVideoCodecParam(const string &codec_id) const

Get video codec parameters.

Parameters:

codec_id – Codec ID.

Returns:

Codec parameters. If codec is not found, Error will be thrown.

void setVideoCodecParam(const string &codec_id, const VidCodecParam &param)

Set video codec parameters.

Parameters:

• codec_id – Codec ID.

• param – Codec parameter to set.

void resetVideoCodecParam(const string &codec_id)

Reset video codec parameters to library default settings.

Parameters:

codec_id – Codec ID.

CodecOpusConfig getCodecOpusConfig() const

Get codec Opus config.

void setCodecOpusConfig(const CodecOpusConfig &opus_cfg)

Set codec Opus config.

Parameters:

opus_cfg – Codec Opus configuration.

CodecLyraConfig getCodecLyraConfig() const

Get codec Lyra config.

void setCodecLyraConfig(const CodecLyraConfig &lyra_cfg)

Set codec Lyra config.

Parameters:

lyra_cfg – Codec Lyra configuration.

StringVector srtpCryptoEnum()

Enumerate all SRTP crypto-suite names.

Returns:

The list of SRTP crypto-suite name.

void handleIpChange(const IpChangeParam &param)

Inform the stack that IP address change event was detected. The stack will:

1. Restart the listener (this step is configurable via IpChangeParam.restartListener).

2. Shutdown the transport used by account registration (this step is configurable via AccountConfig.ipChangeConfig.shutdownTp).

3. Update contact URI by sending re-Registration (this step is configurable via a\ AccountConfig.natConfig.contactRewriteUse and a\ AccountConfig.natConfig.contactRewriteMethod)

4. Hangup active calls (this step is configurable via a\ AccountConfig.ipChangeConfig.hangupCalls) or continue the call by sending re-INVITE (configurable via AccountConfig.ipChangeConfig.reinviteFlags).

Parameters:

param – The IP change parameter, have a look at IpChangeParam.

inline virtual void onNatDetectionComplete(const OnNatDetectionCompleteParam &prm)

Callback when the Endpoint has finished performing NAT type detection that is initiated with natDetectType().

Parameters:

prm – Callback parameters containing the detection result.

inline virtual void onNatCheckStunServersComplete(const OnNatCheckStunServersCompleteParam &prm)

Callback when the Endpoint has finished performing STUN server checking that is initiated when calling libInit(), or by calling natCheckStunServers() or natUpdateStunServers().

Parameters:

prm – Callback parameters.

inline virtual void onTransportState(const OnTransportStateParam &prm)

This callback is called when transport state has changed.

Parameters:

prm – Callback parameters.

inline virtual void onTimer(const OnTimerParam &prm)

Callback when a timer has fired. The timer was scheduled by utilTimerSchedule().

Parameters:

prm – Callback parameters.

inline virtual void onSelectAccount(OnSelectAccountParam &prm)

This callback can be used by application to override the account to be used to handle an incoming message. Initially, the account to be used will be calculated automatically by the library. This initial account will be used if application does not implement this callback, or application sets an invalid account upon returning from this callback.

Note that currently the incoming messages requiring account assignment are INVITE, MESSAGE, SUBSCRIBE, and unsolicited NOTIFY. This callback may be called before the callback of the SIP event itself, i.e: incoming call, pager, subscription, or unsolicited-event.

Parameters:

prm – Callback parameters.

inline virtual void onIpChangeProgress(OnIpChangeProgressParam &prm)

Calling handleIpChange() may involve different operation. This callback is called to report the progress of each enabled operation.

Parameters:

prm – Callback parameters.

inline virtual void onMediaEvent(OnMediaEventParam &prm)

Notification about media events such as video notifications. This callback will most likely be called from media threads, thus application must not perform heavy processing in this callback. If application needs to perform more complex tasks to handle the event, it should post the task to another thread.

Parameters:

prm – Callback parameter.

virtual pj_status_t onCredAuth(OnCredAuthParam &prm)

Callback for custom computation of the digest AKA response.

Usually an application does not need to implement (overload) this callback because by default the response digest AKA is automatically computed using libmilenage.

To use Digest AKA authentication, add PJSIP_CRED_DATA_EXT_AKA flag in the AuthCredInfo’s dataType field of the AccountConfig, and fill up other AKA specific information in AuthCredInfo. Please see Digest AKAv1 and AKAv2 Authentication API for more information.

Parameters:

prm – Callback parameter.

Returns:

Return PJ_ENOTSUP to let the library compute the response digest automatically. Return PJ_SUCCESS if application does the computation and sets the response digest in prm.DigestCredential.response.

inline virtual void onRejectedIncomingCall(OnRejectedIncomingCallParam &prm)

This callback will be invoked when the library implicitly rejects an incoming call.

In addition to being declined explicitly using the Call::answer() method, the library may also automatically reject the incoming call due to different scenarios, e.g:

• no available call slot.

• no available account to handle the call.

• when an incoming INVITE is received with, for instance, a message containing invalid SDP.

Parameters:

prm – Callback parameters.

Public Static Functions

static Endpoint &instance()

Retrieve the singleton instance of the endpoint