Logo Search packages:      
Sourcecode: libdc1394-22 version File versions  Download package

log.h

Go to the documentation of this file.
/*
 * 1394-Based Digital Camera Control Library
 *
 * Error logging functions
 *
 * Written by Damien Douxchamps <ddouxchamps@users.sf.net> and
 *            Rudolf Leitgeb
 *
 * 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
 * Lesser General Public License for more details.
 *
 * 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
 */

/***************************************************************************
 * logging facility for libdc1394
 *
 * These functions provide the logging of error, warning and debug messages
 * They allow registering of custom logging functions or the use
 * of the builtin loggers which redirect the output to stderr.
 * Three log levels are supported:
 * error:   Indicates that an error has been detected which mandates
 *          shutdown of the program as soon as feasible
 * warning: Indicates that something happened which prevents libdc1394
 *          from working but which could possibly be resolved by the
 *          application or the user: plugging in a camera, resetting the
 *          firewire bus, ....
 * debug:   A sort of way point for the library. This log level is supposed
 *          to report that a specific function has been entered or has
 *          passed a certain stage. This log level is turned off by default
 *          and may produce a lot of output during regular operation.
 *          The main purpose for this log level is for debugging libdc1394
 *          and for generating meaningful problem reports.
 ***************************************************************************/

#include <dc1394/dc1394.h>

#ifndef __DC1394_LOG_H__
#define __DC1394_LOG_H__

/*! \file dc1394/log.h
    \brief Functions to log errors, warning and debug messages
    \author Damien Douxchamps: coding
    \author Rudolf Leitgeb: coding
    \author Peter Antoniac: documentation maintainer

    More details soon
*/

/**
 * Error codes returned by most libdc1394 functions.
 *
 * General rule: 0 is success, negative denotes a problem.
 */
00064 typedef enum {
    DC1394_SUCCESS                     =  0,
    DC1394_FAILURE                     = -1,
    DC1394_NOT_A_CAMERA                = -2,
    DC1394_FUNCTION_NOT_SUPPORTED      = -3,
    DC1394_CAMERA_NOT_INITIALIZED      = -4,
    DC1394_MEMORY_ALLOCATION_FAILURE   = -5,
    DC1394_TAGGED_REGISTER_NOT_FOUND   = -6,
    DC1394_NO_ISO_CHANNEL              = -7,
    DC1394_NO_BANDWIDTH                = -8,
    DC1394_IOCTL_FAILURE               = -9,
    DC1394_CAPTURE_IS_NOT_SET          = -10,
    DC1394_CAPTURE_IS_RUNNING          = -11,
    DC1394_RAW1394_FAILURE             = -12,
    DC1394_FORMAT7_ERROR_FLAG_1        = -13,
    DC1394_FORMAT7_ERROR_FLAG_2        = -14,
    DC1394_INVALID_ARGUMENT_VALUE      = -15,
    DC1394_REQ_VALUE_OUTSIDE_RANGE     = -16,
    DC1394_INVALID_FEATURE             = -17,
    DC1394_INVALID_VIDEO_FORMAT        = -18,
    DC1394_INVALID_VIDEO_MODE          = -19,
    DC1394_INVALID_FRAMERATE           = -20,
    DC1394_INVALID_TRIGGER_MODE        = -21,
    DC1394_INVALID_TRIGGER_SOURCE      = -22,
    DC1394_INVALID_ISO_SPEED           = -23,
    DC1394_INVALID_IIDC_VERSION        = -24,
    DC1394_INVALID_COLOR_CODING        = -25,
    DC1394_INVALID_COLOR_FILTER        = -26,
    DC1394_INVALID_CAPTURE_POLICY      = -27,
    DC1394_INVALID_ERROR_CODE          = -28,
    DC1394_INVALID_BAYER_METHOD        = -29,
    DC1394_INVALID_VIDEO1394_DEVICE    = -30,
    DC1394_INVALID_OPERATION_MODE      = -31,
    DC1394_INVALID_TRIGGER_POLARITY    = -32,
    DC1394_INVALID_FEATURE_MODE        = -33,
    DC1394_INVALID_LOG_TYPE            = -34,
    DC1394_INVALID_BYTE_ORDER          = -35,
    DC1394_INVALID_STEREO_METHOD       = -36,
    DC1394_BASLER_NO_MORE_SFF_CHUNKS   = -37,
    DC1394_BASLER_CORRUPTED_SFF_CHUNK  = -38,
    DC1394_BASLER_UNKNOWN_SFF_CHUNK    = -39
} dc1394error_t;
#define DC1394_ERROR_MIN  DC1394_BASLER_UNKNOWN_SFF_CHUNK
#define DC1394_ERROR_MAX  DC1394_SUCCESS
#define DC1394_ERROR_NUM (DC1394_ERROR_MAX-DC1394_ERROR_MIN+1)

/**
 * Types of logging messages
 *
 * Three types exist:
 * - ERROR for real, hard, unrecoverable errors that will result in the program terminating.
 * - WARNING for things that have gone wrong, but are not requiring a termination of the program.
 * - DEBUG for debug messages that can be very verbose but may help the developers to fix bugs.
 */
00118 typedef enum {
    DC1394_LOG_ERROR=768,
    DC1394_LOG_WARNING,
    DC1394_LOG_DEBUG
} dc1394log_t;
#define DC1394_LOG_MIN               DC1394_LOG_ERROR
#define DC1394_LOG_MAX               DC1394_LOG_DEBUG
#define DC1394_LOG_NUM              (DC1394_LOG_MAX - DC1394_LOG_MIN + 1)

#if ! defined (_MSC_VER)
/* Error logging/checking macros. Logs an error string on stderr and exit current function
   if error is positive. Neg errors are messages and are thus ignored */

/* Some macros to log errors, etc... conditionally */
#define DC1394_WRN(err,message)                           \
  do {                                                    \
    if ((err>0)||(err<=-DC1394_ERROR_NUM))                \
      err=DC1394_INVALID_ERROR_CODE;                      \
                                                          \
    if (err!=DC1394_SUCCESS) {                            \
      dc1394_log_warning("%s: in %s (%s, line %d): %s\n", \
      dc1394_error_get_string(err),                       \
          __FUNCTION__, __FILE__, __LINE__, message);     \
    }                                                     \
  } while (0);

#define DC1394_ERR(err,message)                           \
  do {                                                    \
    if ((err>0)||(err<=-DC1394_ERROR_NUM))                \
      err=DC1394_INVALID_ERROR_CODE;                      \
                                                          \
    if (err!=DC1394_SUCCESS) {                            \
      dc1394_log_error("%s: in %s (%s, line %d): %s\n",   \
      dc1394_error_get_string(err),                       \
          __FUNCTION__, __FILE__, __LINE__, message);     \
      return;                                             \
    }                                                     \
  } while (0);

#define DC1394_ERR_RTN(err,message)                       \
  do {                                                    \
    if ((err>0)||(err<=-DC1394_ERROR_NUM))                \
      err=DC1394_INVALID_ERROR_CODE;                      \
                                                          \
    if (err!=DC1394_SUCCESS) {                            \
      dc1394_log_error("%s: in %s (%s, line %d): %s\n",   \
      dc1394_error_get_string(err),                       \
          __FUNCTION__, __FILE__, __LINE__, message);     \
      return err;                                         \
    }                                                     \
  } while (0);

#define DC1394_ERR_CLN(err,cleanup,message)               \
  do {                                                    \
    if ((err>0)||(err<=-DC1394_ERROR_NUM))                \
      err=DC1394_INVALID_ERROR_CODE;                      \
                                                          \
    if (err!=DC1394_SUCCESS) {                            \
      dc1394_log_error("%s: in %s (%s, line %d): %s\n",   \
      dc1394_error_get_string(err),                       \
          __FUNCTION__, __FILE__, __LINE__, message);     \
      cleanup;                                            \
      return;                                             \
    }                                                     \
  } while (0);

#define DC1394_ERR_CLN_RTN(err,cleanup,message)           \
  do {                                                    \
    if ((err>0)||(err<=-DC1394_ERROR_NUM))                \
      err=DC1394_INVALID_ERROR_CODE;                      \
                                                          \
    if (err!=DC1394_SUCCESS) {                            \
      dc1394_log_error("%s: in %s (%s, line %d): %s\n",   \
      dc1394_error_get_string(err),                       \
          __FUNCTION__, __FILE__, __LINE__, message);     \
      cleanup;                                            \
      return err;                                         \
    }                                                     \
  } while (0);


#endif /* _MSC_VER */

#ifdef __cplusplus
extern "C" {
#endif

/**
 * dc1394_log_register_handler: register log handler for reporting error, warning or debug statements
 * Passing NULL as argument turns off this log level.
 * @param [in] log_handler: pointer to a function which takes a character string as argument
 *             type: the type of log
 * @param [in] type: message type (\a debug, \a err or \a warning)
 * @param [in] message: log message
 */
dc1394error_t dc1394_log_register_handler(dc1394log_t type, void(*log_handler)(dc1394log_t type,
                                          const char *message, void* user), void* user);

/**
 * dc1394_log_set_default_handler: set the log handler to the default handler
 * At boot time, debug logging is OFF (handler is NULL). Using this function for the debug statements
 * will start logging of debug statements usng the default handler.
 */
dc1394error_t dc1394_log_set_default_handler(dc1394log_t type);

/**
 * dc1394_log_error: logs a fatal error condition to the registered facility
 * This function shall be invoked if a fatal error condition is encountered.
 * The message passed as argument is delivered to the registered error reporting
 * function registered before.
 * @param [in] format,...: error message to be logged, multiple arguments allowed (printf style)
 */
void dc1394_log_error(const char *format,...);

/**
 * dc1394_log_warning: logs a nonfatal error condition to the registered facility
 * This function shall be invoked if a nonfatal error condition is encountered.
 * The message passed as argument is delivered to the registered warning reporting
 * function registered before.
 * @param [in] format,...: warning message to be logged, multiple arguments allowed (printf style)
 */
void dc1394_log_warning(const char *format,...);

/**
 * dc1394_log_debug: logs a debug statement to the registered facility
 * This function shall be invoked if a debug statement is to be logged.
 * The message passed as argument is delivered to the registered debug reporting
 * function registered before ONLY IF the environment variable DC1394_DEBUG has been set before the
 * program starts.
 * @param [in] format,...: debug statement to be logged, multiple arguments allowed (printf style)
 */
void dc1394_log_debug(const char *format,...);

#ifdef __cplusplus
}
#endif

#endif

Generated by  Doxygen 1.6.0   Back to index