Liblinphone  3.11.1
Typedefs | Enumerations | Functions
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

LinphoneEventlinphone_core_subscribe (LinphoneCore *lc, const LinphoneAddress *resource, const char *event, int expires, const LinphoneContent *body)
 
LinphoneEventlinphone_core_create_subscribe (LinphoneCore *lc, const LinphoneAddress *resource, const char *event, int expires)
 
LinphoneEventlinphone_core_create_notify (LinphoneCore *lc, const LinphoneAddress *resource, const char *event)
 
LinphoneEventlinphone_core_publish (LinphoneCore *lc, const LinphoneAddress *resource, const char *event, int expires, const LinphoneContent *body)
 
LinphoneEventlinphone_core_create_publish (LinphoneCore *lc, const LinphoneAddress *resource, const char *event, int expires)
 
LinphoneEventlinphone_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 LinphoneErrorInfolinphone_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)
 
LinphoneEventlinphone_event_ref (LinphoneEvent *lev)
 
void linphone_event_unref (LinphoneEvent *lev)
 
const char * linphone_event_get_name (const LinphoneEvent *lev)
 
const LinphoneAddresslinphone_event_get_from (const LinphoneEvent *lev)
 
const LinphoneAddresslinphone_event_get_resource (const LinphoneEvent *lev)
 
LinphoneCorelinphone_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

§ LinphoneCorePublishStateChangedCb

Old name of LinphoneCoreCbsPublishStateChangedCb.

§ LinphoneCoreSubscriptionStateChangedCb

§ LinphoneEvent

typedef struct _LinphoneEvent LinphoneEvent

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

See also
linphone_core_publish()
linphone_core_subscribe()

§ LinphonePublishState

Enum for publish states.

§ LinphoneSubscriptionDir

Enum for subscription direction (incoming or outgoing).

§ LinphoneSubscriptionState

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

Enumeration Type Documentation

§ _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 for subscription direction (incoming or outgoing).

Enumerator
LinphoneSubscriptionIncoming 

Incoming subscription.

LinphoneSubscriptionOutgoing 

Outgoing subscription.

LinphoneSubscriptionInvalidDir 

Invalid subscription direction.

§ _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
lcthe LinphoneCore
resourcethe destination resource
eventthe 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
lcthe LinphoneCore
resourcethe resource uri for the event
eventthe 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
lcthe LinphoneCore
resourcethe resource uri for the event
eventthe event name
expiresthe 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
lcthe LinphoneCore
resourcethe destination resource
eventthe event name
expiresthe 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
lcthe LinphoneCore
resourcethe resource uri for the event
eventthe event name
expiresthe lifetime of event being published, -1 if no associated duration, in which case it will not be refreshed.
bodythe 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
lcthe LinphoneCore
resourcethe destination resource
eventthe event name
expiresthe whished duration of the subscription
bodyan 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
evthe LinphoneEvent
nameheader's name
valuethe 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
evthe LinphoneEvent
nameheader'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
leva LinphoneEvent corresponding to an incoming subscription previously received and accepted.
bodyan 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]levLinphoneEvent 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
levLinphoneEvent 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
levLinphoneEvent 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
levthe LinphoneEvent
bodythe 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
evthe LinphoneEvent
bodyoptional 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
levthe LinphoneEvent
bodythe 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
leva LinphoneEvent
bodyan optional body to include in the subscription update, may be NULL.