1 /*****************************************************************************
2 * events.h: events definitions
3 * Interface used to send events.
4 *****************************************************************************
5 * Copyright (C) 2007 the VideoLAN team
8 * Authors: Pierre d'Herbemont
10 * This program is free software; you can redistribute it and/or modify
11 * it under the terms of the GNU General Public License as published by
12 * the Free Software Foundation; either version 2 of the License, or
13 * (at your option) any later version.
15 * This program is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 * GNU General Public License for more details.
20 * You should have received a copy of the GNU General Public License
21 * along with this program; if not, write to the Free Software
22 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
23 *****************************************************************************/
28 #include <vlc_arrays.h>
32 * This file is the interface definition for events
33 * (implementation in src/misc/events.c)
36 /*****************************************************************************
38 *****************************************************************************/
42 * This implements a way to send and receive event for an object (which can be
43 * a simple C struct or less).
45 * This is in direct concurrency with the Variable based Callback
46 * (see src/misc/variables.c).
48 * It has the following advantages over Variable based Callback:
49 * - No need to implement the whole VLC_COMMON_MEMBERS in the object,
50 * thus it reduce it size. This is especially true for input_item_t which
51 * doesn't have VLC_COMMON_MEMBERS. This is the first reason of existence of
52 * this implementation.
53 * - Libvlc can easily be based upon that.
54 * - Existing event are clearly declared (in include/vlc_events.h)
59 * (vlc_cool_object_t doesn't need to have the VLC_COMMON_MEMBERS.)
61 * struct vlc_cool_object_t
64 * vlc_event_manager_t p_event_manager;
68 * vlc_my_cool_object_new()
71 * vlc_event_manager_Create( &p_self->p_event_manager, p_this );
72 * vlc_event_manager_register_event_type(p_self->p_event_manager,
73 * vlc_MyCoolObjectDidSomething, p_e)
77 * vlc_my_cool_object_release()
80 * vlc_event_manager_release( p_self->p_event_manager );
84 * vlc_my_cool_object_do_something()
88 * event.type = vlc_MyCoolObjectDidSomething;
89 * event.u.my_cool_object_did_something.what_it_did = kSomething;
90 * vlc_event_send( p_self->p_event_manager, &event );
94 /*****************************************************************************
96 *****************************************************************************/
98 /* Private structure defined in misc/events.c */
99 struct vlc_event_listeners_group_t;
101 /* Event manager type */
102 typedef struct vlc_event_manager_t
105 DECL_ARRAY(struct vlc_event_listeners_group_t *) listeners_groups;
106 } vlc_event_manager_t;
109 typedef enum vlc_event_type_t {
110 vlc_InputItemMetaChanged
113 /* Event definition */
114 typedef struct vlc_event_t
116 vlc_event_type_t type;
117 void * p_obj; /* Sender object, automatically filled by event_Send() */
118 union event_type_specific
122 int meta; /* One of the meta identified in include/vlc_meta.h */
123 } input_item_meta_changed;
127 /* Event callback type */
128 typedef void ( *vlc_event_callback_t )( const vlc_event_t *, void * );
130 /*****************************************************************************
132 *****************************************************************************/
135 * p_obj points to the object that owns the event manager, and from
136 * which events are sent
138 int event_manager_Create( vlc_event_manager_t * p_em, void * p_obj );
143 void event_manager_Destroy( vlc_event_manager_t * p_em );
146 * Tells a specific event manager that it will handle event_type object
148 int event_manager_RegisterEventType( vlc_event_manager_t * p_em,
149 vlc_event_type_t event_type );
152 * Send an event to the listener attached to this p_em.
154 void event_Send( vlc_event_manager_t * p_em, vlc_event_t * p_event );
157 * Add a callback for an event.
159 int event_Attach( vlc_event_manager_t * p_event_manager,
160 vlc_event_type_t event_type,
161 vlc_event_callback_t pf_callback,
165 * Remove a callback for an event.
167 int event_Detach( vlc_event_manager_t *p_event_manager,
168 vlc_event_type_t event_type,
169 vlc_event_callback_t pf_callback,
172 #endif /* VLC_EVENTS_H */