VLC  4.0.0-dev
vlc_messages.h
Go to the documentation of this file.
1 /*****************************************************************************
2  * vlc_messages.h: messages interface
3  * This library provides basic functions for threads to interact with user
4  * interface, such as message output.
5  *****************************************************************************
6  * Copyright (C) 1999, 2000, 2001, 2002 VLC authors and VideoLAN
7  *
8  * Authors: Vincent Seguin <seguin@via.ecp.fr>
9  * Samuel Hocevar <sam@zoy.org>
10  *
11  * This program is free software; you can redistribute it and/or modify it
12  * under the terms of the GNU Lesser General Public License as published by
13  * the Free Software Foundation; either version 2.1 of the License, or
14  * (at your option) any later version.
15  *
16  * This program is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19  * GNU Lesser General Public License for more details.
20  *
21  * You should have received a copy of the GNU Lesser General Public License
22  * along with this program; if not, write to the Free Software Foundation,
23  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
24  *****************************************************************************/
25 
26 #ifndef VLC_MESSAGES_H_
27 #define VLC_MESSAGES_H_
28 
29 #include <stdarg.h>
30 
31 /**
32  * \defgroup messages Logging
33  * \ingroup os
34  * \brief Message logs
35  *
36  * Functions for modules to emit log messages.
37  *
38  * @{
39  * \file
40  * Logging functions
41  */
42 
43 /** Message types */
44 enum vlc_log_type
45 {
46  VLC_MSG_INFO=0, /**< Important information */
47  VLC_MSG_ERR, /**< Error */
48  VLC_MSG_WARN, /**< Warning */
49  VLC_MSG_DBG, /**< Debug */
50 };
51 
52 /**
53  * Log message
54  */
55 typedef struct vlc_log_t
56 {
57  uintptr_t i_object_id; /**< Emitter (temporarily) unique object ID or 0 */
58  const char *psz_object_type; /**< Emitter object type name */
59  const char *psz_module; /**< Emitter module (source code) */
60  const char *psz_header; /**< Additional header (used by VLM media) */
61  const char *file; /**< Source code file name or NULL */
62  int line; /**< Source code file line number or -1 */
63  const char *func; /**< Source code calling function name or NULL */
64  unsigned long tid; /**< Emitter thread ID */
66 
67 /**
68  * Emit a log message.
69  *
70  * \param obj VLC object emitting the message or NULL
71  * \param type VLC_MSG_* message type (info, error, warning or debug)
72  * \param module name of module from which the message come
73  * (normally vlc_module_name)
74  * \param file source module file name (normally __FILE__) or NULL
75  * \param line function call source line number (normally __LINE__) or 0
76  * \param func calling function name (normally __func__) or NULL
77  * \param format printf-like message format
78  */
79 VLC_API void vlc_object_Log(vlc_object_t *obj, int prio, const char *module,
80  const char *file, unsigned line, const char *func,
81  const char *format, ...) VLC_FORMAT(7, 8);
82 
83 /**
84  * Emit a log message.
85  *
86  * This function is the variable argument list equivalent to vlc_object_Log().
87  */
88 VLC_API void vlc_object_vaLog(vlc_object_t *obj, int prio, const char *module,
89  const char *file, unsigned line, const char *func,
90  const char *format, va_list ap);
91 
92 #define msg_GenericVa(o, p, fmt, ap) \
93  vlc_object_vaLog(VLC_OBJECT(o), p, vlc_module_name, __FILE__, __LINE__, \
94  __func__, fmt, ap)
95 
96 #define msg_Generic(o, p, ...) \
97  vlc_object_Log(VLC_OBJECT(o), p, vlc_module_name, __FILE__, __LINE__, \
98  __func__, __VA_ARGS__)
99 #define msg_Info(p_this, ...) \
100  msg_Generic(p_this, VLC_MSG_INFO, __VA_ARGS__)
101 #define msg_Err(p_this, ...) \
102  msg_Generic(p_this, VLC_MSG_ERR, __VA_ARGS__)
103 #define msg_Warn(p_this, ...) \
104  msg_Generic(p_this, VLC_MSG_WARN, __VA_ARGS__)
105 #define msg_Dbg(p_this, ...) \
106  msg_Generic(p_this, VLC_MSG_DBG, __VA_ARGS__)
107 
108 extern const char vlc_module_name[];
109 
110 VLC_API const char *vlc_strerror(int);
111 VLC_API const char *vlc_strerror_c(int);
112 
113 /**
114  * \defgroup logger Logger
115  * \brief Message log back-end.
116  *
117  * @{
118  */
119 
120 struct vlc_logger;
121 
122 VLC_API void vlc_Log(struct vlc_logger *const *logger, int prio,
123  const char *type, const char *module,
124  const char *file, unsigned line, const char *func,
125  const char *format, ...) VLC_FORMAT(8, 9);
126 VLC_API void vlc_vaLog(struct vlc_logger *const *logger, int prio,
127  const char *type, const char *module,
128  const char *file, unsigned line, const char *func,
129  const char *format, va_list ap);
130 
131 #define vlc_log_gen(logger, prio, ...) \
132  vlc_Log(&(logger), prio, "generic", vlc_module_name, \
133  __FILE__, __LINE__, __func__, __VA_ARGS__)
134 #define vlc_info(logger, ...) vlc_log_gen(logger, VLC_MSG_INFO, __VA_ARGS__)
135 #define vlc_error(logger, ...) vlc_log_gen(logger, VLC_MSG_ERR, __VA_ARGS__)
136 #define vlc_warning(logger, ...) vlc_log_gen(logger, VLC_MSG_WARN, __VA_ARGS__)
137 #define vlc_debug(logger, ...) vlc_log_gen(logger, VLC_MSG_DBG, __VA_ARGS__)
139 /**
140  * Message logging callback signature.
141  * \param data data pointer as provided to vlc_msg_SetCallback().
142  * \param type message type (VLC_MSG_* values from enum vlc_log_type)
143  * \param item meta information
144  * \param fmt format string
145  * \param args format string arguments
146  */
147 typedef void (*vlc_log_cb) (void *data, int type, const vlc_log_t *item,
148  const char *fmt, va_list args);
149 
151 {
152  vlc_log_cb log;
153  void (*destroy)(void *data);
154 };
155 
156 /**
157  * Creates a prefixed message log.
158  *
159  * This creates a message log that prefixes all its messages and forwards them
160  * in another log.
161  * \param parent message log to inject into
162  * \param str nul-terminated prefix (a.k.a. "header")
163  * \return a new message log on success or @c NULL on error
164  */
165 VLC_API struct vlc_logger *vlc_LogHeaderCreate(struct vlc_logger *parent,
166  const char *str) VLC_USED;
167 
168 /**
169  * Destroys a message log.
170  */
171 VLC_API void vlc_LogDestroy(struct vlc_logger *);
172 
173 /**
174  * @}
175  */
176 /**
177  * @}
178  */
179 #endif
Important information.
Definition: vlc_messages.h:47
vlc_log_type
Message types.
Definition: vlc_messages.h:45
void vlc_LogDestroy(struct vlc_logger *)
Destroys a message log.
Definition: messages.c:586
const char * func
Source code calling function name or NULL.
Definition: vlc_messages.h:64
void vlc_vaLog(struct vlc_logger *const *logger, int prio, const char *type, const char *module, const char *file, unsigned line, const char *func, const char *format, va_list ap)
Definition: messages.c:85
void vlc_object_vaLog(vlc_object_t *obj, int prio, const char *module, const char *file, unsigned line, const char *func, const char *format, va_list ap)
Emit a log message.
Definition: objects.c:140
Definition: vlc_messages.h:151
const char * psz_module
Emitter module (source code)
Definition: vlc_messages.h:60
Error.
Definition: vlc_messages.h:48
Debug.
Definition: vlc_messages.h:50
uintptr_t i_object_id
Emitter (temporarily) unique object ID or 0.
Definition: vlc_messages.h:58
struct vlc_log_t vlc_log_t
Log message.
void vlc_Log(struct vlc_logger *const *logger, int prio, const char *type, const char *module, const char *file, unsigned line, const char *func, const char *format,...)
Definition: messages.c:131
const char * vlc_strerror(int)
Formats an error message in the current locale.
Definition: error.c:29
struct vlc_logger * vlc_LogHeaderCreate(struct vlc_logger *parent, const char *str)
Creates a prefixed message log.
Definition: messages.c:506
void(* vlc_log_cb)(void *data, int type, const vlc_log_t *item, const char *fmt, va_list args)
Message logging callback signature.
Definition: vlc_messages.h:148
Warning.
Definition: vlc_messages.h:49
int line
Source code file line number or -1.
Definition: vlc_messages.h:63
Definition: messages.c:54
#define VLC_API
Definition: fourcc_gen.c:31
const char * file
Source code file name or NULL.
Definition: vlc_messages.h:62
#define VLC_FORMAT(x, y)
String format function annotation.
Definition: vlc_common.h:141
const char * vlc_strerror_c(int)
Formats an error message in the POSIX/C locale (i.e.
Definition: error.c:34
const char * psz_object_type
Emitter object type name.
Definition: vlc_messages.h:59
void vlc_object_Log(vlc_object_t *obj, int prio, const char *module, const char *file, unsigned line, const char *func, const char *format,...)
Emit a log message.
Definition: objects.c:156
unsigned long tid
Emitter thread ID.
Definition: vlc_messages.h:65
Log message.
Definition: vlc_messages.h:56
VLC object common members.
Definition: vlc_objects.h:43
#define VLC_USED
Definition: fourcc_gen.c:32
const char * psz_header
Additional header (used by VLM media)
Definition: vlc_messages.h:61