X-Git-Url: http://research.m1stereo.tv/gitweb?a=blobdiff_plain;f=src%2Fframework%2Fmlt_events.c;h=6732ebda761d12fcaf1b29912f08e15190d65123;hb=1dbd6a7c0bf508fe28e7be1d851311fd880e1742;hp=a9ee7433c6b6ce825bb2bd3230d534a551c1c10e;hpb=48792e5e48a10b3e8041d09638d50023e0cb9305;p=melted diff --git a/src/framework/mlt_events.c b/src/framework/mlt_events.c index a9ee743..6732ebd 100644 --- a/src/framework/mlt_events.c +++ b/src/framework/mlt_events.c @@ -1,21 +1,23 @@ -/* - * mlt_events.h -- event handling - * Copyright (C) 2004-2005 Ushodaya Enterprises Limited - * Author: Charles Yates +/** + * \file mlt_events.c + * \brief event handling * - * This program is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation; either version 2 of the License, or - * (at your option) any later version. + * Copyright (C) 2004-2008 Ushodaya Enterprises Limited + * \author Charles Yates * - * This program is distributed in the hope that it will be useful, + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2.1 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software Foundation, - * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + * You should have received a copy of the GNU Lesser General Public + * License along with this library; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ #include @@ -26,16 +28,23 @@ #include "mlt_properties.h" #include "mlt_events.h" -/** Memory leak checks. -*/ +/* Memory leak checks. */ -//#define _MLT_EVENT_CHECKS_ +#undef _MLT_EVENT_CHECKS_ #ifdef _MLT_EVENT_CHECKS_ static int events_created = 0; static int events_destroyed = 0; #endif +/** \brief Events class + * + * Events provide messages and notifications between services and the application. + * A service can register an event and fire/send it upon certain conditions or times. + * Likewise, a service or an application can listen/receive specific events on specific + * services. + */ + struct mlt_events_struct { mlt_properties owner; @@ -44,6 +53,10 @@ struct mlt_events_struct typedef struct mlt_events_struct *mlt_events; +/** \brief Event class + * + */ + struct mlt_event_struct { mlt_events owner; @@ -54,7 +67,10 @@ struct mlt_event_struct }; /** Increment the reference count on this event. -*/ + * + * \public \memberof mlt_event_struct + * \param this an event + */ void mlt_event_inc_ref( mlt_event this ) { @@ -63,7 +79,10 @@ void mlt_event_inc_ref( mlt_event this ) } /** Increment the block count on this event. -*/ + * + * \public \memberof mlt_event_struct + * \param this an event + */ void mlt_event_block( mlt_event this ) { @@ -72,7 +91,10 @@ void mlt_event_block( mlt_event this ) } /** Decrement the block count on this event. -*/ + * + * \public \memberof mlt_event_struct + * \param this an event + */ void mlt_event_unblock( mlt_event this ) { @@ -81,7 +103,10 @@ void mlt_event_unblock( mlt_event this ) } /** Close this event. -*/ + * + * \public \memberof mlt_event_struct + * \param this an event + */ void mlt_event_close( mlt_event this ) { @@ -100,7 +125,7 @@ void mlt_event_close( mlt_event this ) } } -/** Forward declaration to private functions. +/* Forward declaration to private functions. */ static mlt_events mlt_events_fetch( mlt_properties ); @@ -108,7 +133,10 @@ static void mlt_events_store( mlt_properties, mlt_events ); static void mlt_events_close( mlt_events ); /** Initialise the events structure. -*/ + * + * \public \memberof mlt_events_struct + * \param this a properties list + */ void mlt_events_init( mlt_properties this ) { @@ -122,7 +150,13 @@ void mlt_events_init( mlt_properties this ) } /** Register an event and transmitter. -*/ + * + * \public \memberof mlt_events_struct + * \param this a properties list + * \param id the name of an event + * \param transmitter the callback function to send an event message + * \return true if there was an error + */ int mlt_events_register( mlt_properties this, char *id, mlt_transmitter transmitter ) { @@ -141,7 +175,13 @@ int mlt_events_register( mlt_properties this, char *id, mlt_transmitter transmit } /** Fire an event. -*/ + * + * This takes a variable number of arguments to supply to the listener. + + * \public \memberof mlt_events_struct + * \param this a properties list + * \param id the name of an event + */ void mlt_events_fire( mlt_properties this, char *id, ... ) { @@ -182,7 +222,14 @@ void mlt_events_fire( mlt_properties this, char *id, ... ) } /** Register a listener. -*/ + * + * \public \memberof mlt_events_struct + * \param this a properties list + * \param service an opaque pointer + * \param id the name of the event to listen for + * \param listener the callback to receive an event message + * \return + */ mlt_event mlt_events_listen( mlt_properties this, void *service, char *id, mlt_listener listener ) { @@ -238,7 +285,11 @@ mlt_event mlt_events_listen( mlt_properties this, void *service, char *id, mlt_l } /** Block all events for a given service. -*/ + * + * \public \memberof mlt_events_struct + * \param this a properties list + * \param service an opaque pointer + */ void mlt_events_block( mlt_properties this, void *service ) { @@ -265,7 +316,11 @@ void mlt_events_block( mlt_properties this, void *service ) } /** Unblock all events for a given service. -*/ + * + * \public \memberof mlt_events_struct + * \param this a properties list + * \param service an opaque pointer + */ void mlt_events_unblock( mlt_properties this, void *service ) { @@ -292,7 +347,11 @@ void mlt_events_unblock( mlt_properties this, void *service ) } /** Disconnect all events for a given service. -*/ + * + * \public \memberof mlt_events_struct + * \param this a properties list + * \param service an opaque pointer + */ void mlt_events_disconnect( mlt_properties this, void *service ) { @@ -319,6 +378,8 @@ void mlt_events_disconnect( mlt_properties this, void *service ) } } +/** \brief private to mlt_events_struct, used by mlt_events_wait_for() */ + typedef struct { int done; @@ -327,6 +388,13 @@ typedef struct } condition_pair; +/** The event listener callback for the wait functions. + * + * \private \memberof mlt_events_struct + * \param this a properties list + * \param pair a condition pair + */ + static void mlt_events_listen_for( mlt_properties this, condition_pair *pair ) { pthread_mutex_lock( &pair->mutex ); @@ -337,6 +405,14 @@ static void mlt_events_listen_for( mlt_properties this, condition_pair *pair ) } } +/** Prepare to wait for an event. + * + * \public \memberof mlt_events_struct + * \param this a properties list + * \param id the name of the event to wait for + * \return an event + */ + mlt_event mlt_events_setup_wait_for( mlt_properties this, char *id ) { condition_pair *pair = malloc( sizeof( condition_pair ) ); @@ -347,6 +423,13 @@ mlt_event mlt_events_setup_wait_for( mlt_properties this, char *id ) return mlt_events_listen( this, pair, id, ( mlt_listener )mlt_events_listen_for ); } +/** Wait for an event. + * + * \public \memberof mlt_events_struct + * \param this a properties list + * \param event an event + */ + void mlt_events_wait_for( mlt_properties this, mlt_event event ) { if ( event != NULL ) @@ -356,6 +439,13 @@ void mlt_events_wait_for( mlt_properties this, mlt_event event ) } } +/** Cleanup after waiting for an event. + * + * \public \memberof mlt_events_struct + * \param this a properties list + * \param event an event + */ + void mlt_events_close_wait_for( mlt_properties this, mlt_event event ) { if ( event != NULL ) @@ -370,7 +460,11 @@ void mlt_events_close_wait_for( mlt_properties this, mlt_event event ) } /** Fetch the events object. -*/ + * + * \private \memberof mlt_events_struct + * \param this a properties list + * \return an events object + */ static mlt_events mlt_events_fetch( mlt_properties this ) { @@ -381,7 +475,11 @@ static mlt_events mlt_events_fetch( mlt_properties this ) } /** Store the events object. -*/ + * + * \private \memberof mlt_events_struct + * \param this a properties list + * \param events an events object + */ static void mlt_events_store( mlt_properties this, mlt_events events ) { @@ -390,7 +488,10 @@ static void mlt_events_store( mlt_properties this, mlt_events events ) } /** Close the events object. -*/ + * + * \private \memberof mlt_events_struct + * \param events an events object + */ static void mlt_events_close( mlt_events events ) { @@ -400,4 +501,3 @@ static void mlt_events_close( mlt_events events ) free( events ); } } -