git.sesse.net Git - vlc/blob - include/vlc_events.h

   1 /*****************************************************************************
   2  * events.h: events definitions
   3  * Interface used to send events.
   4  *****************************************************************************
   5  * Copyright (C) 2007 the VideoLAN team
   6  * $Id$
   7  *
   8  * Authors: Pierre d'Herbemont
   9  *
  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.
  14  *
  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.
  19  *
  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  *****************************************************************************/
  24
  25 #ifndef VLC_EVENTS_H
  26 # define VLC_EVENTS_H
  27
  28 #include <vlc_arrays.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_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)
  55  *
  56  *
  57  **** Example usage
  58  *
  59  * (vlc_cool_object_t doesn't need to have the VLC_COMMON_MEMBERS.)
  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_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)
  74  *        ...
  75  * }
  76  *
  77  * vlc_my_cool_object_release()
  78  * {
  79  *         ...
  80  *         vlc_event_manager_release( p_self->p_event_manager );
  81  *         ...
  82  * }
  83  *
  84  * vlc_my_cool_object_do_something()
  85  * {
  86  *        ...
  87  *        vlc_event_t event;
  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 );
  91  * }
  92  * */
  93
  94   /*****************************************************************************
  95  * Event Type
  96  *****************************************************************************/
  97
  98 /* Private structure defined in misc/events.c */
  99 struct vlc_event_listeners_group_t;
 100
 101 /* Event manager type */
 102 typedef struct vlc_event_manager_t
 103 {
 104     void * p_obj;
 105     DECL_ARRAY(struct vlc_event_listeners_group_t *) listeners_groups;
 106 } vlc_event_manager_t;
 107
 108 /* List of event */
 109 typedef enum vlc_event_type_t {
 110     vlc_InputItemMetaChanged
 111 } vlc_event_type_t;
 112
 113 /* Event definition */
 114 typedef struct vlc_event_t
 115 {
 116     vlc_event_type_t type;
 117     void * p_obj; /* Sender object, automatically filled by event_Send() */
 118     union event_type_specific
 119     {
 120         struct
 121         {
 122             int meta; /* One of the meta identified in include/vlc_meta.h */
 123         } input_item_meta_changed;
 124     } u;
 125 } vlc_event_t;
 126
 127 /* Event callback type */
 128 typedef void ( *vlc_event_callback_t )( const vlc_event_t *, void * );
 129
 130  /*****************************************************************************
 131  * Event manager
 132  *****************************************************************************/
 133
 134 /*
 135  * p_obj points to the object that owns the event manager, and from
 136  * which events are sent
 137  */
 138 int event_manager_Create( vlc_event_manager_t * p_em, void * p_obj );
 139
 140 /*
 141  * Destroy
 142  */
 143 void event_manager_Destroy( vlc_event_manager_t * p_em );
 144
 145 /*
 146  * Tells a specific event manager that it will handle event_type object
 147  */
 148 int event_manager_RegisterEventType( vlc_event_manager_t * p_em,
 149                                      vlc_event_type_t event_type );
 150
 151 /*
 152  * Send an event to the listener attached to this p_em.
 153  */
 154 void event_Send( vlc_event_manager_t * p_em, vlc_event_t * p_event );
 155
 156 /*
 157  * Add a callback for an event.
 158  */
 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,
 162                   void *p_user_data );
 163
 164 /*
 165  * Remove a callback for an event.
 166  */
 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,
 170                    void *p_user_data );
 171
 172 #endif /* VLC_EVENTS_H */