home *** CD-ROM | disk | FTP | other *** search
/ PCGUIA 2010 Software/Programs / PCGuia_programas.iso / Software / Utils / VLC Media Player / vlc-1.0.3-win32.exe / sdk / include / vlc / plugins / vlc_events.h < prev    next >
Encoding:
C/C++ Source or Header  |  2009-10-30  |  8.1 KB  |  260 lines
  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. #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.     vlc_object_t *p_parent_object;
  109.     DECL_ARRAY(struct vlc_event_listeners_group_t *) listeners_groups;
  110. } vlc_event_manager_t;
  111.  
  112. /* List of event */
  113. /* Be sure to keep sync-ed with misc/events.c debug name table */
  114. typedef enum vlc_event_type_t {
  115.     /* Input (thread) events */
  116.     vlc_InputStateChanged,
  117.     vlc_InputSelectedStreamChanged,
  118.  
  119.     /* Input item events */
  120.     vlc_InputItemMetaChanged,
  121.     vlc_InputItemSubItemAdded,
  122.     vlc_InputItemDurationChanged,
  123.     vlc_InputItemPreparsedChanged,
  124.     vlc_InputItemNameChanged,
  125.     vlc_InputItemInfoChanged,
  126.     vlc_InputItemErrorWhenReadingChanged,
  127.  
  128.     /* Service Discovery event */
  129.     vlc_ServicesDiscoveryItemAdded,
  130.     vlc_ServicesDiscoveryItemRemoved,
  131.     vlc_ServicesDiscoveryStarted,
  132.     vlc_ServicesDiscoveryEnded
  133. } vlc_event_type_t;
  134.  
  135. /* Event definition */
  136. typedef struct vlc_event_t
  137. {
  138.     vlc_event_type_t type;
  139.     void * p_obj; /* Sender object, automatically filled by vlc_event_send() */
  140.     union vlc_event_type_specific
  141.     {
  142.         /* Input (thread) events */
  143.         struct vlc_input_state_changed
  144.         {
  145.             int new_state;
  146.         } input_state_changed;
  147.         struct vlc_input_selected_stream_changed
  148.         {
  149.             void * unused;
  150.         } input_selected_stream_changed;
  151.  
  152.         /* Input item events */
  153.         struct vlc_input_item_meta_changed
  154.         {
  155.             vlc_meta_type_t meta_type;
  156.         } input_item_meta_changed;
  157.         struct vlc_input_item_subitem_added
  158.         {
  159.             input_item_t * p_new_child;
  160.         } input_item_subitem_added;
  161.         struct vlc_input_item_duration_changed
  162.         {
  163.             mtime_t new_duration;
  164.         } input_item_duration_changed;
  165.         struct vlc_input_item_preparsed_changed
  166.         {
  167.             int new_status;
  168.         } input_item_preparsed_changed;
  169.         struct vlc_input_item_name_changed
  170.         {
  171.             const char * new_name;
  172.         } input_item_name_changed;
  173.         struct vlc_input_item_info_changed
  174.         {
  175.             void * unused;
  176.         } input_item_info_changed;
  177.         struct input_item_error_when_reading_changed
  178.         {
  179.             bool new_value;
  180.         } input_item_error_when_reading_changed;
  181.  
  182.         /* Service discovery events */
  183.         struct vlc_services_discovery_item_added
  184.         {
  185.             input_item_t * p_new_item;
  186.             const char * psz_category;
  187.         } services_discovery_item_added;
  188.         struct vlc_services_discovery_item_removed
  189.         {
  190.             input_item_t * p_item;
  191.         } services_discovery_item_removed;
  192.         struct vlc_services_discovery_started
  193.         {
  194.             void * unused;
  195.         } services_discovery_started;
  196.         struct vlc_services_discovery_ended
  197.         {
  198.             void * unused;
  199.         } services_discovery_ended;
  200.  
  201.     } u;
  202. } vlc_event_t;
  203.  
  204. /* Event callback type */
  205. typedef void ( *vlc_event_callback_t )( const vlc_event_t *, void * );
  206.  
  207.  /*****************************************************************************
  208.  * Event manager
  209.  *****************************************************************************/
  210.  
  211. /*
  212.  * p_obj points to the object that owns the event manager, and from
  213.  * which events are sent
  214.  * p_obj is here to give us a libvlc instance
  215.  */
  216. #define vlc_event_manager_init_with_vlc_object(a,b) \
  217.             vlc_event_manager_init( a, b, b )
  218.  
  219. #define vlc_event_manager_init(a,b,c) \
  220.             __vlc_event_manager_init(a, b, VLC_OBJECT(c))
  221. VLC_EXPORT(int, __vlc_event_manager_init, ( vlc_event_manager_t * p_em,
  222.                                           void * p_obj, vlc_object_t * ));
  223.  
  224. /*
  225.  * Destroy
  226.  */
  227. VLC_EXPORT(void, vlc_event_manager_fini, ( vlc_event_manager_t * p_em ));
  228.  
  229. /*
  230.  * Tells a specific event manager that it will handle event_type object
  231.  */
  232. VLC_EXPORT(int, vlc_event_manager_register_event_type,
  233.                 ( vlc_event_manager_t * p_em, vlc_event_type_t event_type ));
  234.  
  235. /*
  236.  * Send an event to the listener attached to this p_em.
  237.  */
  238. VLC_EXPORT(void, vlc_event_send, ( vlc_event_manager_t * p_em,
  239.                                    vlc_event_t * p_event ));
  240.  
  241. /*
  242.  * Add a callback for an event.
  243.  */
  244. #define vlc_event_attach(a, b, c, d) __vlc_event_attach(a, b, c, d, #c)
  245. VLC_EXPORT(int, __vlc_event_attach, ( vlc_event_manager_t * p_event_manager,
  246.                                       vlc_event_type_t event_type,
  247.                                       vlc_event_callback_t pf_callback,
  248.                                       void *p_user_data,
  249.                                       const char * psz_debug_name ));
  250.  
  251. /*
  252.  * Remove a callback for an event.
  253.  */
  254. VLC_EXPORT(int, vlc_event_detach, ( vlc_event_manager_t *p_event_manager,
  255.                                     vlc_event_type_t event_type,
  256.                                     vlc_event_callback_t pf_callback,
  257.                                     void *p_user_data ));
  258.  
  259. #endif /* VLC_EVENTS_H */
  260.