liblinphone 3.9.1

- Main Page
- Related Pages
- Modules
- Data Structures

Typedefs | Enumerations | Functions
Managing generic subscriptions and publishes

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

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

## 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)
int | linphone_event_send_subscribe (LinphoneEvent *ev, const LinphoneContent *body)
int | linphone_event_update_subscribe (LinphoneEvent *lev, const LinphoneContent *body)
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)
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)
int | linphone_event_send_publish (LinphoneEvent *lev, const LinphoneContent *body)
int | linphone_event_update_publish (LinphoneEvent *lev, const LinphoneContent *body)
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

typedef struct _LinphoneEvent LinphoneEvent

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

See also
  linphone_core_publish()
  linphone_core_subscribe()

typedef enum _LinphoneSubscriptionDir LinphoneSubscriptionDir

Typedef alias for _LinphoneSubscriptionDir

typedef enum _LinphoneSubscriptionState LinphoneSubscriptionState

Typedef for subscription state enum.

typedef enum _LinphonePublishState LinphonePublishState

Typedef for publish state enum

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

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

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

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

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

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

## Enumeration Type Documentation

enum _LinphoneSubscriptionDir

Enum for subscription direction (incoming or outgoing).

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

enum _LinphoneSubscriptionState

Enum for subscription 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 encountered 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.

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

## Function Documentation

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.

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.

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.

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

Update (refresh) an outgoing subscription.

Parameters

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

int linphone_event_accept_subscription | ( | LinphoneEvent * | lev | ) |

Accept an incoming subcription.

int linphone_event_deny_subscription | ( | LinphoneEvent * | lev,
|  | LinphoneReason | reason
| ) |  |

Deny an incoming subscription with given reason.

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.

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.

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.

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

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

LinphoneReason linphone_event_get_reason | ( | const LinphoneEvent * | lev | ) |

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

const LinphoneErrorInfo* linphone_event_get_error_info | ( | const LinphoneEvent * | lev | ) |

Get full details about an error occured.

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.

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.

LinphoneSubscriptionDir linphone_event_get_subscription_dir | ( | LinphoneEvent * | lev | ) |

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

void linphone_event_set_user_data | ( | LinphoneEvent * | ev,
|  | void * | up
| ) |  |

Set a user (application) pointer.

void* linphone_event_get_user_data | ( | const LinphoneEvent * | ev | ) |

Retrieve user pointer.

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.

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.

void linphone_event_terminate | ( | LinphoneEvent * | lev | ) |

Terminate an incoming or outgoing subscription that was previously acccepted, or a previous publication. This function does not unref the object. The core will unref() if it does not need this object anymore.

For subscribed event, when the subscription is terminated normally or because of an error, the core will unref. For published events, no unref is performed. This is because it is allowed to re-publish an expired publish, as well as retry it in case of error.

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.

void linphone_event_unref | ( | LinphoneEvent * | lev | ) |

Decrease reference count.

See also
  linphone_event_ref()

const char* linphone_event_get_name | ( | const LinphoneEvent * | lev | ) |

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

const LinphoneAddress* linphone_event_get_from | ( | const LinphoneEvent * | lev | ) |

Get the "from" address of the subscription.

const LinphoneAddress* linphone_event_get_resource | ( | const LinphoneEvent * | lev | ) |

Get the resource address of the subscription or publish.

LinphoneCore* linphone_event_get_core | ( | const LinphoneEvent * | lev | ) |

Returns back pointer to the LinphoneCore that created this LinphoneEvent