home *** CD-ROM | disk | FTP | other *** search
/ mail.altrad.com / 2015.02.mail.altrad.com.tar / mail.altrad.com / TEST / vlc-2-0-5-win32.exe / sdk / include / vlc / plugins / vlc_events.h < prev    next >
C/C++ Source or Header  |  2012-12-12  |  8KB  |  253 lines
  1. /*****************************************************************************
  2.  * events.h: events definitions
  3.  * Interface used to send events.
  4.  *****************************************************************************
  5.  * Copyright (C) 2007 VLC authors and VideoLAN
  6.  * $Id: 842e204ef45aea390aa01d4488abdc89d79b0c08 $
  7.  *
  8.  * Authors: Pierre d'Herbemont
  9.  *
  10.  * This program is free software; you can redistribute it and/or modify it
  11.  * under the terms of the GNU Lesser General Public License as published by
  12.  * the Free Software Foundation; either version 2.1 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 Lesser General Public License for more details.
  19.  *
  20.  * You should have received a copy of the GNU Lesser General Public License
  21.  * along with this program; if not, write to the Free Software Foundation,
  22.  * 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. #include <vlc_meta.h>
  30.  
  31. /**
  32.  * \file
  33.  * This file is the interface definition for events
  34.  * (implementation in src/misc/events.c)
  35.  */
  36.  
  37. /*****************************************************************************
  38.  * Documentation
  39.  *****************************************************************************/
  40. /*
  41.  **** Background
  42.  *
  43.  * This implements a way to send and receive event for an object (which can be
  44.  * a simple C struct or less).
  45.  *
  46.  * This is in direct concurrency with the Variable based Callback
  47.  * (see src/misc/variables.c).
  48.  *
  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)
  56.  *
  57.  *
  58.  **** Example usage
  59.  *
  60.  * (vlc_cool_object_t doesn't need to have the VLC_COMMON_MEMBERS.)
  61.  *
  62.  * struct vlc_cool_object_t
  63.  * {
  64.  *        ...
  65.  *        vlc_event_manager_t p_event_manager;
  66.  *        ...
  67.  * }
  68.  *
  69.  * vlc_my_cool_object_new()
  70.  * {
  71.  *        ...
  72.  *        vlc_event_manager_init( &p_self->p_event_manager, p_self, p_a_libvlc_object );
  73.  *        vlc_event_manager_register_event_type(p_self->p_event_manager,
  74.  *                vlc_MyCoolObjectDidSomething, p_e)
  75.  *        ...
  76.  * }
  77.  *
  78.  * vlc_my_cool_object_release()
  79.  * {
  80.  *         ...
  81.  *         vlc_event_manager_fini( &p_self->p_event_manager );
  82.  *         ...
  83.  * }
  84.  *
  85.  * vlc_my_cool_object_do_something()
  86.  * {
  87.  *        ...
  88.  *        vlc_event_t event;
  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 );
  92.  * }
  93.  * */
  94.  
  95.   /*****************************************************************************
  96.  * Event Type
  97.  *****************************************************************************/
  98.  
  99. /* Private structure defined in misc/events.c */
  100. struct vlc_event_listeners_group_t;
  101.  
  102. /* Event manager type */
  103. typedef struct vlc_event_manager_t
  104. {
  105.     void * p_obj;
  106.     vlc_mutex_t object_lock;
  107.     vlc_mutex_t event_sending_lock;
  108.     DECL_ARRAY(struct vlc_event_listeners_group_t *) listeners_groups;
  109. } vlc_event_manager_t;
  110.  
  111. /* List of event */
  112. typedef enum vlc_event_type_t {
  113.     /* Input (thread) events */
  114.     vlc_InputStateChanged,
  115.     vlc_InputSelectedStreamChanged,
  116.  
  117.     /* Input item events */
  118.     vlc_InputItemMetaChanged,
  119.     vlc_InputItemSubItemAdded,
  120.     vlc_InputItemSubItemTreeAdded,
  121.     vlc_InputItemDurationChanged,
  122.     vlc_InputItemPreparsedChanged,
  123.     vlc_InputItemNameChanged,
  124.     vlc_InputItemInfoChanged,
  125.     vlc_InputItemErrorWhenReadingChanged,
  126.  
  127.     /* Service Discovery event */
  128.     vlc_ServicesDiscoveryItemAdded,
  129.     vlc_ServicesDiscoveryItemRemoved,
  130.     vlc_ServicesDiscoveryStarted,
  131.     vlc_ServicesDiscoveryEnded
  132. } vlc_event_type_t;
  133.  
  134. /* Event definition */
  135. typedef struct vlc_event_t
  136. {
  137.     vlc_event_type_t type;
  138.     void * p_obj; /* Sender object, automatically filled by vlc_event_send() */
  139.     union vlc_event_type_specific
  140.     {
  141.         /* Input (thread) events */
  142.         struct vlc_input_state_changed
  143.         {
  144.             int new_state;
  145.         } input_state_changed;
  146.         struct vlc_input_selected_stream_changed
  147.         {
  148.             void * unused;
  149.         } input_selected_stream_changed;
  150.  
  151.         /* Input item events */
  152.         struct vlc_input_item_meta_changed
  153.         {
  154.             vlc_meta_type_t meta_type;
  155.         } input_item_meta_changed;
  156.         struct vlc_input_item_subitem_added
  157.         {
  158.             input_item_t * p_new_child;
  159.         } input_item_subitem_added;
  160.         struct vlc_input_item_subitem_tree_added
  161.         {
  162.             input_item_node_t * p_root;
  163.         } input_item_subitem_tree_added;
  164.         struct vlc_input_item_duration_changed
  165.         {
  166.             mtime_t new_duration;
  167.         } input_item_duration_changed;
  168.         struct vlc_input_item_preparsed_changed
  169.         {
  170.             int new_status;
  171.         } input_item_preparsed_changed;
  172.         struct vlc_input_item_name_changed
  173.         {
  174.             const char * new_name;
  175.         } input_item_name_changed;
  176.         struct vlc_input_item_info_changed
  177.         {
  178.             void * unused;
  179.         } input_item_info_changed;
  180.         struct input_item_error_when_reading_changed
  181.         {
  182.             bool new_value;
  183.         } input_item_error_when_reading_changed;
  184.  
  185.         /* Service discovery events */
  186.         struct vlc_services_discovery_item_added
  187.         {
  188.             input_item_t * p_new_item;
  189.             const char * psz_category;
  190.         } services_discovery_item_added;
  191.         struct vlc_services_discovery_item_removed
  192.         {
  193.             input_item_t * p_item;
  194.         } services_discovery_item_removed;
  195.         struct vlc_services_discovery_started
  196.         {
  197.             void * unused;
  198.         } services_discovery_started;
  199.         struct vlc_services_discovery_ended
  200.         {
  201.             void * unused;
  202.         } services_discovery_ended;
  203.  
  204.     } u;
  205. } vlc_event_t;
  206.  
  207. /* Event callback type */
  208. typedef void ( *vlc_event_callback_t )( const vlc_event_t *, void * );
  209.  
  210.  /*****************************************************************************
  211.  * Event manager
  212.  *****************************************************************************/
  213.  
  214. /*
  215.  * p_obj points to the object that owns the event manager, and from
  216.  * which events are sent
  217.  */
  218. VLC_API int vlc_event_manager_init( vlc_event_manager_t * p_em, void * p_obj );
  219.  
  220. /*
  221.  * Destroy
  222.  */
  223. VLC_API void vlc_event_manager_fini( vlc_event_manager_t * p_em );
  224.  
  225. /*
  226.  * Tells a specific event manager that it will handle event_type object
  227.  */
  228. VLC_API int vlc_event_manager_register_event_type( vlc_event_manager_t * p_em,
  229.                                                    vlc_event_type_t );
  230.  
  231. /*
  232.  * Send an event to the listener attached to this p_em.
  233.  */
  234. VLC_API void vlc_event_send( vlc_event_manager_t * p_em, vlc_event_t * );
  235.  
  236. /*
  237.  * Add a callback for an event.
  238.  */
  239. VLC_API int vlc_event_attach( vlc_event_manager_t * p_event_manager,
  240.                               vlc_event_type_t event_type,
  241.                               vlc_event_callback_t pf_callback,
  242.                               void *p_user_data );
  243.  
  244. /*
  245.  * Remove a callback for an event.
  246.  */
  247. VLC_API void vlc_event_detach( vlc_event_manager_t *p_event_manager,
  248.                                vlc_event_type_t event_type,
  249.                                vlc_event_callback_t pf_callback,
  250.                                void *p_user_data );
  251.  
  252. #endif /* VLC_EVENTS_H */
  253.