Home --> Documentations --> PJSIP Reference
#include <endpoint.hpp>
|
| Endpoint () |
|
virtual | ~Endpoint () |
|
Version | libVersion () const |
|
void | libCreate () throw (Error) |
|
pjsua_state | libGetState () const |
|
void | libInit (const EpConfig &prmEpConfig) throw (Error) |
|
void | libStart () throw (Error) |
|
void | libRegisterThread (const string &name) throw (Error) |
|
bool | libIsThreadRegistered () |
|
void | libStopWorkerThreads () |
|
int | libHandleEvents (unsigned msec_timeout) |
|
void | libDestroy (unsigned prmFlags=0) throw (Error) |
|
string | utilStrError (pj_status_t prmErr) |
|
void | utilLogWrite (int prmLevel, const string &prmSender, const string &prmMsg) |
|
void | utilLogWrite (LogEntry &e) |
|
pj_status_t | utilVerifySipUri (const string &prmUri) |
|
pj_status_t | utilVerifyUri (const string &prmUri) |
|
Token | utilTimerSchedule (unsigned prmMsecDelay, Token prmUserData) throw (Error) |
|
void | utilTimerCancel (Token prmToken) |
|
void | utilAddPendingJob (PendingJob *job) |
|
IntVector | utilSslGetAvailableCiphers () throw (Error) |
|
void | natDetectType (void) throw (Error) |
|
pj_stun_nat_type | natGetType () throw (Error) |
|
void | natUpdateStunServers (const StringVector &prmServers, bool prmWait) throw (Error) |
|
void | natCheckStunServers (const StringVector &prmServers, bool prmWait, Token prmUserData) throw (Error) |
|
void | natCancelCheckStunServers (Token token, bool notify_cb=false) throw (Error) |
|
TransportId | transportCreate (pjsip_transport_type_e type, const TransportConfig &cfg) throw (Error) |
|
IntVector | transportEnum () const throw (Error) |
|
TransportInfo | transportGetInfo (TransportId id) const throw (Error) |
|
void | transportSetEnable (TransportId id, bool enabled) throw (Error) |
|
void | transportClose (TransportId id) throw (Error) |
|
void | transportShutdown (TransportHandle tp) throw (Error) |
|
void | hangupAllCalls (void) |
|
void | mediaAdd (AudioMedia &media) |
|
void | mediaRemove (AudioMedia &media) |
|
bool | mediaExists (const AudioMedia &media) const |
|
unsigned | mediaMaxPorts () const |
|
unsigned | mediaActivePorts () const |
|
const AudioMediaVector & | mediaEnumPorts () const throw (Error) |
|
AudioMediaVector2 | mediaEnumPorts2 () const throw (Error) |
|
VideoMediaVector | mediaEnumVidPorts () const throw (Error) |
|
AudDevManager & | audDevManager () |
|
VidDevManager & | vidDevManager () |
|
const CodecInfoVector & | codecEnum () throw (Error) |
|
CodecInfoVector2 | codecEnum2 () const throw (Error) |
|
void | codecSetPriority (const string &codec_id, pj_uint8_t priority) throw (Error) |
|
CodecParam | codecGetParam (const string &codec_id) const throw (Error) |
|
void | codecSetParam (const string &codec_id, const CodecParam param) throw (Error) |
|
const CodecInfoVector & | videoCodecEnum () throw (Error) |
|
CodecInfoVector2 | videoCodecEnum2 () const throw (Error) |
|
void | videoCodecSetPriority (const string &codec_id, pj_uint8_t priority) throw (Error) |
|
VidCodecParam | getVideoCodecParam (const string &codec_id) const throw (Error) |
|
void | setVideoCodecParam (const string &codec_id, const VidCodecParam ¶m) throw (Error) |
|
void | resetVideoCodecParam (const string &codec_id) throw (Error) |
|
StringVector | srtpCryptoEnum () throw (Error) |
|
void | handleIpChange (const IpChangeParam ¶m) throw (Error) |
|
virtual void | onNatDetectionComplete (const OnNatDetectionCompleteParam &prm) |
|
virtual void | onNatCheckStunServersComplete (const OnNatCheckStunServersCompleteParam &prm) |
|
virtual void | onTransportState (const OnTransportStateParam &prm) |
|
virtual void | onTimer (const OnTimerParam &prm) |
|
virtual void | onSelectAccount (OnSelectAccountParam &prm) |
|
virtual void | onIpChangeProgress (OnIpChangeProgressParam &prm) |
|
virtual void | onMediaEvent (OnMediaEventParam &prm) |
|
virtual pj_status_t | onCredAuth (OnCredAuthParam &prm) |
|
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.
◆ Endpoint()
pj::Endpoint::Endpoint |
( |
| ) |
|
◆ ~Endpoint()
virtual pj::Endpoint::~Endpoint |
( |
| ) |
|
|
virtual |
◆ instance()
Retrieve the singleton instance of the endpoint
◆ libVersion()
Version pj::Endpoint::libVersion |
( |
| ) |
const |
◆ libCreate()
void pj::Endpoint::libCreate |
( |
| ) |
|
throw | ( | Error |
| ) | | |
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.
◆ libGetState()
Get library state.
- Returns
- library state.
◆ libInit()
void pj::Endpoint::libInit |
( |
const EpConfig & |
prmEpConfig | ) |
|
throw | ( | Error |
| ) | | |
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
-
◆ libStart()
void pj::Endpoint::libStart |
( |
| ) |
|
throw | ( | Error |
| ) | | |
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().
◆ libRegisterThread()
void pj::Endpoint::libRegisterThread |
( |
const string & |
name | ) |
|
throw | ( | Error |
| ) | | |
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. |
◆ libIsThreadRegistered()
bool pj::Endpoint::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().
◆ libStopWorkerThreads()
void pj::Endpoint::libStopWorkerThreads |
( |
| ) |
|
◆ libHandleEvents()
int pj::Endpoint::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).
◆ libDestroy()
void pj::Endpoint::libDestroy |
( |
unsigned |
prmFlags = 0 | ) |
|
throw | ( | Error |
| ) | | |
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. |
◆ utilStrError()
string pj::Endpoint::utilStrError |
( |
pj_status_t |
prmErr | ) |
|
Retrieve the error string for the specified status code.
- Parameters
-
◆ utilLogWrite() [1/2]
void pj::Endpoint::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. |
◆ utilLogWrite() [2/2]
void pj::Endpoint::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
-
◆ utilVerifySipUri()
pj_status_t pj::Endpoint::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.
- Parameters
-
- Returns
- PJ_SUCCESS on success, or the appropriate error code.
- See also
- utilVerifyUri()
◆ utilVerifyUri()
pj_status_t pj::Endpoint::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.
- Parameters
-
- Returns
- PJ_SUCCESS on success, or the appropriate error code.
- See also
- pjsua_verify_sip_url()
◆ utilTimerSchedule()
Token pj::Endpoint::utilTimerSchedule |
( |
unsigned |
prmMsecDelay, |
|
|
Token |
prmUserData |
|
) |
| |
throw | ( | Error |
| ) | | |
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().
◆ utilTimerCancel()
void pj::Endpoint::utilTimerCancel |
( |
Token |
prmToken | ) |
|
Cancel previously scheduled timer with the specified timer token.
- Parameters
-
◆ utilAddPendingJob()
void pj::Endpoint::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
-
◆ utilSslGetAvailableCiphers()
Get cipher list supported by SSL/TLS backend.
◆ natDetectType()
void pj::Endpoint::natDetectType |
( |
void |
| ) |
|
throw | ( | Error |
| ) | | |
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.
◆ 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.
◆ natUpdateStunServers()
void pj::Endpoint::natUpdateStunServers |
( |
const StringVector & |
prmServers, |
|
|
bool |
prmWait |
|
) |
| |
throw | ( | Error |
| ) | | |
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. |
◆ natCheckStunServers()
void pj::Endpoint::natCheckStunServers |
( |
const StringVector & |
prmServers, |
|
|
bool |
prmWait, |
|
|
Token |
prmUserData |
|
) |
| |
throw | ( | Error |
| ) | | |
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.
- 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. |
- See also
- natCancelCheckStunServers()
◆ natCancelCheckStunServers()
void pj::Endpoint::natCancelCheckStunServers |
( |
Token |
token, |
|
|
bool |
notify_cb = false |
|
) |
| |
throw | ( | Error |
| ) | | |
Cancel pending STUN resolution which match the specified token.
- 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. |
Exception: PJ_ENOTFOUND if there is no matching one, or other error.
◆ transportCreate()
Create and start a new SIP transport according to the specified settings.
- Parameters
-
type | Transport type. |
cfg | Transport configuration. |
- Returns
- The transport ID.
◆ transportEnum()
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.
◆ transportGetInfo()
Get information about transport.
- Parameters
-
- Returns
- Transport info.
◆ transportSetEnable()
void pj::Endpoint::transportSetEnable |
( |
TransportId |
id, |
|
|
bool |
enabled |
|
) |
| |
throw | ( | Error |
| ) | | |
Disable a transport or re-enable it. By default transport is always enabled after it is created. Disabling a transport does not necessarily close the socket, it will only discard incoming messages and prevent the transport from being used to send outgoing messages.
- Parameters
-
id | Transport ID. |
enabled | Enable or disable the transport. |
◆ transportClose()
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
-
◆ transportShutdown()
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
-
◆ hangupAllCalls()
void pj::Endpoint::hangupAllCalls |
( |
void |
| ) |
|
Terminate all calls. This will initiate call hangup for all currently active calls.
◆ mediaAdd()
Add media to the media list.
- Parameters
-
◆ mediaRemove()
void pj::Endpoint::mediaRemove |
( |
AudioMedia & |
media | ) |
|
Remove media from the media list.
- Parameters
-
media | media to be removed. |
◆ mediaExists()
bool pj::Endpoint::mediaExists |
( |
const AudioMedia & |
media | ) |
const |
Check if media has been added to the media list.
- Parameters
-
- Returns
- True if media has been added, false otherwise.
◆ mediaMaxPorts()
unsigned pj::Endpoint::mediaMaxPorts |
( |
| ) |
const |
Get maximum number of media port.
- Returns
- Maximum number of media port in the conference bridge.
◆ mediaActivePorts()
unsigned pj::Endpoint::mediaActivePorts |
( |
| ) |
const |
Get current number of active media port in the bridge.
- Returns
- The number of active media port.
◆ mediaEnumPorts()
Warning: deprecated, use mediaEnumPorts2() instead. This function is not safe in multithreaded environment.
Enumerate all media port.
- Returns
- The list of media port.
◆ mediaEnumPorts2()
Enumerate all audio media port.
- Returns
- The list of audio media port.
◆ mediaEnumVidPorts()
Enumerate all video media port.
- Returns
- The list of video media port.
◆ audDevManager()
Get the instance of Audio Device Manager.
- Returns
- The Audio Device Manager.
◆ vidDevManager()
Get the instance of Video Device Manager.
- Returns
- The Video Device Manager.
◆ 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.
◆ codecEnum2()
Enum all supported codecs in the system.
- Returns
- Array of codec info.
◆ codecSetPriority()
void pj::Endpoint::codecSetPriority |
( |
const string & |
codec_id, |
|
|
pj_uint8_t |
priority |
|
) |
| |
throw | ( | Error |
| ) | | |
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. |
◆ codecGetParam()
CodecParam pj::Endpoint::codecGetParam |
( |
const string & |
codec_id | ) |
const |
throw | ( | Error |
| ) | | |
Get codec parameters.
- Parameters
-
- Returns
- Codec parameters. If codec is not found, Error will be thrown.
◆ codecSetParam()
void pj::Endpoint::codecSetParam |
( |
const string & |
codec_id, |
|
|
const CodecParam |
param |
|
) |
| |
throw | ( | Error |
| ) | | |
Set codec parameters.
- Parameters
-
codec_id | Codec ID. |
param | Codec parameter to set. Set to NULL to reset codec parameter to library default settings. |
◆ 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.
◆ videoCodecEnum2()
Enum all supported video codecs in the system.
- Returns
- Array of video codec info.
◆ videoCodecSetPriority()
void pj::Endpoint::videoCodecSetPriority |
( |
const string & |
codec_id, |
|
|
pj_uint8_t |
priority |
|
) |
| |
throw | ( | Error |
| ) | | |
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. |
◆ getVideoCodecParam()
VidCodecParam pj::Endpoint::getVideoCodecParam |
( |
const string & |
codec_id | ) |
const |
throw | ( | Error |
| ) | | |
Get video codec parameters.
- Parameters
-
- Returns
- Codec parameters. If codec is not found, Error will be thrown.
◆ setVideoCodecParam()
void pj::Endpoint::setVideoCodecParam |
( |
const string & |
codec_id, |
|
|
const VidCodecParam & |
param |
|
) |
| |
throw | ( | Error |
| ) | | |
Set video codec parameters.
- Parameters
-
codec_id | Codec ID. |
param | Codec parameter to set. |
◆ resetVideoCodecParam()
void pj::Endpoint::resetVideoCodecParam |
( |
const string & |
codec_id | ) |
|
throw | ( | Error |
| ) | | |
Reset video codec parameters to library default settings.
- Parameters
-
◆ srtpCryptoEnum()
Enumerate all SRTP crypto-suite names.
- Returns
- The list of SRTP crypto-suite name.
◆ handleIpChange()
Inform the stack that IP address change event was detected. The stack will:
- Restart the listener (this step is configurable via IpChangeParam.restartListener).
- Shutdown the transport used by account registration (this step is configurable via AccountConfig.ipChangeConfig.shutdownTp).
- Update contact URI by sending re-Registration (this step is configurable via a\ AccountConfig.natConfig.contactRewriteUse and a\ AccountConfig.natConfig.contactRewriteMethod)
- 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
-
◆ onNatDetectionComplete()
Callback when the Endpoint has finished performing NAT type detection that is initiated with natDetectType().
- Parameters
-
prm | Callback parameters containing the detection result. |
References PJ_UNUSED_ARG.
◆ onNatCheckStunServersComplete()
◆ onTransportState()
This callback is called when transport state has changed.
- Parameters
-
References PJ_UNUSED_ARG.
◆ onTimer()
virtual void pj::Endpoint::onTimer |
( |
const OnTimerParam & |
prm | ) |
|
|
inlinevirtual |
◆ onSelectAccount()
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
-
References PJ_UNUSED_ARG.
◆ onIpChangeProgress()
Calling handleIpChange() may involve different operation. This callback is called to report the progress of each enabled operation.
- Parameters
-
References PJ_UNUSED_ARG.
◆ onMediaEvent()
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
-
References PJ_UNUSED_ARG.
◆ onCredAuth()
Callback for computation of the digest credential.
Usually, an application does not need to implement (overload) this callback. Use it, if your application needs to support Digest AKA authentication without the default digest computation back-end (i.e: 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:
- If PJSIP_HAS_DIGEST_AKA_AUTH is disabled, you have to overload this callback to provide your own digest computation back-end.
- If PJSIP_HAS_DIGEST_AKA_AUTH is enabled, libmilenage library from third_party directory is linked, and this callback returns PJ_ENOTSUP, then the default digest computation back-end is used.
- Parameters
-
prm.digestChallenge | The authentication challenge sent by server in 401 or 401 response, as either Proxy-Authenticate or WWW-Authenticate header. |
prm.credentialInfo | The credential to be used. |
method | The request method. |
prm.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 have been set by caller. Upon return, the response field will be initialized by this function. |
- Returns
- PJ_ENOTSUP is the default. If you overload this callback, return PJ_SUCCESS on success.
The documentation for this class was generated from the following file:
PJSIP Open Source, high performance, small footprint, and very very portable SIP stack
Copyright (C) 2006-2008 Teluu Inc.
|