Boston Dynamics Log Library

Generated from libbdilog.h

DI-Guy API Version 12.5.1

This file was automatically generated from libbdilog.h. Do not edit this file directly; the changes will be lost.
Includes: declspec_bdiutil.h

Contents:

Alphabetical Index

The Boston Dynamics log library is used by most of Boston Dynamics' software. It allows programs to write errors, debugging information, etc., to zero, one, or more outputs including stderr, a file, or a user-supplied output.

constant CHECK_PRINTF_FORMAT

#define CHECK_PRINTF_FORMAT  __attribute__ ((format (printf, 2, 3)))
Constants and Types

typedef bdiCallbackHandle

typedef int bdiCallbackHandle;

constants 

#define BDI_LOG_MAX_CALLBACKS       (8)
#define BDI_LOG_BAD_CALLBACK_HANDLE (-1)

constants 

#define BDI_LOG_NOTHING    (-1)
#define BDI_LOG_ALWAYS     (0) 
#define BDI_LOG_FATAL      (1) 
#define BDI_LOG_ERROR      (2) 
#define BDI_LOG_WARN       (3) 
#define BDI_LOG_INFO       (4) 
#define BDI_LOG_DEBUG      (5) 
#define BDI_LOG_DEBUG_LV1  (6) 
#define BDI_LOG_DEBUG_LV2  (7) 
#define BDI_LOG_DEBUG_LV3  (8) 
#define BDI_LOG_DEBUG_LV4  (9) 
#define BDI_LOG_DEBUG_LV5  (10) 
#define BDI_LOG_DEBUG_LV6  (11) 
#define BDI_LOG_DEBUG_LV7  (12) 
#define BDI_LOG_DEBUG_LV8  (13) 
#define BDI_LOG_DEBUG_LV9  (14) 
#define BDI_LOG_EVERYTHING (15)
Log notify levels. A lower number indicates higher importance.

Standard stderr/stdout Callbacks

function bdi_log_stderr_enable

Prototype:

int bdi_log_stderr_enable(int notify_level);
Description:

This function will route a copy of appropriate log messages to stdio's stderr.

Arguments and Return Value:

return value0 on success, -1 on failure
notify_levelonly messages whose notify level is at least as important as this will appear in this log

function bdi_log_stderr_disable

Prototype:

int bdi_log_stderr_disable(void);
Description:

This function shuts down the log opened by bdi_log_stderr_enable().

function bdi_log_stdout_enable

Prototype:

int bdi_log_stdout_enable(int notify_level);
Description:

This function will route a copy of appropriate log messages to stdio's stdout.

Arguments and Return Value:

return value0 on success, -1 on failure
notify_levelonly messages whose notify level is at least as important as this will appear in this log

function bdi_log_stdout_disable

Prototype:

int bdi_log_stdout_disable(void);
Description:

This function shuts down the log opened by bdi_log_stdout_enable().

Arguments and Return Value:

return value0 on success, -1 on failure
File Callbacks

function bdi_log_file_enable

Prototype:

int bdi_log_file_enable(int notify_level, const char* filename, int clear_file);
Description:

This function will route a copy of appropriate log messages to the named file.

Arguments and Return Value:

return value0 on success, -1 on failure
notify_levelonly messages whose notify level is at least as important as this will appear in this log
filename name of the file in which messages will appear
clear_file 0 or 1; 1 means clear out prior contents of file, 0 means append to the file

function bdi_log_file_disable

Prototype:

int bdi_log_file_disable(void);
Description:

This function shuts down the log opened by bdi_log_file_enable().

Arguments and Return Value:

return value0 on success, -1 on failure
Print Functions

function bdi_log_print

Prototype:

int bdi_log_print(int notify_level, const char* string);
Description:

This function sends the specified string to all open logs. Whether or not the string is actually printed depends the specified notify_level in this call and the notify_level with which each log was opened.

Arguments and Return Value:

return value0 on success, -1 on failure
string message to be (potentially) printed
notify_level"importance" of message; lower is more important

function bdi_log_set_global_notify_level

Prototype:

int bdi_log_set_global_notify_level(int notify_level);
Description:

This function sets the global notify level. Messages whose notify_level argument is less important than this will not be printed, regardless of the notify_level used to open logs.

The starting global notify level is BDI_LOG_EVERYTHING.

Arguments and Return Value:

return value0 on success, -1 on failure
notify_levelglobal level of importance
Example:

// open a file log with notify level BDI_LOG_WARN
bdi_log_file_enable(BDI_LOG_WARN, "errors.txt", 1);

// this message WILL appear in the log
bdi_log_print(BDI_LOG_WARN, "Message 1.\n");

// set the global notify level to be more strict
bdi_log_set_global_notify_level(BDI_LOG_ERROR);

// this message WILL NOT appear in the log
// (log messages of importance less than BDI_LOG_ERROR are ignored.)
bdi_log_print(BDI_LOG_WARN, "Message 2.\n");

function bdi_log_get_global_notify_level

Prototype:

int bdi_log_get_global_notify_level(void);
Description:

Returns the most recent setting of bdi_log_set_global_notify_level().

Arguments and Return Value:

return valuemost recent setting
Registration Functions

function bdi_log_register_callback

Prototype:

bdiCallbackHandle bdi_log_register_callback(int notify_level,
    bdiLogCallbackFunction* callback,
    void* user_data);
Description:

This function registers a callback for the specified notify_level.

Arguments and Return Value:

return value a handle
callback pointer to the callback function
notify_level level of "importance" the callback will be called for
user_data pointer that will be supplied to the callback each time it is called.

function bdi_log_unregister_callback

Prototype:

int bdi_log_unregister_callback(bdiCallbackHandle handle);
Description:

This function unregisters a previously registered callback.

Arguments and Return Value:

return value0 on success, -1 on failure
handle the handle returned by bdi_log_register_callback()

function bdi_log_get_num_logs_open

Prototype:

int bdi_log_get_num_logs_open();
Description:

This function returns the number of logs currently open.

Arguments and Return Value:

return value number of logs open

function bdi_log_set_notify_level

Prototype:

int bdi_log_set_notify_level(bdiCallbackHandle handle, int notify_level);
Description:

This function changes the notify level of a registered callback.

Arguments and Return Value:

return value0 on success, -1 on failure
handle the handle returned by bdi_log_register_callback()
notify_levelthe new notify level

function bdi_log_get_notify_level

Prototype:

int bdi_log_get_notify_level(bdiCallbackHandle handle);
Description:

This function returns the notify level of a registered callback.

Arguments and Return Value:

return valuemost recent setting or BDI_LOG_NOTHING if handle is invalid
handle the handle returned by bdi_log_register_callback()

function bdi_log_get_string_from_notify_level

Prototype:

void bdi_log_get_string_from_notify_level(int notify_level,
    char* result,
    int result_buf_size);
Description:

Derives a string from the notify level and returns it in the passed result buffer.

Arguments:

notify_level notify level to parse
result character buffer for result
result_max_lenresult buffer size

function bdi_log_register_fatal_exit_function

Prototype:

void bdi_log_register_fatal_exit_function(bdiLogFatalExitFunction* fatal_exit_func);
Description:

This function registers a function that will be called if a log message is sent with level BDI_LOG_FATAL. The function should whatever it takes to shut down gracefully.

If no fatal exit function is registered, exit(EXIT_FAILURE) will be called by default.

function bdi_log_print_to_output_window

Prototype:

int bdi_log_print_to_output_window(char* format, ...);
Description:

This function prints using OutputDebugString on Windows, which will show up in the Output window in Microsoft Developer Studio.

function bdi_log_lock

Prototype:

void bdi_log_lock();
Description:

This function grabs the lock of the logging system. This is pretty hacky. If you do not release this lock, you're in trouble. This can be useful for certain specialized interactions with log callback objects that rely on the libbdilog lock for their synchronization.

function bdi_log_unlock

Prototype:

void bdi_log_unlock();
Description:

This function releases the lock of the logging system. This is pretty hacky. If you do not release this lock, you're in trouble. This can be useful for certain specialized interactions with log callback objects that rely on the libbdilog lock for their synchronization.

Alphabetical Index



Copyright (C) 1992-2012 Boston Dynamics

ALL RIGHTS RESERVED.

These coded instructions, statements, and computer programs contain unpublished proprietary information of Boston Dynamics and are protected by Copyright Laws of the United States. They may not be used, duplicated, or disclosed in any form, in whole or in part, without the prior written consent from Boston Dynamics.

RESTRICTED RIGHTS LEGEND

Use, duplication, or disclosure by the government is subject to restrictions as set forth in FAR 52.227.19(c)(2) or subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Sofware clause at DFARS 252.227-7013 and/or in similar or successor clauses in the FAR, or the DOD or NASA FAR Supplement, or to subparagraphs (c)(1) and (c)(2) of the Commercial Computer Software--Restricted Rights at 48 CFR 52.227-19, as applicable. Unpublished-rights reserved under the Copyright Laws of the United States.

Contractor/Manufacturer is:

Boston Dynamics/78 Fourth Avenue/Waltham MA 02451.