Boston Dynamics Log Library

libbdilog.h

DI-Guy API Version 5.1.26

This file was automatically generated from comments in the C/C++ header file libbdilog.h. Do not edit this file directly; the changes will be lost. Please mail suggestions or corrections to diguy@bdi.com

Alphabetical Index

Includes: declspec_bdiutil.h

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.

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, 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_printf

Prototype:

int bdi_log_printf(int notify_level, const char *format, ...);
Description:

printf-like version of bdi_log_print(). Use just like printf, but add the notify_level as the first argument.

Arguments and Return Value:

return value0 on success, -1 on failure

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

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.

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_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_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.


Alphabetical Index


Copyright (C) 1992-2003

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/515 Massachusetts Avenue/Cambridge MA 02139.