Presence functions

Functions
(int)	- PortSIPSDK::setPresenceMode:
	Indicate that SDK uses the P2P mode for presence or presence agent mode. More...
(int)	- PortSIPSDK::setDefaultSubscriptionTime:
	Set the default expiration time to be used when creating a subscription. More...
(int)	- PortSIPSDK::setDefaultPublicationTime:
	Set the default expiration time to be used when creating a publication. More...
(long)	- PortSIPSDK::presenceSubscribe:subject:
	Send a SUBSCRIBE message for subscribing the contact's presence status. More...
(int)	- PortSIPSDK::presenceTerminateSubscribe:
	Terminate the given presence subscription. More...
(int)	- PortSIPSDK::presenceAcceptSubscribe:
	Accept the presence SUBSCRIBE request which is received from contact. More...
(int)	- PortSIPSDK::presenceRejectSubscribe:
	Reject a presence SUBSCRIBE request which is received from contact. More...
(int)	- PortSIPSDK::setPresenceStatus:statusText:
	Send a NOTIFY message to contact to notify that presence status is online/offline/changed. More...
(long)	- PortSIPSDK::sendSubscription:eventName:
	Send a SUBSCRIBE message to remote side. More...
(int)	- PortSIPSDK::terminateSubscription:
	Terminate the given subscription. More...

Detailed Description

Function Documentation

setPresenceMode:()

- (int) setPresenceMode:

(int)

mode

Indicate that SDK uses the P2P mode for presence or presence agent mode.

Parameters

mode	0 - P2P mode; 1 - Presence Agent mode, default is P2P mode.

Returns

If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.

Remarks

Since presence agent mode requires the PBX/Server support the PUBLISH, please ensure you have your server and PortSIP PBX support this feature. For more details please visit: https://www.portsip.com/portsip-pbx

setDefaultSubscriptionTime:()

- (int) setDefaultSubscriptionTime:

(int)

secs

Set the default expiration time to be used when creating a subscription.

Parameters

secs	The default expiration time of subscription.

Returns

If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.

setDefaultPublicationTime:()

- (int) setDefaultPublicationTime:

(int)

secs

Set the default expiration time to be used when creating a publication.

Parameters

secs	The default expiration time of publication.

Returns

If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.

presenceSubscribe:subject:()

- (long) presenceSubscribe:		(NSString *)	contact
subject:		(NSString *)	subject

Send a SUBSCRIBE message for subscribing the contact's presence status.

Parameters

contact	The target contact. It must be like sip:conta.nosp@m.ct00.nosp@m.1@sip.nosp@m..por.nosp@m.tsip..nosp@m.com.
subject	This subject text will be inserted into the SUBSCRIBE message. For example: "Hello, I'm Jason". The subject maybe in UTF-8 format. You should use UTF-8 to decode it.

Returns

If the function succeeds, it will return subscribeId. If the function fails, it will return a specific error code.

presenceTerminateSubscribe:()

- (int) presenceTerminateSubscribe:

(long)

subscribeId

Terminate the given presence subscription.

Parameters

subscribeId

The ID of the subscription.

Returns

If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.

presenceAcceptSubscribe:()

- (int) presenceAcceptSubscribe:

(long)

subscribeId

Accept the presence SUBSCRIBE request which is received from contact.

Parameters

subscribeId

Subscription ID. When receiving a SUBSCRIBE request from contact, the event onPresenceRecvSubscribe will be triggered. The event will include the subscription ID.

Returns

If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.

Remarks

If the P2P presence mode is enabled, when someone subscribes your presence status, you will receive the subscription request in the callback, and you can use this function to reject it.

presenceRejectSubscribe:()

- (int) presenceRejectSubscribe:

(long)

subscribeId

Reject a presence SUBSCRIBE request which is received from contact.

Parameters

subscribeId

Subscription ID. When receiving a SUBSCRIBE request from contact, the event onPresenceRecvSubscribe will be triggered. The event includes the subscription ID.

Returns

If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.

Remarks

If the P2P presence mode is enabled, when someone subscribe your presence status, you will receive the subscribe request in the callback, and you can use this function to accept it.

setPresenceStatus:statusText:()

- (int) setPresenceStatus:		(long)	subscribeId
statusText:		(NSString *)	statusText

Send a NOTIFY message to contact to notify that presence status is online/offline/changed.

Parameters

subscribeId	Subscription ID. When receiving a SUBSCRIBE request from contact, the event onPresenceRecvSubscribe that includes the Subscription ID will be triggered.
statusText	The state text of presence status. For example: "I'm here", offline must use "offline"

Returns

If the function succeeds, it will return value 0. If the function fails, it will return value a specific error code.

sendSubscription:eventName:()

- (long) sendSubscription:		(NSString *)	to
eventName:		(NSString *)	eventName

Send a SUBSCRIBE message to remote side.

Parameters

to	The subscribe user.
eventName	The event name to be subscribed.

Returns

If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.

Remarks

Example 1, to subscribe the MWI (Message Waiting notifications), You can use this code: long mwiSubId = sendSubscription("sip:101@test.com", "message-summary");

Example 2, to monitor a user/extension call status, You can use code: sendSubscription(mSipLib, "100", "dialog"); Extension 100 is the one to be monitored. Once being monitored, when extension 100 hold a call or is ringing, the onDialogStateUpdated callback will be triggered.

terminateSubscription:()

- (int) terminateSubscription:

(long)

subscribeId

Terminate the given subscription.

Parameters

subscribeId

The ID of the subscription.

Returns

If the function succeeds, it will return value 0. If the function fails, it will return a specific error code.

Remarks

For example, if you want stop check the MWI, use below code:

terminateSubscription(mwiSubId);