← Back to branch summary

~ubuntu-branches/ubuntu/vivid/sflphone/vivid

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.0.1/pjmedia/include/pjmedia/event.h

  • Committer: Package Import Robot
  • Author(s): Mark Purcell
  • Date: 2013-06-30 11:40:56 UTC
  • mfrom: (4.1.18 saucy-proposed)
  • Revision ID: package-import@ubuntu.com-20130630114056-0np50jkyqo6vnmii
Tags: 1.2.3-2
* changeset_r92d62cfc54732bbbcfff2b1d36c096b120b981a5.diff 
  - fixes automatic endian detection 
* Update Vcs: fixes vcs-field-not-canonical

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject-2.0.1/pjmedia/include/pjmedia/event.h
 
1
/* $Id: event.h 3905 2011-12-09 05:15:39Z ming $ */
 
2
/*
 
3
 * Copyright (C) 2011-2011 Teluu Inc. (http://www.teluu.com)
 
4
 *
 
5
 * This program is free software; you can redistribute it and/or modify
 
6
 * it under the terms of the GNU General Public License as published by
 
7
 * the Free Software Foundation; either version 2 of the License, or
 
8
 * (at your option) any later version.
 
9
 *
 
10
 * This program is distributed in the hope that it will be useful,
 
11
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 
12
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 
13
 * GNU General Public License for more details.
 
14
 *
 
15
 * You should have received a copy of the GNU General Public License
 
16
 * along with this program; if not, write to the Free Software
 
17
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 
18
 */
 
19
#ifndef __PJMEDIA_EVENT_H__
 
20
#define __PJMEDIA_EVENT_H__
 
21
 
 
22
/**
 
23
 * @file pjmedia/event.h
 
24
 * @brief Event framework
 
25
 */
 
26
#include <pjmedia/format.h>
 
27
#include <pjmedia/signatures.h>
 
28
 
 
29
PJ_BEGIN_DECL
 
30
 
 
31
/**
 
32
 * @defgroup PJMEDIA_EVENT Event Framework
 
33
 * @brief PJMEDIA event framework
 
34
 * @{
 
35
 */
 
36
 
 
37
/**
 
38
 * This enumeration describes list of media events.
 
39
 */
 
40
typedef enum pjmedia_event_type
 
41
{
 
42
    /**
 
43
     * No event.
 
44
     */
 
45
    PJMEDIA_EVENT_NONE,
 
46
 
 
47
    /**
 
48
     * Media format has changed event.
 
49
     */
 
50
    PJMEDIA_EVENT_FMT_CHANGED   = PJMEDIA_FOURCC('F', 'M', 'C', 'H'),
 
51
 
 
52
    /**
 
53
     * Video window is being closed.
 
54
     */
 
55
    PJMEDIA_EVENT_WND_CLOSING   = PJMEDIA_FOURCC('W', 'N', 'C', 'L'),
 
56
 
 
57
    /**
 
58
     * Video window has been closed event.
 
59
     */
 
60
    PJMEDIA_EVENT_WND_CLOSED    = PJMEDIA_FOURCC('W', 'N', 'C', 'O'),
 
61
 
 
62
    /**
 
63
     * Video window has been resized event.
 
64
     */
 
65
    PJMEDIA_EVENT_WND_RESIZED   = PJMEDIA_FOURCC('W', 'N', 'R', 'Z'),
 
66
 
 
67
    /**
 
68
     * Mouse button has been pressed event.
 
69
     */
 
70
    PJMEDIA_EVENT_MOUSE_BTN_DOWN = PJMEDIA_FOURCC('M', 'S', 'D', 'N'),
 
71
 
 
72
    /**
 
73
     * Video keyframe has just been decoded event.
 
74
     */
 
75
    PJMEDIA_EVENT_KEYFRAME_FOUND = PJMEDIA_FOURCC('I', 'F', 'R', 'F'),
 
76
 
 
77
    /**
 
78
     * Video decoding error due to missing keyframe event.
 
79
     */
 
80
    PJMEDIA_EVENT_KEYFRAME_MISSING = PJMEDIA_FOURCC('I', 'F', 'R', 'M'),
 
81
 
 
82
    /**
 
83
     * Video orientation has been changed event.
 
84
     */
 
85
    PJMEDIA_EVENT_ORIENT_CHANGED = PJMEDIA_FOURCC('O', 'R', 'N', 'T')
 
86
 
 
87
} pjmedia_event_type;
 
88
 
 
89
/**
 
90
 * Additional data/parameters for media format changed event
 
91
 * (PJMEDIA_EVENT_FMT_CHANGED).
 
92
 */
 
93
typedef struct pjmedia_event_fmt_changed_data
 
94
{
 
95
    /** The media flow direction */
 
96
    pjmedia_dir         dir;
 
97
 
 
98
    /** The new media format. */
 
99
    pjmedia_format      new_fmt;
 
100
} pjmedia_event_fmt_changed_data;
 
101
 
 
102
/**
 
103
 * Additional data/parameters are not needed.
 
104
 */
 
105
typedef struct pjmedia_event_dummy_data
 
106
{
 
107
    /** Dummy data */
 
108
    int                 dummy;
 
109
} pjmedia_event_dummy_data;
 
110
 
 
111
/**
 
112
 * Additional data/parameters for window resized event
 
113
 * (PJMEDIA_EVENT_WND_RESIZED).
 
114
 */
 
115
typedef struct pjmedia_event_wnd_resized_data
 
116
{
 
117
    /**
 
118
     * The new window size.
 
119
     */
 
120
    pjmedia_rect_size   new_size;
 
121
} pjmedia_event_wnd_resized_data;
 
122
 
 
123
/**
 
124
 * Additional data/parameters for window closing event.
 
125
 */
 
126
typedef struct pjmedia_event_wnd_closing_data
 
127
{
 
128
    /** Consumer may set this field to PJ_TRUE to cancel the closing */
 
129
    pj_bool_t           cancel;
 
130
} pjmedia_event_wnd_closing_data;
 
131
 
 
132
/** Additional parameters for window changed event. */
 
133
typedef pjmedia_event_dummy_data pjmedia_event_wnd_closed_data;
 
134
 
 
135
/** Additional parameters for mouse button down event */
 
136
typedef pjmedia_event_dummy_data pjmedia_event_mouse_btn_down_data;
 
137
 
 
138
/** Additional parameters for keyframe found event */
 
139
typedef pjmedia_event_dummy_data pjmedia_event_keyframe_found_data;
 
140
 
 
141
/** Additional parameters for keyframe missing event */
 
142
typedef pjmedia_event_dummy_data pjmedia_event_keyframe_missing_data;
 
143
 
 
144
/**
 
145
 * Maximum size of additional parameters section in pjmedia_event structure
 
146
 */
 
147
#define PJMEDIA_EVENT_DATA_MAX_SIZE     sizeof(pjmedia_event_fmt_changed_data)
 
148
 
 
149
/** Type of storage to hold user data in pjmedia_event structure */
 
150
typedef char pjmedia_event_user_data[PJMEDIA_EVENT_DATA_MAX_SIZE];
 
151
 
 
152
/**
 
153
 * This structure describes a media event. It consists mainly of the event
 
154
 * type and additional data/parameters for the event. Applications can
 
155
 * use #pjmedia_event_init() to initialize this event structure with
 
156
 * basic information about the event.
 
157
 */
 
158
typedef struct pjmedia_event
 
159
{
 
160
    /**
 
161
     * The event type.
 
162
     */
 
163
    pjmedia_event_type                   type;
 
164
 
 
165
    /**
 
166
     * The media timestamp when the event occurs.
 
167
     */
 
168
    pj_timestamp                         timestamp;
 
169
 
 
170
    /**
 
171
     * Pointer information about the source of this event. This field
 
172
     * is provided mainly for comparison purpose so that event subscribers
 
173
     * can check which source the event originated from. Usage of this
 
174
     * pointer for other purpose may require special care such as mutex
 
175
     * locking or checking whether the object is already destroyed.
 
176
     */
 
177
    const void                          *src;
 
178
 
 
179
    /**
 
180
     * Pointer information about the publisher of this event. This field
 
181
     * is provided mainly for comparison purpose so that event subscribers
 
182
     * can check which object published the event. Usage of this
 
183
     * pointer for other purpose may require special care such as mutex
 
184
     * locking or checking whether the object is already destroyed.
 
185
     */
 
186
    const void                          *epub;
 
187
 
 
188
    /**
 
189
     * Additional data/parameters about the event. The type of data
 
190
     * will be specific to the event type being reported.
 
191
     */
 
192
    union {
 
193
        /** Media format changed event data. */
 
194
        pjmedia_event_fmt_changed_data          fmt_changed;
 
195
 
 
196
        /** Window resized event data */
 
197
        pjmedia_event_wnd_resized_data          wnd_resized;
 
198
 
 
199
        /** Window closing event data. */
 
200
        pjmedia_event_wnd_closing_data          wnd_closing;
 
201
 
 
202
        /** Window closed event data */
 
203
        pjmedia_event_wnd_closed_data           wnd_closed;
 
204
 
 
205
        /** Mouse button down event data */
 
206
        pjmedia_event_mouse_btn_down_data       mouse_btn_down;
 
207
 
 
208
        /** Keyframe found event data */
 
209
        pjmedia_event_keyframe_found_data       keyframe_found;
 
210
 
 
211
        /** Keyframe missing event data */
 
212
        pjmedia_event_keyframe_missing_data     keyframe_missing;
 
213
 
 
214
        /** Storage for user event data */
 
215
        pjmedia_event_user_data                 user;
 
216
 
 
217
        /** Pointer to storage to user event data, if it's outside
 
218
         * this struct
 
219
         */
 
220
        void                                    *ptr;
 
221
    } data;
 
222
} pjmedia_event;
 
223
 
 
224
/**
 
225
 * The callback to receive media events.
 
226
 *
 
227
 * @param event         The media event.
 
228
 * @param user_data     The user data associated with the callback.
 
229
 *
 
230
 * @return              If the callback returns non-PJ_SUCCESS, this return
 
231
 *                      code may be propagated back to the caller.
 
232
 */
 
233
typedef pj_status_t pjmedia_event_cb(pjmedia_event *event,
 
234
                                     void *user_data);
 
235
 
 
236
/**
 
237
 * This enumeration describes flags for event publication via
 
238
 * #pjmedia_event_publish().
 
239
 */
 
240
typedef enum pjmedia_event_publish_flag
 
241
{
 
242
    /**
 
243
     * Publisher will only post the event to the event manager. It is the
 
244
     * event manager that will later notify all the publisher's subscribers.
 
245
     */
 
246
    PJMEDIA_EVENT_PUBLISH_POST_EVENT = 1
 
247
 
 
248
} pjmedia_event_publish_flag;
 
249
 
 
250
/**
 
251
 * Event manager flag.
 
252
 */
 
253
typedef enum pjmedia_event_mgr_flag
 
254
{
 
255
    /**
 
256
     * Tell the event manager not to create any event worker thread.
 
257
     */
 
258
    PJMEDIA_EVENT_MGR_NO_THREAD = 1
 
259
 
 
260
} pjmedia_event_mgr_flag;
 
261
 
 
262
/**
 
263
 * Opaque data type for event manager. Typically, the event manager
 
264
 * is a singleton instance, although application may instantiate more than one
 
265
 * instances of this if required.
 
266
 */
 
267
typedef struct pjmedia_event_mgr pjmedia_event_mgr;
 
268
 
 
269
/**
 
270
 * Create a new event manager instance. This will also set the pointer
 
271
 * to the singleton instance if the value is still NULL.
 
272
 *
 
273
 * @param pool          Pool to allocate memory from.
 
274
 * @param options       Options. Bitmask flags from #pjmedia_event_mgr_flag
 
275
 * @param mgr           Pointer to hold the created instance of the
 
276
 *                      event manager.
 
277
 *
 
278
 * @return              PJ_SUCCESS on success or the appropriate error code.
 
279
 */
 
280
PJ_DECL(pj_status_t) pjmedia_event_mgr_create(pj_pool_t *pool,
 
281
                                              unsigned options,
 
282
                                              pjmedia_event_mgr **mgr);
 
283
 
 
284
/**
 
285
 * Get the singleton instance of the event manager.
 
286
 *
 
287
 * @return              The instance.
 
288
 */
 
289
PJ_DECL(pjmedia_event_mgr*) pjmedia_event_mgr_instance(void);
 
290
 
 
291
/**
 
292
 * Manually assign a specific event manager instance as the singleton
 
293
 * instance. Normally this is not needed if only one instance is ever
 
294
 * going to be created, as the library automatically assign the singleton
 
295
 * instance.
 
296
 *
 
297
 * @param mgr           The instance to be used as the singleton instance.
 
298
 *                      Application may specify NULL to clear the singleton
 
299
 *                      singleton instance.
 
300
 */
 
301
PJ_DECL(void) pjmedia_event_mgr_set_instance(pjmedia_event_mgr *mgr);
 
302
 
 
303
/**
 
304
 * Destroy an event manager. If the manager happens to be the singleton
 
305
 * instance, the singleton instance will be set to NULL.
 
306
 *
 
307
 * @param mgr           The eventmanager. Specify NULL to use
 
308
 *                      the singleton instance.
 
309
 */
 
310
PJ_DECL(void) pjmedia_event_mgr_destroy(pjmedia_event_mgr *mgr);
 
311
 
 
312
/**
 
313
 * Initialize event structure with basic data about the event.
 
314
 *
 
315
 * @param event         The event to be initialized.
 
316
 * @param type          The event type to be set for this event.
 
317
 * @param ts            Event timestamp. May be set to NULL to set the event
 
318
 *                      timestamp to zero.
 
319
 * @param src           Event source.
 
320
 */
 
321
PJ_DECL(void) pjmedia_event_init(pjmedia_event *event,
 
322
                                 pjmedia_event_type type,
 
323
                                 const pj_timestamp *ts,
 
324
                                 const void *src);
 
325
 
 
326
/**
 
327
 * Subscribe a callback function to events published by the specified
 
328
 * publisher. Note that the subscriber may receive not only events emitted by
 
329
 * the specific publisher specified in the argument, but also from other
 
330
 * publishers contained by the publisher, if the publisher is republishing
 
331
 * events from other publishers.
 
332
 *
 
333
 * @param mgr           The event manager.
 
334
 * @param cb            The callback function to receive the event.
 
335
 * @param user_data     The user data to be associated with the callback
 
336
 *                      function.
 
337
 * @param epub          The event publisher.
 
338
 *
 
339
 * @return              PJ_SUCCESS on success or the appropriate error code.
 
340
 */
 
341
PJ_DECL(pj_status_t) pjmedia_event_subscribe(pjmedia_event_mgr *mgr,
 
342
                                             pjmedia_event_cb *cb,
 
343
                                             void *user_data,
 
344
                                             void *epub);
 
345
 
 
346
/**
 
347
 * Unsubscribe the callback associated with the user data from a publisher.
 
348
 * If the user data is not specified, this function will do the
 
349
 * unsubscription for all user data. If the publisher, epub, is not
 
350
 * specified, this function will do the unsubscription from all publishers.
 
351
 *
 
352
 * @param mgr           The event manager.
 
353
 * @param cb            The callback function.
 
354
 * @param user_data     The user data associated with the callback
 
355
 *                      function, can be NULL.
 
356
 * @param epub          The event publisher, can be NULL.
 
357
 *
 
358
 * @return              PJ_SUCCESS on success or the appropriate error code.
 
359
 */
 
360
PJ_DECL(pj_status_t)
 
361
pjmedia_event_unsubscribe(pjmedia_event_mgr *mgr,
 
362
                          pjmedia_event_cb *cb,
 
363
                          void *user_data,
 
364
                          void *epub);
 
365
 
 
366
/**
 
367
 * Publish the specified event to all subscribers of the specified event
 
368
 * publisher. By default, the function will call all the subcribers'
 
369
 * callbacks immediately. If the publisher uses the flag
 
370
 * PJMEDIA_EVENT_PUBLISH_POST_EVENT, publisher will only post the event
 
371
 * to the event manager and return immediately. It is the event manager
 
372
 * that will later notify all the publisher's subscribers.
 
373
 *
 
374
 * @param mgr           The event manager.
 
375
 * @param epub          The event publisher.
 
376
 * @param event         The event to be published.
 
377
 * @param flag          Publication flag.
 
378
 *
 
379
 * @return              PJ_SUCCESS only if all subscription callbacks returned
 
380
 *                      PJ_SUCCESS.
 
381
 */
 
382
PJ_DECL(pj_status_t) pjmedia_event_publish(pjmedia_event_mgr *mgr,
 
383
                                           void *epub,
 
384
                                           pjmedia_event *event,
 
385
                                           pjmedia_event_publish_flag flag);
 
386
 
 
387
 
 
388
/**
 
389
 * @}  PJMEDIA_EVENT
 
390
 */
 
391
 
 
392
 
 
393
PJ_END_DECL
 
394
 
 
395
#endif  /* __PJMEDIA_EVENT_H__ */