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>
33 * This file is the interface definition for events
34 * (implementation in src/misc/events.c)
37 /*****************************************************************************
39 *****************************************************************************/
43 * This implements a way to send and receive event for an object (which can be
44 * a simple C struct or less).
46 * This is in direct concurrency with the Variable based Callback
47 * (see src/misc/variables.c).
49 * It has the following advantages over Variable based Callback:
50 * - No need to implement the whole VLC_COMMON_MEMBERS in the object,
51 * thus it reduce it size. This is especially true for input_item_t which
52 * doesn't have VLC_COMMON_MEMBERS. This is the first reason of existence of
53 * this implementation.
54 * - Libvlc can easily be based upon that.
55 * - Existing event are clearly declared (in include/vlc_events.h)
60 * (vlc_cool_object_t doesn't need to have the VLC_COMMON_MEMBERS.)
62 * struct vlc_cool_object_t
65 * vlc_event_manager_t p_event_manager;
69 * vlc_my_cool_object_new()
72 * vlc_event_manager_Create( &p_self->p_event_manager, p_this );
73 * vlc_event_manager_register_event_type(p_self->p_event_manager,
74 * vlc_MyCoolObjectDidSomething, p_e)
78 * vlc_my_cool_object_release()
81 * vlc_event_manager_release( p_self->p_event_manager );
85 * vlc_my_cool_object_do_something()
89 * event.type = vlc_MyCoolObjectDidSomething;
90 * event.u.my_cool_object_did_something.what_it_did = kSomething;
91 * vlc_event_send( p_self->p_event_manager, &event );
95 /*****************************************************************************
97 *****************************************************************************/
99 /* Private structure defined in misc/events.c */
100 struct vlc_event_listeners_group_t;
102 /* Event manager type */
103 typedef struct vlc_event_manager_t
106 vlc_mutex_t object_lock;
107 DECL_ARRAY(struct vlc_event_listeners_group_t *) listeners_groups;
108 } vlc_event_manager_t;
111 typedef enum vlc_event_type_t {
112 /* Input item events */
113 vlc_InputItemMetaChanged,
114 vlc_InputItemSubItemAdded,
116 /* Service Discovery event */
117 vlc_ServicesDiscoveryItemAdded,
118 vlc_ServicesDiscoveryItemRemoved
121 /* Event definition */
122 typedef struct vlc_event_t
124 vlc_event_type_t type;
125 void * p_obj; /* Sender object, automatically filled by vlc_event_send() */
126 union vlc_event_type_specific
128 /* Input item events */
129 struct vlc_input_item_meta_changed
131 vlc_meta_type_t meta_type;
132 } input_item_meta_changed;
133 struct vlc_input_item_subitem_added
135 input_item_t * p_new_child;
136 } input_item_subitem_added;
138 /* Service discovery events */
139 struct vlc_services_discovery_item_added
141 input_item_t * p_new_item;
142 const char * psz_category;
143 } services_discovery_item_added;
144 struct vlc_services_discovery_item_removed
146 input_item_t * p_item;
147 } services_discovery_item_removed;
152 /* Event callback type */
153 typedef void ( *vlc_event_callback_t )( const vlc_event_t *, void * );
155 /*****************************************************************************
157 *****************************************************************************/
160 * p_obj points to the object that owns the event manager, and from
161 * which events are sent
162 * p_obj is here to give us a libvlc instance
164 VLC_EXPORT(int, vlc_event_manager_init, ( vlc_event_manager_t * p_em,
165 void * p_obj, vlc_object_t * ));
170 VLC_EXPORT(void, vlc_event_manager_fini, ( vlc_event_manager_t * p_em ));
173 * Tells a specific event manager that it will handle event_type object
175 VLC_EXPORT(int, vlc_event_manager_register_event_type,
176 ( vlc_event_manager_t * p_em, vlc_event_type_t event_type ));
179 * Send an event to the listener attached to this p_em.
181 VLC_EXPORT(void, vlc_event_send, ( vlc_event_manager_t * p_em,
182 vlc_event_t * p_event ));
185 * Add a callback for an event.
187 VLC_EXPORT(int, vlc_event_attach, ( vlc_event_manager_t * p_event_manager,
188 vlc_event_type_t event_type,
189 vlc_event_callback_t pf_callback,
190 void *p_user_data ));
193 * Remove a callback for an event.
195 VLC_EXPORT(int, vlc_event_detach, ( vlc_event_manager_t *p_event_manager,
196 vlc_event_type_t event_type,
197 vlc_event_callback_t pf_callback,
198 void *p_user_data ));
200 #endif /* VLC_EVENTS_H */