Event Framework

PJMEDIA event framework. More...

Data Structures
struct	pjmedia_event_fmt_changed_data
struct	pjmedia_event_dummy_data
struct	pjmedia_event_wnd_resized_data
struct	pjmedia_event_wnd_closing_data
struct	pjmedia_event_aud_dev_err_data
struct	pjmedia_event_vid_dev_err_data
struct	pjmedia_event_media_tp_err_data
struct	pjmedia_event

Macros
#define	PJMEDIA_EVENT_DATA_MAX_SIZE   sizeof(pjmedia_event_fmt_changed_data)

Typedefs
typedef pjmedia_event_dummy_data	pjmedia_event_wnd_closed_data
typedef pjmedia_event_dummy_data	pjmedia_event_mouse_btn_down_data
typedef pjmedia_event_dummy_data	pjmedia_event_keyframe_found_data
typedef pjmedia_event_dummy_data	pjmedia_event_keyframe_missing_data
typedef char	pjmedia_event_user_data[sizeof(pjmedia_event_fmt_changed_data)]
typedef pj_status_t	pjmedia_event_cb(pjmedia_event *event, void *user_data)
typedef struct pjmedia_event_mgr	pjmedia_event_mgr

Enumerations
enum	pjmedia_event_type {   PJMEDIA_EVENT_NONE ,   PJMEDIA_EVENT_FMT_CHANGED = PJMEDIA_FOURCC('F', 'M', 'C', 'H') ,   PJMEDIA_EVENT_WND_CLOSING = PJMEDIA_FOURCC('W', 'N', 'C', 'L') ,   PJMEDIA_EVENT_WND_CLOSED = PJMEDIA_FOURCC('W', 'N', 'C', 'O') ,   PJMEDIA_EVENT_WND_RESIZED = PJMEDIA_FOURCC('W', 'N', 'R', 'Z') ,   PJMEDIA_EVENT_MOUSE_BTN_DOWN = PJMEDIA_FOURCC('M', 'S', 'D', 'N') ,   PJMEDIA_EVENT_KEYFRAME_FOUND = PJMEDIA_FOURCC('I', 'F', 'R', 'F') ,   PJMEDIA_EVENT_KEYFRAME_MISSING = PJMEDIA_FOURCC('I', 'F', 'R', 'M') ,   PJMEDIA_EVENT_ORIENT_CHANGED = PJMEDIA_FOURCC('O', 'R', 'N', 'T') ,   PJMEDIA_EVENT_RX_RTCP_FB = PJMEDIA_FOURCC('R', 'T', 'F', 'B') ,   PJMEDIA_EVENT_AUD_DEV_ERROR = PJMEDIA_FOURCC('A', 'E', 'R', 'R') ,   PJMEDIA_EVENT_VID_DEV_ERROR = PJMEDIA_FOURCC('V', 'E', 'R', 'R') ,   PJMEDIA_EVENT_MEDIA_TP_ERR = PJMEDIA_FOURCC('T', 'E', 'R', 'R') ,   PJMEDIA_EVENT_CALLBACK = PJMEDIA_FOURCC('C', 'B', ' ', ' ') }
enum	pjmedia_event_publish_flag {   PJMEDIA_EVENT_PUBLISH_DEFAULT ,   PJMEDIA_EVENT_PUBLISH_POST_EVENT = 1 }
enum	pjmedia_event_mgr_flag { PJMEDIA_EVENT_MGR_NO_THREAD = 1 }

Functions
pj_status_t	pjmedia_event_mgr_create (pj_pool_t *pool, unsigned options, pjmedia_event_mgr **mgr)
pjmedia_event_mgr *	pjmedia_event_mgr_instance (void)
void	pjmedia_event_mgr_set_instance (pjmedia_event_mgr *mgr)
void	pjmedia_event_mgr_destroy (pjmedia_event_mgr *mgr)
void	pjmedia_event_init (pjmedia_event *event, pjmedia_event_type type, const pj_timestamp *ts, const void *src)
pj_status_t	pjmedia_event_subscribe (pjmedia_event_mgr *mgr, pjmedia_event_cb *cb, void *user_data, void *epub)
pj_status_t	pjmedia_event_unsubscribe (pjmedia_event_mgr *mgr, pjmedia_event_cb *cb, void *user_data, void *epub)
pj_status_t	pjmedia_event_publish (pjmedia_event_mgr *mgr, void *epub, pjmedia_event *event, pjmedia_event_publish_flag flag)

Detailed Description

Macro Definition Documentation

PJMEDIA_EVENT_DATA_MAX_SIZE

#define PJMEDIA_EVENT_DATA_MAX_SIZE   sizeof(pjmedia_event_fmt_changed_data)

Maximum size of additional parameters section in pjmedia_event structure

Typedef Documentation

pjmedia_event_wnd_closed_data

typedef pjmedia_event_dummy_data pjmedia_event_wnd_closed_data

Additional parameters for window changed event.

pjmedia_event_mouse_btn_down_data

typedef pjmedia_event_dummy_data pjmedia_event_mouse_btn_down_data

Additional parameters for mouse button down event

pjmedia_event_keyframe_found_data

typedef pjmedia_event_dummy_data pjmedia_event_keyframe_found_data

Additional parameters for keyframe found event

pjmedia_event_keyframe_missing_data

typedef pjmedia_event_dummy_data pjmedia_event_keyframe_missing_data

Additional parameters for keyframe missing event

pjmedia_event_user_data

typedef char pjmedia_event_user_data[sizeof(pjmedia_event_fmt_changed_data)]

Type of storage to hold user data in pjmedia_event structure

pjmedia_event_cb

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

The callback to receive media events.

Parameters

event	The media event.
user_data	The user data associated with the callback.

Returns

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

pjmedia_event_mgr

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.

Enumeration Type Documentation

pjmedia_event_type

enum pjmedia_event_type

This enumeration describes list of media events.

Enumerator
PJMEDIA_EVENT_NONE	No event.
PJMEDIA_EVENT_FMT_CHANGED	Media format has changed event.
PJMEDIA_EVENT_WND_CLOSING	Video window is being closed.
PJMEDIA_EVENT_WND_CLOSED	Video window has been closed event.
PJMEDIA_EVENT_WND_RESIZED	Video window has been resized event.
PJMEDIA_EVENT_MOUSE_BTN_DOWN	Mouse button has been pressed event.
PJMEDIA_EVENT_KEYFRAME_FOUND	Video keyframe has just been decoded event.
PJMEDIA_EVENT_KEYFRAME_MISSING	Video decoding error due to missing keyframe event.
PJMEDIA_EVENT_ORIENT_CHANGED	Video orientation has been changed event.
PJMEDIA_EVENT_RX_RTCP_FB	RTCP-FB has been received.
PJMEDIA_EVENT_AUD_DEV_ERROR	Audio device stopped on error.
PJMEDIA_EVENT_VID_DEV_ERROR	Video device stopped on error.
PJMEDIA_EVENT_MEDIA_TP_ERR	Transport media error.
PJMEDIA_EVENT_CALLBACK	Callback event. Currently for internal use only.

pjmedia_event_publish_flag

enum pjmedia_event_publish_flag

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

Enumerator
PJMEDIA_EVENT_PUBLISH_DEFAULT	Default flag.
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.

pjmedia_event_mgr_flag

enum pjmedia_event_mgr_flag

Event manager flag.

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.

Function Documentation

pjmedia_event_mgr_create()

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_instance()

pjmedia_event_mgr * pjmedia_event_mgr_instance

(

void

)

Get the singleton instance of the event manager.

Returns

The instance.

pjmedia_event_mgr_set_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.

pjmedia_event_mgr_destroy()

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.

pjmedia_event_init()

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.

pjmedia_event_subscribe()

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.

pjmedia_event_unsubscribe()

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.

pjmedia_event_publish()

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.