Managing generic subscriptions and publishes

Typedefs
typedef void(*	LinphoneCoreCbsNotifyReceivedCb) (LinphoneCore *lc, LinphoneEvent *lev, const char *notified_event, const LinphoneContent *body)
typedef LinphoneCoreCbsNotifyReceivedCb	LinphoneCoreNotifyReceivedCb
typedef void(*	LinphoneCoreCbsSubscriptionStateChangedCb) (LinphoneCore *lc, LinphoneEvent *lev, LinphoneSubscriptionState state)
typedef LinphoneCoreCbsSubscriptionStateChangedCb	LinphoneCoreSubscriptionStateChangedCb
typedef void(*	LinphoneCoreCbsPublishStateChangedCb) (LinphoneCore *lc, LinphoneEvent *lev, LinphonePublishState state)
typedef LinphoneCoreCbsPublishStateChangedCb	LinphoneCorePublishStateChangedCb
typedef struct _LinphoneEvent	LinphoneEvent
typedef enum _LinphonePublishState	LinphonePublishState
typedef enum _LinphoneSubscriptionDir	LinphoneSubscriptionDir
typedef enum _LinphoneSubscriptionState	LinphoneSubscriptionState

Enumerations
enum	_LinphonePublishState {   LinphonePublishNone,   LinphonePublishProgress,   LinphonePublishOk,   LinphonePublishError,   LinphonePublishExpiring,   LinphonePublishCleared }
enum	_LinphoneSubscriptionDir {   LinphoneSubscriptionIncoming,   LinphoneSubscriptionOutgoing,   LinphoneSubscriptionInvalidDir }
enum	_LinphoneSubscriptionState {   LinphoneSubscriptionNone,   LinphoneSubscriptionOutgoingProgress,   LinphoneSubscriptionIncomingReceived,   LinphoneSubscriptionPending,   LinphoneSubscriptionActive,   LinphoneSubscriptionTerminated,   LinphoneSubscriptionError,   LinphoneSubscriptionExpiring }

Functions
LinphoneEvent *	linphone_core_subscribe (LinphoneCore *lc, const LinphoneAddress *resource, const char *event, int expires, const LinphoneContent *body)
LinphoneEvent *	linphone_core_create_subscribe (LinphoneCore *lc, const LinphoneAddress *resource, const char *event, int expires)
LinphoneEvent *	linphone_core_create_notify (LinphoneCore *lc, const LinphoneAddress *resource, const char *event)
LinphoneEvent *	linphone_core_publish (LinphoneCore *lc, const LinphoneAddress *resource, const char *event, int expires, const LinphoneContent *body)
LinphoneEvent *	linphone_core_create_publish (LinphoneCore *lc, const LinphoneAddress *resource, const char *event, int expires)
LinphoneEvent *	linphone_core_create_one_shot_publish (LinphoneCore *lc, const LinphoneAddress *resource, const char *event)
int	linphone_event_send_subscribe (LinphoneEvent *ev, const LinphoneContent *body)
int	linphone_event_update_subscribe (LinphoneEvent *lev, const LinphoneContent *body)
int	linphone_event_refresh_subscribe (LinphoneEvent *lev)
int	linphone_event_accept_subscription (LinphoneEvent *lev)
int	linphone_event_deny_subscription (LinphoneEvent *lev, LinphoneReason reason)
int	linphone_event_notify (LinphoneEvent *lev, const LinphoneContent *body)
int	linphone_event_send_publish (LinphoneEvent *lev, const LinphoneContent *body)
int	linphone_event_update_publish (LinphoneEvent *lev, const LinphoneContent *body)
int	linphone_event_refresh_publish (LinphoneEvent *lev)
void	linphone_event_pause_publish (LinphoneEvent *lev)
LinphoneReason	linphone_event_get_reason (const LinphoneEvent *lev)
const LinphoneErrorInfo *	linphone_event_get_error_info (const LinphoneEvent *lev)
LinphoneSubscriptionState	linphone_event_get_subscription_state (const LinphoneEvent *lev)
LinphonePublishState	linphone_event_get_publish_state (const LinphoneEvent *lev)
LinphoneSubscriptionDir	linphone_event_get_subscription_dir (LinphoneEvent *lev)
void	linphone_event_set_user_data (LinphoneEvent *ev, void *up)
void *	linphone_event_get_user_data (const LinphoneEvent *ev)
void	linphone_event_add_custom_header (LinphoneEvent *ev, const char *name, const char *value)
const char *	linphone_event_get_custom_header (LinphoneEvent *ev, const char *name)
void	linphone_event_terminate (LinphoneEvent *lev)
LinphoneEvent *	linphone_event_ref (LinphoneEvent *lev)
void	linphone_event_unref (LinphoneEvent *lev)
const char *	linphone_event_get_name (const LinphoneEvent *lev)
const LinphoneAddress *	linphone_event_get_from (const LinphoneEvent *lev)
const LinphoneAddress *	linphone_event_get_resource (const LinphoneEvent *lev)
LinphoneCore *	linphone_event_get_core (const LinphoneEvent *lev)

Detailed Description

The LinphoneEvent api allows application to control subscriptions, receive notifications and make publish to peers, in a generic manner.

Typedef Documentation

LinphoneCoreCbsNotifyReceivedCb

typedef void(* LinphoneCoreCbsNotifyReceivedCb) (LinphoneCore *lc, LinphoneEvent *lev, const char *notified_event, const LinphoneContent *body)

Callback prototype for notifying the application about notification received from the network.

LinphoneCoreCbsPublishStateChangedCb

typedef void(* LinphoneCoreCbsPublishStateChangedCb) (LinphoneCore *lc, LinphoneEvent *lev, LinphonePublishState state)

Callback prototype for notifying the application about changes of publish states.

LinphoneCoreCbsSubscriptionStateChangedCb

typedef void(* LinphoneCoreCbsSubscriptionStateChangedCb) (LinphoneCore *lc, LinphoneEvent *lev, LinphoneSubscriptionState state)

Callback prototype for notifying the application about changes of subscription states, including arrival of new subscriptions.

LinphoneCoreNotifyReceivedCb

typedef LinphoneCoreCbsNotifyReceivedCb LinphoneCoreNotifyReceivedCb

Old name of LinphoneCoreCbsNotifyReceivedCb.

LinphoneCorePublishStateChangedCb

typedef LinphoneCoreCbsPublishStateChangedCb LinphoneCorePublishStateChangedCb

Old name of LinphoneCoreCbsPublishStateChangedCb.

LinphoneCoreSubscriptionStateChangedCb

typedef LinphoneCoreCbsSubscriptionStateChangedCb LinphoneCoreSubscriptionStateChangedCb

Old name of LinphoneCoreCbsSubscriptionStateChangedCb.

LinphoneEvent

typedef struct _LinphoneEvent LinphoneEvent

Object representing an event state, which is subcribed or published.

See also

linphone_core_publish()

linphone_core_subscribe()

LinphonePublishState

typedef enum _LinphonePublishState LinphonePublishState

Enum for publish states.

LinphoneSubscriptionDir

typedef enum _LinphoneSubscriptionDir LinphoneSubscriptionDir

Enum for subscription direction (incoming or outgoing).

LinphoneSubscriptionState

typedef enum _LinphoneSubscriptionState LinphoneSubscriptionState

Enum for subscription states. LinphoneSubscriptionTerminated and LinphoneSubscriptionError are final states.

Enumeration Type Documentation

_LinphonePublishState

enum _LinphonePublishState

Enum for publish states.

Enumerator
LinphonePublishNone	Initial state, do not use
LinphonePublishProgress	An outgoing publish was created and submitted
LinphonePublishOk	Publish is accepted
LinphonePublishError	Publish encoutered an error, linphone_event_get_reason() gives reason code
LinphonePublishExpiring	Publish is about to expire, only sent if [sip]->refresh_generic_publish property is set to 0
LinphonePublishCleared	Event has been un published

_LinphoneSubscriptionDir

enum _LinphoneSubscriptionDir

Enum for subscription direction (incoming or outgoing).

Enumerator
LinphoneSubscriptionIncoming	Incoming subscription.
LinphoneSubscriptionOutgoing	Outgoing subscription.
LinphoneSubscriptionInvalidDir	Invalid subscription direction.

_LinphoneSubscriptionState

enum _LinphoneSubscriptionState

Enum for subscription states. LinphoneSubscriptionTerminated and LinphoneSubscriptionError are final states.

Enumerator
LinphoneSubscriptionNone	Initial state, should not be used
LinphoneSubscriptionOutgoingProgress	An outgoing subcription was sent
LinphoneSubscriptionIncomingReceived	An incoming subcription is received
LinphoneSubscriptionPending	Subscription is pending, waiting for user approval
LinphoneSubscriptionActive	Subscription is accepted
LinphoneSubscriptionTerminated	Subscription is terminated normally
LinphoneSubscriptionError	Subscription was terminated by an error, indicated by linphone_event_get_reason()
LinphoneSubscriptionExpiring	Subscription is about to expire, only sent if [sip]->refresh_generic_subscribe property is set to 0

Function Documentation

linphone_core_create_notify()

LinphoneEvent* linphone_core_create_notify	(	LinphoneCore *	lc,
		const LinphoneAddress *	resource,
		const char *	event
	)

Create an out-of-dialog notification, specifying the destination resource, the event name. The notification can be send with linphone_event_notify().

Parameters

lc	the LinphoneCore
resource	the destination resource
event	the event name

Returns

a LinphoneEvent holding the context of the notification.

linphone_core_create_one_shot_publish()

LinphoneEvent* linphone_core_create_one_shot_publish	(	LinphoneCore *	lc,
		const LinphoneAddress *	resource,
		const char *	event
	)

Create a publish context for a one-shot publish. After being created, the publish must be sent using linphone_event_send_publish(). The LinphoneEvent is automatically terminated when the publish transaction is finished, either with success or failure. The application must not call linphone_event_terminate() for such one-shot publish.

Parameters

lc	the LinphoneCore
resource	the resource uri for the event
event	the event name

Returns

the LinphoneEvent holding the context of the publish.

linphone_core_create_publish()

LinphoneEvent* linphone_core_create_publish	(	LinphoneCore *	lc,
		const LinphoneAddress *	resource,
		const char *	event,
		int	expires
	)

Create a publish context for an event state. After being created, the publish must be sent using linphone_event_send_publish(). After expiry, the publication is refreshed unless it is terminated before.

Parameters

lc	the LinphoneCore
resource	the resource uri for the event
event	the event name
expires	the lifetime of event being published, -1 if no associated duration, in which case it will not be refreshed.

Returns

the LinphoneEvent holding the context of the publish.

linphone_core_create_subscribe()

LinphoneEvent* linphone_core_create_subscribe	(	LinphoneCore *	lc,
		const LinphoneAddress *	resource,
		const char *	event,
		int	expires
	)

Create an outgoing subscription, specifying the destination resource, the event name, and an optional content body. If accepted, the subscription runs for a finite period, but is automatically renewed if not terminated before. Unlike linphone_core_subscribe() the subscription isn't sent immediately. It will be send when calling linphone_event_send_subscribe().

Parameters

lc	the LinphoneCore
resource	the destination resource
event	the event name
expires	the whished duration of the subscription

Returns

a LinphoneEvent holding the context of the created subcription.

linphone_core_publish()

LinphoneEvent* linphone_core_publish	(	LinphoneCore *	lc,
		const LinphoneAddress *	resource,
		const char *	event,
		int	expires,
		const LinphoneContent *	body
	)

Publish an event state. This first create a LinphoneEvent with linphone_core_create_publish() and calls linphone_event_send_publish() to actually send it. After expiry, the publication is refreshed unless it is terminated before.

Parameters

lc	the LinphoneCore
resource	the resource uri for the event
event	the event name
expires	the lifetime of event being published, -1 if no associated duration, in which case it will not be refreshed.
body	the actual published data

Returns

the LinphoneEvent holding the context of the publish.

linphone_core_subscribe()

LinphoneEvent* linphone_core_subscribe	(	LinphoneCore *	lc,
		const LinphoneAddress *	resource,
		const char *	event,
		int	expires,
		const LinphoneContent *	body
	)

Create an outgoing subscription, specifying the destination resource, the event name, and an optional content body. If accepted, the subscription runs for a finite period, but is automatically renewed if not terminated before.

Parameters

lc	the LinphoneCore
resource	the destination resource
event	the event name
expires	the whished duration of the subscription
body	an optional body, may be NULL.

Returns

a LinphoneEvent holding the context of the created subcription.

linphone_event_accept_subscription()

int linphone_event_accept_subscription

(

LinphoneEvent *

lev

)

Accept an incoming subcription.

linphone_event_add_custom_header()

void linphone_event_add_custom_header	(	LinphoneEvent *	ev,
		const char *	name,
		const char *	value
	)

Add a custom header to an outgoing susbscription or publish.

Parameters

ev	the LinphoneEvent
name	header's name
value	the header's value.

linphone_event_deny_subscription()

int linphone_event_deny_subscription	(	LinphoneEvent *	lev,
		LinphoneReason	reason
	)

Deny an incoming subscription with given reason.

linphone_event_get_core()

LinphoneCore* linphone_event_get_core

(

const LinphoneEvent *

lev

)

Returns back pointer to the LinphoneCore that created this LinphoneEvent

linphone_event_get_custom_header()

const char* linphone_event_get_custom_header	(	LinphoneEvent *	ev,
		const char *	name
	)

Obtain the value of a given header for an incoming subscription.

Parameters

ev	the LinphoneEvent
name	header's name

Returns

the header's value or NULL if such header doesn't exist.

linphone_event_get_error_info()

const LinphoneErrorInfo* linphone_event_get_error_info

(

const LinphoneEvent *

lev

)

Get full details about an error occured.

linphone_event_get_from()

const LinphoneAddress* linphone_event_get_from

(

const LinphoneEvent *

lev

)

Get the "from" address of the subscription.

linphone_event_get_name()

const char* linphone_event_get_name

(

const LinphoneEvent *

lev

)

Get the name of the event as specified in the event package RFC.

linphone_event_get_publish_state()

LinphonePublishState linphone_event_get_publish_state

(

const LinphoneEvent *

lev

)

Get publish state. If the event object was not created by a publish mechanism, LinphonePublishNone is returned.

linphone_event_get_reason()

LinphoneReason linphone_event_get_reason

(

const LinphoneEvent *

lev

)

Return reason code (in case of error state reached).

linphone_event_get_resource()

const LinphoneAddress* linphone_event_get_resource

(

const LinphoneEvent *

lev

)

Get the resource address of the subscription or publish.

linphone_event_get_subscription_dir()

LinphoneSubscriptionDir linphone_event_get_subscription_dir

(

LinphoneEvent *

lev

)

Get subscription direction. If the object wasn't created by a subscription mechanism, LinphoneSubscriptionInvalidDir is returned.

linphone_event_get_subscription_state()

LinphoneSubscriptionState linphone_event_get_subscription_state

(

const LinphoneEvent *

lev

)

Get subscription state. If the event object was not created by a subscription mechanism, LinphoneSubscriptionNone is returned.

linphone_event_get_user_data()

void* linphone_event_get_user_data

(

const LinphoneEvent *

ev

)

Retrieve user pointer.

linphone_event_notify()

int linphone_event_notify	(	LinphoneEvent *	lev,
		const LinphoneContent *	body
	)

Send a notification.

Parameters

lev	a LinphoneEvent corresponding to an incoming subscription previously received and accepted.
body	an optional body containing the actual notification data.

Returns

0 if successful, -1 otherwise.

linphone_event_pause_publish()

void linphone_event_pause_publish

(

LinphoneEvent *

lev

)

Prevent an event from refreshing its publish. This is useful to let registrations to expire naturally (or) when the application wants to keep control on when refreshes are sent. The refreshing operations can be resumed with linphone_proxy_config_refresh_register().

Parameters

[in]

lev

LinphoneEvent object.

linphone_event_ref()

LinphoneEvent* linphone_event_ref

(

LinphoneEvent *

lev

)

Increase reference count of LinphoneEvent. By default LinphoneEvents created by the core are owned by the core only. An application that wishes to retain a reference to it must call linphone_event_ref(). When this reference is no longer needed, linphone_event_unref() must be called.

linphone_event_refresh_publish()

int linphone_event_refresh_publish

(

LinphoneEvent *

lev

)

Refresh an outgoing publish keeping the same body.

Parameters

lev	LinphoneEvent object.

Returns

0 if successful, -1 otherwise.

linphone_event_refresh_subscribe()

int linphone_event_refresh_subscribe

(

LinphoneEvent *

lev

)

Refresh an outgoing subscription keeping the same body.

Parameters

lev	LinphoneEvent object.

Returns

0 if successful, -1 otherwise.

linphone_event_send_publish()

int linphone_event_send_publish	(	LinphoneEvent *	lev,
		const LinphoneContent *	body
	)

Send a publish created by linphone_core_create_publish().

Parameters

lev	the LinphoneEvent
body	the new data to be published

linphone_event_send_subscribe()

int linphone_event_send_subscribe	(	LinphoneEvent *	ev,
		const LinphoneContent *	body
	)

Send a subscription previously created by linphone_core_create_subscribe().

Parameters

ev	the LinphoneEvent
body	optional content to attach with the subscription.

Returns

0 if successful, -1 otherwise.

linphone_event_set_user_data()

void linphone_event_set_user_data	(	LinphoneEvent *	ev,
		void *	up
	)

Set a user (application) pointer.

linphone_event_terminate()

void linphone_event_terminate

(

LinphoneEvent *

lev

)

Terminate an incoming or outgoing subscription that was previously acccepted, or a previous publication. The LinphoneEvent shall not be used anymore after this operation, unless the application explicitely took a reference on the object with linphone_event_ref().

linphone_event_unref()

void linphone_event_unref

(

LinphoneEvent *

lev

)

Decrease reference count.

See also

linphone_event_ref()

linphone_event_update_publish()

int linphone_event_update_publish	(	LinphoneEvent *	lev,
		const LinphoneContent *	body
	)

Update (refresh) a publish.

Parameters

lev	the LinphoneEvent
body	the new data to be published

linphone_event_update_subscribe()

int linphone_event_update_subscribe	(	LinphoneEvent *	lev,
		const LinphoneContent *	body
	)

Update (refresh) an outgoing subscription, changing the body.

Parameters

lev	a LinphoneEvent
body	an optional body to include in the subscription update, may be NULL.