From c2251f25cb8fd59a3969aab2a0a8bd00ae67c820 Mon Sep 17 00:00:00 2001 From: Sigmund Augdal Helberg Date: Wed, 3 Dec 2003 23:01:48 +0000 Subject: [PATCH] all: * doxygenated parts of the messages system --- include/vlc_messages.h | 62 ++++++++++++++++++++++++------------------ src/misc/messages.c | 61 +++++++++++++++++++++++++---------------- 2 files changed, 73 insertions(+), 50 deletions(-) diff --git a/include/vlc_messages.h b/include/vlc_messages.h index 2b4a6328a5..33aacaa622 100644 --- a/include/vlc_messages.h +++ b/include/vlc_messages.h @@ -4,7 +4,7 @@ * interface, such as message output. ***************************************************************************** * Copyright (C) 1999, 2000, 2001, 2002 VideoLAN - * $Id: vlc_messages.h,v 1.8 2002/12/18 11:47:35 sam Exp $ + * $Id: vlc_messages.h,v 1.9 2003/12/03 23:01:48 sigmunau Exp $ * * Authors: Vincent Seguin * Samuel Hocevar @@ -25,19 +25,25 @@ *****************************************************************************/ #include +/** + * \defgroup messages Messages + * This library provides basic functions for threads to interact with user + * interface, such as message output. + * + * @{ + */ -/***************************************************************************** - * msg_item_t - ***************************************************************************** + +/** * Store a single message. - *****************************************************************************/ + */ typedef struct { - int i_type; /* message type, see below */ + int i_type; /**< message type, see below */ int i_object_id; int i_object_type; char * psz_module; - char * psz_msg; /* the message itself */ + char * psz_msg; /**< the message itself */ #if 0 mtime_t date; /* date of the message */ @@ -48,25 +54,27 @@ typedef struct } msg_item_t; /* Message types */ -#define VLC_MSG_INFO 0 /* standard messages */ -#define VLC_MSG_ERR 1 /* error messages */ -#define VLC_MSG_WARN 2 /* warning messages */ -#define VLC_MSG_DBG 3 /* debug messages */ - -/***************************************************************************** - * msg_bank_t - ***************************************************************************** +/** standard messages */ +#define VLC_MSG_INFO 0 +/** error messages */ +#define VLC_MSG_ERR 1 +/** warning messages */ +#define VLC_MSG_WARN 2 +/** debug messages */ +#define VLC_MSG_DBG 3 + +/** * Store all data requiered by messages interfaces. - *****************************************************************************/ + */ struct msg_bank_t { - /* Message queue lock */ + /** Message queue lock */ vlc_mutex_t lock; vlc_bool_t b_configured; vlc_bool_t b_overflow; /* Message queue */ - msg_item_t msg[VLC_MSG_QSIZE]; /* message queue */ + msg_item_t msg[VLC_MSG_QSIZE]; /**< message queue */ int i_start; int i_stop; @@ -80,11 +88,9 @@ struct msg_bank_t #endif }; -/***************************************************************************** - * msg_subscription_t - ***************************************************************************** +/** * Used by interface plugins which subscribe to the message bank. - *****************************************************************************/ + */ struct msg_subscription_t { int i_start; @@ -98,10 +104,10 @@ struct msg_subscription_t * Prototypes *****************************************************************************/ VLC_EXPORT( void, __msg_Generic, ( vlc_object_t *, int, const char *, const char *, ... ) ATTRIBUTE_FORMAT( 4, 5 ) ); -VLC_EXPORT( void, __msg_Info, ( void *, const char *, ... ) ATTRIBUTE_FORMAT( 2, 3 ) ); -VLC_EXPORT( void, __msg_Err, ( void *, const char *, ... ) ATTRIBUTE_FORMAT( 2, 3 ) ); -VLC_EXPORT( void, __msg_Warn, ( void *, const char *, ... ) ATTRIBUTE_FORMAT( 2, 3 ) ); -VLC_EXPORT( void, __msg_Dbg, ( void *, const char *, ... ) ATTRIBUTE_FORMAT( 2, 3 ) ); +VLC_EXPORT( void, __msg_Info, ( vlc_object_t *, const char *, ... ) ATTRIBUTE_FORMAT( 2, 3 ) ); +VLC_EXPORT( void, __msg_Err, ( vlc_object_t *, const char *, ... ) ATTRIBUTE_FORMAT( 2, 3 ) ); +VLC_EXPORT( void, __msg_Warn, ( vlc_object_t *, const char *, ... ) ATTRIBUTE_FORMAT( 2, 3 ) ); +VLC_EXPORT( void, __msg_Dbg, ( vlc_object_t *, const char *, ... ) ATTRIBUTE_FORMAT( 2, 3 ) ); #ifdef HAVE_VARIADIC_MACROS @@ -142,3 +148,7 @@ void __msg_Destroy ( vlc_object_t * ); VLC_EXPORT( msg_subscription_t*, __msg_Subscribe, ( vlc_object_t * ) ); VLC_EXPORT( void, __msg_Unsubscribe, ( vlc_object_t *, msg_subscription_t * ) ); + +/** + * @} + */ diff --git a/src/misc/messages.c b/src/misc/messages.c index 515e51d78e..b30b51eb27 100644 --- a/src/misc/messages.c +++ b/src/misc/messages.c @@ -4,7 +4,7 @@ * modules, especially intf modules. See config.h for output configuration. ***************************************************************************** * Copyright (C) 1998-2002 VideoLAN - * $Id: messages.c,v 1.35 2003/10/08 21:01:07 gbazin Exp $ + * $Id: messages.c,v 1.36 2003/12/03 23:01:48 sigmunau Exp $ * * Authors: Vincent Seguin * Samuel Hocevar @@ -67,12 +67,12 @@ static void QueueMsg ( vlc_object_t *, int , const char *, static void FlushMsg ( msg_bank_t * ); static void PrintMsg ( vlc_object_t *, msg_item_t * ); -/***************************************************************************** - * msg_Create: initialize messages interface - ***************************************************************************** +/** + * Initialize messages interface + * * This functions has to be called before any call to other msg_* functions. * It set up the locks and the message queue if it is used. - *****************************************************************************/ + */ void __msg_Create( vlc_object_t *p_this ) { /* Message queue initialization */ @@ -96,9 +96,9 @@ void __msg_Create( vlc_object_t *p_this ) #endif } -/***************************************************************************** - * msg_Flush: flush the message queue - *****************************************************************************/ +/** + * Flush the message queue + */ void __msg_Flush( vlc_object_t *p_this ) { int i_index; @@ -119,13 +119,13 @@ void __msg_Flush( vlc_object_t *p_this ) vlc_mutex_unlock( &p_this->p_libvlc->msg_bank.lock ); } -/***************************************************************************** - * msg_Destroy: free resources allocated by msg_Create - ***************************************************************************** +/** + * Free resources allocated by msg_Create + * * This functions prints all messages remaining in queue, then free all the * resources allocated by msg_Create. * No other messages interface functions should be called after this one. - *****************************************************************************/ + */ void __msg_Destroy( vlc_object_t *p_this ) { if( p_this->p_libvlc->msg_bank.i_sub ) @@ -151,9 +151,9 @@ void __msg_Destroy( vlc_object_t *p_this ) vlc_mutex_destroy( &p_this->p_libvlc->msg_bank.lock ); } -/***************************************************************************** - * msg_Subscribe: subscribe to the message queue. - *****************************************************************************/ +/** + * Subscribe to the message queue. + */ msg_subscription_t *__msg_Subscribe( vlc_object_t *p_this ) { msg_bank_t *p_bank = &p_this->p_libvlc->msg_bank; @@ -175,9 +175,9 @@ msg_subscription_t *__msg_Subscribe( vlc_object_t *p_this ) return p_sub; } -/***************************************************************************** - * msg_Unsubscribe: unsubscribe from the message queue. - *****************************************************************************/ +/** + * Unsubscribe from the message queue. + */ void __msg_Unsubscribe( vlc_object_t *p_this, msg_subscription_t *p_sub ) { msg_bank_t *p_bank = &p_this->p_libvlc->msg_bank; @@ -231,7 +231,7 @@ void __msg_Generic( vlc_object_t *p_this, int i_type, const char *psz_module, /* Generic functions used when variadic macros are not available. */ #define DECLARE_MSG_FN( FN_NAME, FN_TYPE ) \ - void FN_NAME( void *p_this, const char *psz_format, ... ) \ + void FN_NAME( vlc_object_t *p_this, const char *psz_format, ... ) \ { \ va_list args; \ va_start( args, psz_format ); \ @@ -240,20 +240,33 @@ void __msg_Generic( vlc_object_t *p_this, int i_type, const char *psz_module, va_end( args ); \ } \ struct _ - +/** + * Output an informational message. + * \note Do not use this for debug messages + * \see input_AddInfo + */ DECLARE_MSG_FN( __msg_Info, VLC_MSG_INFO ); +/** + * Output an error message. + */ DECLARE_MSG_FN( __msg_Err, VLC_MSG_ERR ); +/** + * Output a waring message + */ DECLARE_MSG_FN( __msg_Warn, VLC_MSG_WARN ); +/** + * Output a debug message + */ DECLARE_MSG_FN( __msg_Dbg, VLC_MSG_DBG ); -/***************************************************************************** - * QueueMsg: add a message to a queue - ***************************************************************************** +/** + * Add a message to a queue + * * This function provides basic functionnalities to other msg_* functions. * It adds a message to a queue (after having printed all stored messages if it * is full). If the message can't be converted to string in memory, it issues * a warning. - *****************************************************************************/ + */ static void QueueMsg( vlc_object_t *p_this, int i_type, const char *psz_module, const char *psz_format, va_list _args ) { -- 2.39.2