1/*
2 * 1394-Based Digital Camera Control Library
3 *
4 * Error logging functions
5 *
6 * Written by Damien Douxchamps <ddouxchamps@users.sf.net> and
7 * Rudolf Leitgeb
8 *
9 * This library is free software; you can redistribute it and/or
10 * modify it under the terms of the GNU Lesser General Public
11 * License as published by the Free Software Foundation; either
12 * version 2.1 of the License, or (at your option) any later version.
13 *
14 * This library is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 * Lesser General Public License for more details.
18 *
19 * You should have received a copy of the GNU Lesser General Public
20 * License along with this library; if not, write to the Free Software
21 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
22 */
23
24/***************************************************************************
25 * logging facility for libdc1394
26 *
27 * These functions provide the logging of error, warning and debug messages
28 * They allow registering of custom logging functions or the use
29 * of the builtin loggers which redirect the output to stderr.
30 * Three log levels are supported:
31 * error: Indicates that an error has been detected which mandates
32 * shutdown of the program as soon as feasible
33 * warning: Indicates that something happened which prevents libdc1394
34 * from working but which could possibly be resolved by the
35 * application or the user: plugging in a camera, resetting the
36 * firewire bus, ....
37 * debug: A sort of way point for the library. This log level is supposed
38 * to report that a specific function has been entered or has
39 * passed a certain stage. This log level is turned off by default
40 * and may produce a lot of output during regular operation.
41 * The main purpose for this log level is for debugging libdc1394
42 * and for generating meaningful problem reports.
43 ***************************************************************************/
44
45#include <dc1394/dc1394.h>
46
47#ifndef __DC1394_LOG_H__
48#define __DC1394_LOG_H__
49
50/*! \file dc1394/log.h
51 \brief Functions to log errors, warning and debug messages
52 \author Damien Douxchamps: coding
53 \author Rudolf Leitgeb: coding
54 \author Peter Antoniac: documentation maintainer
55
56 More details soon
57*/
58
59/**
60 * Error codes returned by most libdc1394 functions.
61 *
62 * General rule: 0 is success, negative denotes a problem.
63 */
64typedef enum {
65 DC1394_SUCCESS = 0,
66 DC1394_FAILURE = -1,
67 DC1394_NOT_A_CAMERA = -2,
68 DC1394_FUNCTION_NOT_SUPPORTED = -3,
69 DC1394_CAMERA_NOT_INITIALIZED = -4,
70 DC1394_MEMORY_ALLOCATION_FAILURE = -5,
71 DC1394_TAGGED_REGISTER_NOT_FOUND = -6,
72 DC1394_NO_ISO_CHANNEL = -7,
73 DC1394_NO_BANDWIDTH = -8,
74 DC1394_IOCTL_FAILURE = -9,
75 DC1394_CAPTURE_IS_NOT_SET = -10,
76 DC1394_CAPTURE_IS_RUNNING = -11,
77 DC1394_RAW1394_FAILURE = -12,
78 DC1394_FORMAT7_ERROR_FLAG_1 = -13,
79 DC1394_FORMAT7_ERROR_FLAG_2 = -14,
80 DC1394_INVALID_ARGUMENT_VALUE = -15,
81 DC1394_REQ_VALUE_OUTSIDE_RANGE = -16,
82 DC1394_INVALID_FEATURE = -17,
83 DC1394_INVALID_VIDEO_FORMAT = -18,
84 DC1394_INVALID_VIDEO_MODE = -19,
85 DC1394_INVALID_FRAMERATE = -20,
86 DC1394_INVALID_TRIGGER_MODE = -21,
87 DC1394_INVALID_TRIGGER_SOURCE = -22,
88 DC1394_INVALID_ISO_SPEED = -23,
89 DC1394_INVALID_IIDC_VERSION = -24,
90 DC1394_INVALID_COLOR_CODING = -25,
91 DC1394_INVALID_COLOR_FILTER = -26,
92 DC1394_INVALID_CAPTURE_POLICY = -27,
93 DC1394_INVALID_ERROR_CODE = -28,
94 DC1394_INVALID_BAYER_METHOD = -29,
95 DC1394_INVALID_VIDEO1394_DEVICE = -30,
96 DC1394_INVALID_OPERATION_MODE = -31,
97 DC1394_INVALID_TRIGGER_POLARITY = -32,
98 DC1394_INVALID_FEATURE_MODE = -33,
99 DC1394_INVALID_LOG_TYPE = -34,
100 DC1394_INVALID_BYTE_ORDER = -35,
101 DC1394_INVALID_STEREO_METHOD = -36,
102 DC1394_BASLER_NO_MORE_SFF_CHUNKS = -37,
103 DC1394_BASLER_CORRUPTED_SFF_CHUNK = -38,
104 DC1394_BASLER_UNKNOWN_SFF_CHUNK = -39
105} dc1394error_t;
106#define DC1394_ERROR_MIN DC1394_BASLER_UNKNOWN_SFF_CHUNK
107#define DC1394_ERROR_MAX DC1394_SUCCESS
108#define DC1394_ERROR_NUM (DC1394_ERROR_MAX-DC1394_ERROR_MIN+1)
109
110/**
111 * Types of logging messages
112 *
113 * Three types exist:
114 * - ERROR for real, hard, unrecoverable errors that will result in the program terminating.
115 * - WARNING for things that have gone wrong, but are not requiring a termination of the program.
116 * - DEBUG for debug messages that can be very verbose but may help the developers to fix bugs.
117 */
118typedef enum {
119 DC1394_LOG_ERROR=768,
120 DC1394_LOG_WARNING,
121 DC1394_LOG_DEBUG
122} dc1394log_t;
123#define DC1394_LOG_MIN DC1394_LOG_ERROR
124#define DC1394_LOG_MAX DC1394_LOG_DEBUG
125#define DC1394_LOG_NUM (DC1394_LOG_MAX - DC1394_LOG_MIN + 1)
126
127#if ! defined (_MSC_VER)
128/* Error logging/checking macros. Logs an error string on stderr and exit current function
129 if error is positive. Neg errors are messages and are thus ignored */
130
131/* Some macros to log errors, etc... conditionally */
132#define DC1394_WRN(err,message) \
133 do { \
134 if ((err>0)||(err<=-DC1394_ERROR_NUM)) \
135 err=DC1394_INVALID_ERROR_CODE; \
136 \
137 if (err!=DC1394_SUCCESS) { \
138 dc1394_log_warning("%s: in %s (%s, line %d): %s\n", \
139 dc1394_error_get_string(err), \
140 __FUNCTION__, __FILE__, __LINE__, message); \
141 } \
142 } while (0);
143
144#define DC1394_ERR(err,message) \
145 do { \
146 if ((err>0)||(err<=-DC1394_ERROR_NUM)) \
147 err=DC1394_INVALID_ERROR_CODE; \
148 \
149 if (err!=DC1394_SUCCESS) { \
150 dc1394_log_error("%s: in %s (%s, line %d): %s\n", \
151 dc1394_error_get_string(err), \
152 __FUNCTION__, __FILE__, __LINE__, message); \
153 return; \
154 } \
155 } while (0);
156
157#define DC1394_ERR_RTN(err,message) \
158 do { \
159 if ((err>0)||(err<=-DC1394_ERROR_NUM)) \
160 err=DC1394_INVALID_ERROR_CODE; \
161 \
162 if (err!=DC1394_SUCCESS) { \
163 dc1394_log_error("%s: in %s (%s, line %d): %s\n", \
164 dc1394_error_get_string(err), \
165 __FUNCTION__, __FILE__, __LINE__, message); \
166 return err; \
167 } \
168 } while (0);
169
170#define DC1394_ERR_CLN(err,cleanup,message) \
171 do { \
172 if ((err>0)||(err<=-DC1394_ERROR_NUM)) \
173 err=DC1394_INVALID_ERROR_CODE; \
174 \
175 if (err!=DC1394_SUCCESS) { \
176 dc1394_log_error("%s: in %s (%s, line %d): %s\n", \
177 dc1394_error_get_string(err), \
178 __FUNCTION__, __FILE__, __LINE__, message); \
179 cleanup; \
180 return; \
181 } \
182 } while (0);
183
184#define DC1394_ERR_CLN_RTN(err,cleanup,message) \
185 do { \
186 if ((err>0)||(err<=-DC1394_ERROR_NUM)) \
187 err=DC1394_INVALID_ERROR_CODE; \
188 \
189 if (err!=DC1394_SUCCESS) { \
190 dc1394_log_error("%s: in %s (%s, line %d): %s\n", \
191 dc1394_error_get_string(err), \
192 __FUNCTION__, __FILE__, __LINE__, message); \
193 cleanup; \
194 return err; \
195 } \
196 } while (0);
197
198
199#endif /* _MSC_VER */
200
201#ifdef __cplusplus
202extern "C" {
203#endif
204
205/**
206 * dc1394_log_register_handler: register log handler for reporting error, warning or debug statements
207 * Passing NULL as argument turns off this log level.
208 * @param [in] log_handler: pointer to a function which takes a character string as argument
209 * type: the type of log
210 * @param [in] type: message type (\a debug, \a err or \a warning)
211 * @param [in] message: log message
212 */
213dc1394error_t dc1394_log_register_handler(dc1394log_t type, void(*log_handler)(dc1394log_t type,
214 const char *message, void* user), void* user);
215
216/**
217 * dc1394_log_set_default_handler: set the log handler to the default handler
218 * At boot time, debug logging is OFF (handler is NULL). Using this function for the debug statements
219 * will start logging of debug statements usng the default handler.
220 */
221dc1394error_t dc1394_log_set_default_handler(dc1394log_t type);
222
223/**
224 * dc1394_log_error: logs a fatal error condition to the registered facility
225 * This function shall be invoked if a fatal error condition is encountered.
226 * The message passed as argument is delivered to the registered error reporting
227 * function registered before.
228 * @param [in] format,...: error message to be logged, multiple arguments allowed (printf style)
229 */
230void dc1394_log_error(const char *format,...);
231
232/**
233 * dc1394_log_warning: logs a nonfatal error condition to the registered facility
234 * This function shall be invoked if a nonfatal error condition is encountered.
235 * The message passed as argument is delivered to the registered warning reporting
236 * function registered before.
237 * @param [in] format,...: warning message to be logged, multiple arguments allowed (printf style)
238 */
239void dc1394_log_warning(const char *format,...);
240
241/**
242 * dc1394_log_debug: logs a debug statement to the registered facility
243 * This function shall be invoked if a debug statement is to be logged.
244 * The message passed as argument is delivered to the registered debug reporting
245 * function registered before ONLY IF the environment variable DC1394_DEBUG has been set before the
246 * program starts.
247 * @param [in] format,...: debug statement to be logged, multiple arguments allowed (printf style)
248 */
249void dc1394_log_debug(const char *format,...);
250
251#ifdef __cplusplus
252}
253#endif
254
255#endif
256

source code of include/dc1394/log.h