4.端点ENDPOINT

公共功能(函数)

Endpoint() 　　　//默认构造函数 

virtual ~Endpoint()//虚析构函数

Version libVersion() const//得到库的版本

void libCreate()　　//实例化pjsua应用程序。调用任何其他函数之前，应用程序必须调用此函数，以确保底层库被正确初始化。一旦此函数返回成功，应用程序必须在退出前调用libDestroy（）。

pjsua_state libGetState() const //获取库状态。返回 库状态 

void libInit(const EpConfig &prmEpConfig) //使用指定的设置初始化pjsua。所有设置都是可选的，并且在未指定配置时将使用默认值。请注意，在调用此函数之前必须调用create（）。 

　　参数  prmEpConfig -端点配置

void libStart() // 在所有的初始化完成后，调用该函数，以便可以做其他检查设置。应用程序可以在init（）之后的任何时间调用此函数。

void libRegisterThread(const string &name)//将由外部或自身API创建的线程注册到库。请注意，每次调用此函数时，它将分配一些内存来存储线程描述，这只会在库被销毁时被释放。 

　　参数name 要分配给线程的可选名称

bool libIsThreadRegistered()//检查该线程是否已经被注册到库中。需要注意的是此功能只适用于使用libRegisterThread（）注册的库的主线程与工作线程和外部/自身线程。

void libStopWorkerThreads()//停止所有工作线程

int libHandleEvents(unsigned msec_timeout)//对pjsua进行事件轮询，如果需要，可以阻塞调用者线程指定的最大间隔（以毫秒为单位）。如果它在pjsua_config结构里配置了工作线程（thread_cnt域），应用程序通常不需要调用这个函数，因为轮询将由这些工作线程来完成。如果EpConfig :: UaConfig :: mainThreadOnly启用，并从主线程调用此函数（默认情况下，主线程是调用libCreate（）的线程），此功能也将扫描并在列表中运行任何挂起的作业。

 　　返回　　投票期间处理的事件数。负值表示错误，应用程序可以以（status = -return_value）方式检索错误。

　　参数  msec_timeout - 最长时间等待，以毫秒为单位。 

void libDestroy(unsigned prmFlags = 0) //销毁pjsua. 建议使用应用程序在调用此功能之前执行正常shutdown（例如从SIP服务器注销帐户，终止预订订阅和挂断主动调用）.但是如果发现有活动会话，此函数将执行所有这些操作以终止活动会话。此功能将等待（block）几秒钟等待远程的回复。如果没有跟踪它的状态，Application.可以多次安全地调用此函数。 

　　参数  prmFlags，  pjsua_destroy_flag 枚举值的组合

string utilStrError(pj_status_t prmErr) 检索指定状态代码的错误字符串。

参数 prmErr -错误代码。 

void utilLogWrite(int prmLevel, const string &prmSender, const string &prmMsg)写一个日志消息

参数 prmLevel -日志详细程度（1-5）

prmSender -日志发送方。

prmMsg -日志消息。

void utilLogWrite(LogEntry &e)

Write a log entry.

 

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.

 

Return

PJ_SUCCESS on success, or the appropriate error code.

See

utilVerifyUri()

Parameters

• prmUri -

  The URL string.

 

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.

 

Return

PJ_SUCCESS on success, or the appropriate error code.

See

pjsua_verify_sip_url()

Parameters

• prmUri -

  The URL string.

 

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.

 

Return

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

Parameters

• prmMsecDelay -

  The time interval in msec.

• prmUserData -

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

 

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, TokenprmUserData)

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

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.

 

Return

The transport ID.

Parameters

• type -

  Transport type.

• cfg -

  Transport configuration.

 

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

 

Return

Array of transport IDs.

 

TransportInfo transportGetInfo(TransportId id)

Get information about transport.

 

Return

Transport info.

Parameters

• id -

  Transport ID.

 

void transportSetEnable(TransportId id, bool enabled)

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.

 

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.

 

Return

True if media has been added, false otherwise.

Parameters

• media -

  media to be check.

 

unsigned mediaMaxPorts() const

Get maximum number of media port.

 

Return

Maximum number of media port in the conference bridge.

 

unsigned mediaActivePorts() const

Get current number of active media port in the bridge.

 

Return

The number of active media port.

 

const AudioMediaVector &mediaEnumPorts() const

Enumerate all media port.

 

Return

The list of media port.

 

AudDevManager &audDevManager()

Get the instance of Audio Device Manager.

 

Return

The Audio Device Manager.

 

VidDevManager &vidDevManager()

Get the instance of Video Device Manager.

 

Return

The Video Device Manager.

 

const CodecInfoVector &codecEnum()

Enum all supported codecs in the system.

 

Return

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.

 

Return

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

Parameters

• codec_id -

  Codec ID.

 

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

Enum all supported video codecs in the system.

 

Return

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.

 

Return

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

Parameters

• codec_id -

  Codec ID.

 

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.

 

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.

 

virtual void onNatCheckStunServersComplete(constOnNatCheckStunServersCompleteParam &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.

 

virtual void onTransportState(const OnTransportStateParam &prm)

This callback is called when transport state has changed.

 

Parameters

• prm -

  Callback parameters.

 

virtual void onTimer(const OnTimerParam &prm)

Callback when a timer has fired.

The timer was scheduled by utilTimerSchedule().

 

Parameters

• prm -

  Callback parameters.

 

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.

 

Public Static Functions

static Endpoint &instance()

Retrieve the singleton instance of the endpoint.