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.

Param event:: The media event.
Param user_data:: The user data associated with the callback.
Return:: If the callback returns non-PJ_SUCCESS, this return code may be propagated back to the caller.

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:

enumerator PJMEDIA_EVENT_NONE: No event.

enumerator PJMEDIA_EVENT_FMT_CHANGED: Media format has changed event.

enumerator PJMEDIA_EVENT_WND_CLOSING: Video window is being closed.

enumerator PJMEDIA_EVENT_WND_CLOSED: Video window has been closed event.

enumerator PJMEDIA_EVENT_WND_RESIZED: Video window has been resized event.

enumerator PJMEDIA_EVENT_MOUSE_BTN_DOWN: Mouse button has been pressed event.

enumerator PJMEDIA_EVENT_KEYFRAME_FOUND: Video keyframe has just been decoded event.

enumerator PJMEDIA_EVENT_KEYFRAME_MISSING: Video decoding error due to missing keyframe event.

enumerator PJMEDIA_EVENT_ORIENT_CHANGED: Video orientation has been changed event.

enumerator PJMEDIA_EVENT_RX_RTCP_FB: RTCP-FB has been received.

enumerator PJMEDIA_EVENT_AUD_DEV_ERROR: Audio device stopped on error.

enumerator PJMEDIA_EVENT_VID_DEV_ERROR: Video device stopped on error.

enumerator PJMEDIA_EVENT_MEDIA_TP_ERR: Transport media error.

enumerator PJMEDIA_EVENT_CALLBACK: Callback event. Currently for internal use only.

enum pjmedia_event_publish_flag

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

Values:

enumerator PJMEDIA_EVENT_PUBLISH_DEFAULT: Default flag.

enumerator PJMEDIA_EVENT_PUBLISH_POST_EVENT: 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:

enumerator PJMEDIA_EVENT_MGR_NO_THREAD: 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.

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.

Returns:

PJ_SUCCESS on success or the appropriate error code.

pjmedia_event_mgr *pjmedia_event_mgr_instance(void)

Get the singleton instance of the event manager.

Returns:: 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.

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.

Returns:

PJ_SUCCESS on success or the appropriate error code.

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.

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.

Returns:

PJ_SUCCESS on success or the appropriate error code.

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.

Parameters:

mgr – The event manager.
epub – The event publisher.
event – The event to be published.
flag – Publication flag.

Returns:

PJ_SUCCESS only if all subscription callbacks returned PJ_SUCCESS.

struct pjmedia_event_fmt_changed_data

#include <event.h>

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

Public Members

pjmedia_dir dir: The media flow direction

pjmedia_format new_fmt: The new media format.

struct pjmedia_event_dummy_data

#include <event.h>

Additional data/parameters are not needed.

Public Members

int dummy: Dummy data

struct pjmedia_event_wnd_resized_data

#include <event.h>

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

Public Members

pjmedia_rect_size new_size: The new window size.

struct pjmedia_event_wnd_closing_data

#include <event.h>

Additional data/parameters for window closing event.

Public Members

pj_bool_t cancel: Consumer may set this field to PJ_TRUE to cancel the closing

struct pjmedia_event_aud_dev_err_data

#include <event.h>

Additional data/parameters for audio device error event.

Public Members

pjmedia_dir dir: The media direction that fails

pjmedia_aud_dev_index id: The audio device ID

pj_status_t status: The error code

struct pjmedia_event_vid_dev_err_data

#include <event.h>

Additional data/parameters for video device error event.

Public Members

pjmedia_dir dir: The media direction that fails

pjmedia_vid_dev_index id: The video device ID

pj_status_t status: The error code

struct pjmedia_event_media_tp_err_data

#include <event.h>

Additional data/parameters for media transmit error event.

Public Members

pjmedia_type type: The media type

pj_bool_t is_rtp: RTP/RTCP?

pjmedia_dir dir: Media direction

pj_status_t status: The error code

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.

Public Members

pjmedia_event_type type: The event type.

pj_timestamp timestamp: The media timestamp when the event occurs.

const void *src: Pointer information about the source of this event. This field is provided mainly for comparison purpose so that event subscribers can check which source the event originated from. Usage of this pointer for other purpose may require special care such as mutex locking or checking whether the object is already destroyed.

const void *epub: Pointer information about the publisher of this event. This field is provided mainly for comparison purpose so that event subscribers can check which object published the event. Usage of this pointer for other purpose may require special care such as mutex locking or checking whether the object is already destroyed.

pjmedia_event_fmt_changed_data fmt_changed: Media format changed event data.

pjmedia_event_wnd_resized_data wnd_resized: Window resized event data

pjmedia_event_wnd_closing_data wnd_closing: Window closing event data.

pjmedia_event_wnd_closed_data wnd_closed: Window closed event data

pjmedia_event_mouse_btn_down_data mouse_btn_down: Mouse button down event data

pjmedia_event_keyframe_found_data keyframe_found: Keyframe found event data

pjmedia_event_keyframe_missing_data keyframe_missing: Keyframe missing event data

pjmedia_event_aud_dev_err_data aud_dev_err: Audio device error event data

pjmedia_event_vid_dev_err_data vid_dev_err: Video device error event data

pjmedia_event_user_data user: Storage for user event data

pjmedia_event_media_tp_err_data med_tp_err: Media transport error event data

pjmedia_event_rx_rtcp_fb_data rx_rtcp_fb: Receiving RTCP-FB event data

void *ptr: Pointer to storage to user event data, if it’s outside this struct

union pjmedia_event::[anonymous] data: Additional data/parameters about the event. The type of data will be specific to the event type being reported.