VLC  4.0.0-dev
vlc_events.h
Go to the documentation of this file.
1 /*****************************************************************************
2  * vlc_events.h: events definitions
3  * Interface used to send events.
4  *****************************************************************************
5  * Copyright (C) 2007 VLC authors and VideoLAN
6  *
7  * Authors: Pierre d'Herbemont
8  *
9  * This program is free software; you can redistribute it and/or modify it
10  * under the terms of the GNU Lesser General Public License as published by
11  * the Free Software Foundation; either version 2.1 of the License, or
12  * (at your option) any later version.
13  *
14  * This program is distributed in the hope that it will be useful,
15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17  * GNU Lesser General Public License for more details.
18  *
19  * You should have received a copy of the GNU Lesser General Public License
20  * along with this program; if not, write to the Free Software Foundation,
21  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
22  *****************************************************************************/
23 
24 #ifndef VLC_EVENTS_H
25 # define VLC_EVENTS_H
26 
27 #include <vlc_arrays.h>
28 #include <vlc_meta.h>
29 
30 /**
31  * \file
32  * This file is the interface definition for events
33  * (implementation in src/misc/events.c)
34  */
35 
36 /*****************************************************************************
37  * Documentation
38  *****************************************************************************/
39 /*
40  **** Background
41  *
42  * This implements a way to send and receive event for an object (which can be
43  * a simple C struct or less).
44  *
45  * This is in direct concurrency with the Variable based Callback
46  * (see src/misc/variables.c).
47  *
48  * It has the following advantages over Variable based Callback:
49  * - No need to implement the whole vlc_object_t in the object,
50  * thus it reduce it size. This is especially true for input_item_t which
51  * doesn't have vlc_object_t. 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)
55  *
56  *
57  **** Example usage
58  *
59  * (vlc_cool_object_t doesn't need to have the vlc_object_t.)
60  *
61  * struct vlc_cool_object_t
62  * {
63  * ...
64  * vlc_event_manager_t p_event_manager;
65  * ...
66  * }
67  *
68  * vlc_my_cool_object_new()
69  * {
70  * ...
71  * vlc_event_manager_init( &p_self->p_event_manager, p_self, p_a_libvlc_object );
72  * ...
73  * }
74  *
75  * vlc_my_cool_object_release()
76  * {
77  * ...
78  * vlc_event_manager_fini( &p_self->p_event_manager );
79  * ...
80  * }
81  *
82  * vlc_my_cool_object_do_something()
83  * {
84  * ...
85  * vlc_event_t event;
86  * event.type = vlc_MyCoolObjectDidSomething;
87  * event.u.my_cool_object_did_something.what_it_did = kSomething;
88  * vlc_event_send( &p_self->p_event_manager, &event );
89  * }
90  * */
91 
92  /*****************************************************************************
93  * Event Type
94  *****************************************************************************/
95 
96 /* List of event */
97 typedef enum vlc_event_type_t {
98  /* Input item events */
106 
107 typedef struct vlc_event_listeners_group_t
108 {
111 
112 /* Event manager type */
113 typedef struct vlc_event_manager_t
114 {
115  void * p_obj;
119 
120 /* Event definition */
121 typedef struct vlc_event_t
122 {
123  vlc_event_type_t type;
124  void * p_obj; /* Sender object, automatically filled by vlc_event_send() */
126  {
127  /* Input item events */
129  {
130  vlc_meta_type_t meta_type;
131  } input_item_meta_changed;
133  {
134  input_item_t * p_new_child;
135  } input_item_subitem_added;
137  {
138  input_item_node_t * p_root;
139  } input_item_subitem_tree_added;
141  {
142  vlc_tick_t new_duration;
143  } input_item_duration_changed;
145  {
146  int new_status;
147  } input_item_preparsed_changed;
149  {
150  const char * new_name;
151  } input_item_name_changed;
153  {
154  void * unused;
155  } input_item_info_changed;
157  {
158  bool new_value;
161  {
162  int new_status;
164  } u;
165 } vlc_event_t;
166 
167 /* Event callback type */
168 typedef void ( *vlc_event_callback_t )( const vlc_event_t *, void * );
170  /*****************************************************************************
171  * Event manager
172  *****************************************************************************/
173 
174 /*
175  * p_obj points to the object that owns the event manager, and from
176  * which events are sent
177  */
178 void vlc_event_manager_init( vlc_event_manager_t * p_em, void * p_obj );
179 
180 /*
181  * Destroy
182  */
184 
185 /*
186  * Send an event to the listener attached to this p_em.
187  */
189 
190 /*
191  * Add a callback for an event.
192  */
193 VLC_API int vlc_event_attach( vlc_event_manager_t * p_event_manager,
194  vlc_event_type_t event_type,
195  vlc_event_callback_t pf_callback,
196  void *p_user_data );
197 
198 /*
199  * Remove a callback for an event.
200  */
201 VLC_API void vlc_event_detach( vlc_event_manager_t *p_event_manager,
202  vlc_event_type_t event_type,
203  vlc_event_callback_t pf_callback,
204  void *p_user_data );
205 
206 #endif /* VLC_EVENTS_H */
Definition: vlc_events.h:105
struct vlc_event_listeners_group_t vlc_event_listeners_group_t
struct vlc_event_t vlc_event_t
Definition: vlc_events.h:102
Describes an input and is used to spawn input_thread_t objects.
Definition: vlc_input_item.h:77
This file defines functions and structures for stream meta-data in vlc.
Definition: vlc_input_item.h:191
Definition: vlc_events.h:104
vlc_mutex_t lock
Definition: rand.c:32
Definition: vlc_events.h:114
Definition: vlc_events.h:126
Definition: vlc_events.h:101
struct vlc_event_listeners_group_t::@213 listeners
int64_t vlc_tick_t
High precision date or time interval.
Definition: vlc_tick.h:45
vlc_event_type_t
Definition: vlc_events.h:98
int vlc_event_attach(vlc_event_manager_t *p_event_manager, vlc_event_type_t event_type, vlc_event_callback_t pf_callback, void *p_user_data)
Add a callback for an event.
Definition: events.c:118
Mutex.
Definition: vlc_threads.h:243
struct vlc_event_manager_t vlc_event_manager_t
#define VLC_API
Definition: fourcc_gen.c:31
void(* vlc_event_callback_t)(const vlc_event_t *, void *)
Definition: vlc_events.h:169
Definition: vlc_events.h:122
#define DECL_ARRAY(type)
Definition: vlc_arrays.h:181
Definition: vlc_events.h:103
Definition: vlc_events.h:108
void vlc_event_send(vlc_event_manager_t *p_em, vlc_event_t *)
Send an event to the listener attached to this p_em.
Definition: events.c:97
void vlc_event_manager_fini(vlc_event_manager_t *p_em)
Destroy the event manager.
Definition: events.c:79
Definition: events.c:48
This file defines functions, structures and macros for handling arrays in vlc.
Definition: vlc_events.h:100
void vlc_event_manager_init(vlc_event_manager_t *p_em, void *p_obj)
Initialize event manager object p_obj is the object that contains the event manager.
Definition: events.c:65
vlc_meta_type_t
Definition: vlc_meta.h:33
void vlc_event_detach(vlc_event_manager_t *p_event_manager, vlc_event_type_t event_type, vlc_event_callback_t pf_callback, void *p_user_data)
Remove a callback for an event.
Definition: events.c:143