Group PJMEDIA_EVENT

group PJMEDIA_EVENT

PJMEDIA event framework.

Defines

PJMEDIA_EVENT_DATA_MAX_SIZE

Maximum size of additional parameters section in pjmedia_event structure

Typedefs

typedef pjmedia_event_dummy_data pjmedia_event_wnd_closed_data

Additional parameters for window changed event.

typedef pjmedia_event_dummy_data pjmedia_event_mouse_btn_down_data

Additional parameters for mouse button down event

typedef pjmedia_event_dummy_data pjmedia_event_keyframe_found_data

Additional parameters for keyframe found event

typedef pjmedia_event_dummy_data pjmedia_event_keyframe_missing_data

Additional parameters for keyframe missing event

typedef char pjmedia_event_user_data[sizeof(pjmedia_event_fmt_changed_data)]

Type of storage to hold user data in pjmedia_event structure

typedef pj_status_t pjmedia_event_cb(pjmedia_event *event, void *user_data)

The callback to receive media events.

Return

If the callback returns non-PJ_SUCCESS, this return code may be propagated back to the caller.

Parameters
  • event: The media event.

  • user_data: The user data associated with the callback.

typedef struct pjmedia_event_mgr pjmedia_event_mgr

Opaque data type for event manager. Typically, the event manager is a singleton instance, although application may instantiate more than one instances of this if required.

Enums

enum pjmedia_event_type

This enumeration describes list of media events.

Values:

PJMEDIA_EVENT_NONE

No event.

PJMEDIA_EVENT_FMT_CHANGED = PJMEDIA_FOURCC('F', 'M', 'C', 'H')

Media format has changed event.

PJMEDIA_EVENT_WND_CLOSING = PJMEDIA_FOURCC('W', 'N', 'C', 'L')

Video window is being closed.

PJMEDIA_EVENT_WND_CLOSED = PJMEDIA_FOURCC('W', 'N', 'C', 'O')

Video window has been closed event.

PJMEDIA_EVENT_WND_RESIZED = PJMEDIA_FOURCC('W', 'N', 'R', 'Z')

Video window has been resized event.

PJMEDIA_EVENT_MOUSE_BTN_DOWN = PJMEDIA_FOURCC('M', 'S', 'D', 'N')

Mouse button has been pressed event.

PJMEDIA_EVENT_KEYFRAME_FOUND = PJMEDIA_FOURCC('I', 'F', 'R', 'F')

Video keyframe has just been decoded event.

PJMEDIA_EVENT_KEYFRAME_MISSING = PJMEDIA_FOURCC('I', 'F', 'R', 'M')

Video decoding error due to missing keyframe event.

PJMEDIA_EVENT_ORIENT_CHANGED = PJMEDIA_FOURCC('O', 'R', 'N', 'T')

Video orientation has been changed event.

PJMEDIA_EVENT_RX_RTCP_FB = PJMEDIA_FOURCC('R', 'T', 'F', 'B')

RTCP-FB has been received.

PJMEDIA_EVENT_AUD_DEV_ERROR = PJMEDIA_FOURCC('A', 'E', 'R', 'R')

Audio device stopped on error.

PJMEDIA_EVENT_VID_DEV_ERROR = PJMEDIA_FOURCC('V', 'E', 'R', 'R')

Video device stopped on error.

PJMEDIA_EVENT_MEDIA_TP_ERR = PJMEDIA_FOURCC('T', 'E', 'R', 'R')

Transport media error.

PJMEDIA_EVENT_CALLBACK = PJMEDIA_FOURCC('C', 'B', ' ', ' ')

Callback event. Currently for internal use only.

enum pjmedia_event_publish_flag

This enumeration describes flags for event publication via pjmedia_event_publish().

Values:

PJMEDIA_EVENT_PUBLISH_DEFAULT

Default flag.

PJMEDIA_EVENT_PUBLISH_POST_EVENT = 1

Publisher will only post the event to the event manager. It is the event manager that will later notify all the publisher’s subscribers.

enum pjmedia_event_mgr_flag

Event manager flag.

Values:

PJMEDIA_EVENT_MGR_NO_THREAD = 1

Tell the event manager not to create any event worker thread. Do not set this flag if app plans to publish an event using PJMEDIA_EVENT_PUBLISH_POST_EVENT.

Functions

pj_status_t pjmedia_event_mgr_create(pj_pool_t *pool, unsigned options, pjmedia_event_mgr **mgr)

Create a new event manager instance. This will also set the pointer to the singleton instance if the value is still NULL.

Return

PJ_SUCCESS on success or the appropriate error code.

Parameters
  • pool: Pool to allocate memory from.

  • options: Options. Bitmask flags from pjmedia_event_mgr_flag

  • mgr: Pointer to hold the created instance of the event manager.

pjmedia_event_mgr *pjmedia_event_mgr_instance(void)

Get the singleton instance of the event manager.

Return

The instance.

void pjmedia_event_mgr_set_instance(pjmedia_event_mgr *mgr)

Manually assign a specific event manager instance as the singleton instance. Normally this is not needed if only one instance is ever going to be created, as the library automatically assign the singleton instance.

Parameters
  • mgr: The instance to be used as the singleton instance. Application may specify NULL to clear the singleton singleton instance.

void pjmedia_event_mgr_destroy(pjmedia_event_mgr *mgr)

Destroy an event manager. If the manager happens to be the singleton instance, the singleton instance will be set to NULL.

Parameters
  • mgr: The eventmanager. Specify NULL to use the singleton instance.

void pjmedia_event_init(pjmedia_event *event, pjmedia_event_type type, const pj_timestamp *ts, const void *src)

Initialize event structure with basic data about the event.

Parameters
  • event: The event to be initialized.

  • type: The event type to be set for this event.

  • ts: Event timestamp. May be set to NULL to set the event timestamp to zero.

  • src: Event source.

pj_status_t pjmedia_event_subscribe(pjmedia_event_mgr *mgr, pjmedia_event_cb *cb, void *user_data, void *epub)

Subscribe a callback function to events published by the specified publisher. Note that the subscriber may receive not only events emitted by the specific publisher specified in the argument, but also from other publishers contained by the publisher, if the publisher is republishing events from other publishers.

Return

PJ_SUCCESS on success or the appropriate error code.

Parameters
  • mgr: The event manager.

  • cb: The callback function to receive the event.

  • user_data: The user data to be associated with the callback function.

  • epub: The event publisher.

pj_status_t pjmedia_event_unsubscribe(pjmedia_event_mgr *mgr, pjmedia_event_cb *cb, void *user_data, void *epub)

Unsubscribe the callback associated with the user data from a publisher. If the user data is not specified, this function will do the unsubscription for all user data. If the publisher, epub, is not specified, this function will do the unsubscription from all publishers.

Return

PJ_SUCCESS on success or the appropriate error code.

Parameters
  • mgr: The event manager.

  • cb: The callback function.

  • user_data: The user data associated with the callback function, can be NULL.

  • epub: The event publisher, can be NULL.

pj_status_t pjmedia_event_publish(pjmedia_event_mgr *mgr, void *epub, pjmedia_event *event, pjmedia_event_publish_flag flag)

Publish the specified event to all subscribers of the specified event publisher. By default, the function will call all the subcribers’ callbacks immediately. If the publisher uses the flag PJMEDIA_EVENT_PUBLISH_POST_EVENT, publisher will only post the event to the event manager and return immediately. It is the event manager that will later notify all the publisher’s subscribers.

Return

PJ_SUCCESS only if all subscription callbacks returned PJ_SUCCESS.

Parameters
  • mgr: The event manager.

  • epub: The event publisher.

  • event: The event to be published.

  • flag: Publication flag.

struct pjmedia_event_fmt_changed_data
#include <event.h>

Additional data/parameters for media format changed event (PJMEDIA_EVENT_FMT_CHANGED).

struct pjmedia_event_dummy_data
#include <event.h>

Additional data/parameters are not needed.

struct pjmedia_event_wnd_resized_data
#include <event.h>

Additional data/parameters for window resized event (PJMEDIA_EVENT_WND_RESIZED).

struct pjmedia_event_wnd_closing_data
#include <event.h>

Additional data/parameters for window closing event.

struct pjmedia_event_aud_dev_err_data
#include <event.h>

Additional data/parameters for audio device error event.

struct pjmedia_event_vid_dev_err_data
#include <event.h>

Additional data/parameters for video device error event.

struct pjmedia_event_media_tp_err_data
#include <event.h>

Additional data/parameters for media transmit error event.

struct pjmedia_event
#include <event.h>

This structure describes a media event. It consists mainly of the event type and additional data/parameters for the event. Applications can use pjmedia_event_init() to initialize this event structure with basic information about the event.