OSAPI Log API. More...

Data Structures
struct	OSAPI_LogEntry
	The type for a log-entry. More...

struct	OSAPI_LogProperty
	Configuration of logging functionality. More...

Macros
#define	OSAPI_LOG_DETAIL_MODULENAME (0x80000000UL)
	Bitmap for enabling saving the module name in the log buffer.

#define	OSAPI_LOG_DETAIL_SOURCEFILE (0x40000000UL)
	Bitmap for enabling saving the file name in the log buffer.

#define	OSAPI_LOG_DETAIL_LINENUMBER (0x20000000UL)
	Bitmap for enabling saving the line number in the log buffer.

#define	OSAPI_LOG_DETAIL_FUNCTIONAME (0x10000000UL)
	Bitmap for enabling saving the function name in the log buffer.

#define	OSAPI_LOG_DETAIL_DATA_ONLY (0x04000000UL)
	Bitmap for enabling additional log details.

#define	OSAPI_LOG_DETAIL_ALL
	Bitmap enabling all log detail fields.

#define	OSAPI_LOG_DETAIL_NO_DATA
	Bitmap enabling all log detail fields except data.

#define	OSAPI_LogProperty_INITIALIZER
	Initializer for the OSAPI_LogProperty.

Typedefs
typedef struct OSAPI_LogEntry	OSAPI_LogEntry_T
	The type for a log-entry.

typedef void(*	OSAPI_Log_write_buffer_T) (const char *buffer, RTI_SIZE_T length)
	Optional user-defined function to output a log/trace buffer.

typedef void(*	OSAPI_LogHandler_T) (void param, OSAPI_LogEntry_T entry)
	Optional user-defined function for processing new log messages.

Enumerations
enum	OSAPI_LogVerbosity_T { OSAPI_LOG_VERBOSITY_SILENT = 0 , OSAPI_LOG_VERBOSITY_ERROR = 1 , OSAPI_LOG_VERBOSITY_WARNING = 2 , OSAPI_LOG_VERBOSITY_DEBUG = 3 }
	Logging verbosity. More...

Functions
RTI_BOOL	OSAPI_Log_set_log_handler (OSAPI_LogHandler_T handler, void *param)
	Install a log handler.

RTI_BOOL	OSAPI_Log_get_log_handler (OSAPI_LogHandler_T handler, void *param)
	Return the current log handler.

RTI_BOOL	OSAPI_Log_set_display_handler (OSAPI_LogDisplay_T handler, void *param)
	Install a display handler.

RTI_BOOL	OSAPI_Log_get_display_handler (OSAPI_LogDisplay_T handler, void *param)
	Return the current display function.

void	OSAPI_Log_set_verbosity (OSAPI_LogVerbosity_T verbosity)
	Set the log verbosity.

RTI_BOOL	OSAPI_Log_clear (void)
	Clear the log buffer.

void	OSAPI_Log_get_property (struct OSAPI_LogProperty *property)
	Get the current log properties.

RTI_BOOL	OSAPI_Log_set_property (struct OSAPI_LogProperty *property)
	Set the current log properties.

OSAPI_LogVerbosity_T	OSAPI_Log_get_verbosity (void)
	Get the current log verbosity.

RTI_INT32	OSAPI_Log_get_last_error_code (void)
	Returns the error code for a function that failed.

Detailed Description

OSAPI Log API.

Macro Definition Documentation

◆ OSAPI_LOG_DETAIL_MODULENAME

#define OSAPI_LOG_DETAIL_MODULENAME (0x80000000UL)

Bitmap for enabling saving the module name in the log buffer.

See Also OSAPI_LogProperty::log_detail

◆ OSAPI_LOG_DETAIL_SOURCEFILE

#define OSAPI_LOG_DETAIL_SOURCEFILE (0x40000000UL)

Bitmap for enabling saving the file name in the log buffer.

See Also OSAPI_LogProperty::log_detail

◆ OSAPI_LOG_DETAIL_LINENUMBER

#define OSAPI_LOG_DETAIL_LINENUMBER (0x20000000UL)

Bitmap for enabling saving the line number in the log buffer.

See Also OSAPI_LogProperty::log_detail

◆ OSAPI_LOG_DETAIL_FUNCTIONAME

#define OSAPI_LOG_DETAIL_FUNCTIONAME (0x10000000UL)

Bitmap for enabling saving the function name in the log buffer.

See Also OSAPI_LogProperty::log_detail

◆ OSAPI_LOG_DETAIL_DATA_ONLY

#define OSAPI_LOG_DETAIL_DATA_ONLY (0x04000000UL)

Bitmap for enabling additional log details.

See Also OSAPI_LogProperty::log_detail

◆ OSAPI_LOG_DETAIL_ALL

#define OSAPI_LOG_DETAIL_ALL

Value:

        (OSAPI_LOG_DETAIL_MODULENAME | \
         OSAPI_LOG_DETAIL_SOURCEFILE | \
         OSAPI_LOG_DETAIL_LINENUMBER | \
         OSAPI_LOG_DETAIL_FUNCTIONAME | \
         OSAPI_LOG_DETAIL_FORMAT | \
         OSAPI_LOG_DETAIL_DATA_ONLY)

Bitmap enabling all log detail fields.

See Also OSAPI_LogProperty::log_detail

◆ OSAPI_LOG_DETAIL_NO_DATA

#define OSAPI_LOG_DETAIL_NO_DATA

Value:

        (OSAPI_LOG_DETAIL_MODULENAME | \
         OSAPI_LOG_DETAIL_SOURCEFILE | \
         OSAPI_LOG_DETAIL_LINENUMBER | \
         OSAPI_LOG_DETAIL_FUNCTIONAME )

Bitmap enabling all log detail fields except data.

See Also OSAPI_LogProperty::log_detail

◆ OSAPI_LogProperty_INITIALIZER

#define OSAPI_LogProperty_INITIALIZER

Value:

{\
    OSAPI_LOG_BUFFER_SIZE,\
    OSAPI_LOG_DETAIL_ALL,\
    NULL\
}

Initializer for the OSAPI_LogProperty.

Typedef Documentation

◆ OSAPI_LogEntry_T

typedef struct OSAPI_LogEntry OSAPI_LogEntry_T

The type for a log-entry.

◆ OSAPI_Log_write_buffer_T

typedef void(* OSAPI_Log_write_buffer_T) (const char *buffer, RTI_SIZE_T length)

Optional user-defined function to output a log/trace buffer.

The handler is set by OSAPI_Log_set_property.

Parameters

buffer	<<in>> Pointer to buffer with log to write
length	<<in>> Length of the buffer to write

◆ OSAPI_LogHandler_T

typedef void(* OSAPI_LogHandler_T) (void *param, OSAPI_LogEntry_T *entry)

Optional user-defined function for processing new log messages.

Definition of a function that can be installed with the logger and that will be called for each new log event.

The handler is set by OSAPI_Log_set_log_handler().

The function is called while holding a global lock.

When called, provides parameters containing the raw log entry and additional optional information.

Parameters

[in]	param	User-defined parameter
[in]	entry	Log entry

Enumeration Type Documentation

◆ OSAPI_LogVerbosity_T

enum OSAPI_LogVerbosity_T

Logging verbosity.

Enumerator
OSAPI_LOG_VERBOSITY_SILENT	Logs are not written.
OSAPI_LOG_VERBOSITY_ERROR	Only error logs are written.
OSAPI_LOG_VERBOSITY_WARNING	Error and warning logs are written.
OSAPI_LOG_VERBOSITY_DEBUG	All logs are written.

Function Documentation

◆ OSAPI_Log_set_log_handler()

RTI_BOOL OSAPI_Log_set_log_handler	(	OSAPI_LogHandler_T	handler,
		void *	param )

Install a log handler.

The log functionality allows the user to specify a log handler. The log handler is a function which is called for every logged event. It is up to the user to decide what to do with the log message. The handler is a global function pointer.

Parameters

handler	<<in>> Pointer to log handler function
param	<<in>> Parameter passed to the log handler function. This parameter is transparent to the log functionality.

Returns: RTI_TRUE on success, RTI_FALSE on failure

◆ OSAPI_Log_get_log_handler()

RTI_BOOL OSAPI_Log_get_log_handler	(	OSAPI_LogHandler_T *	handler,
		void **	param )

Return the current log handler.

Parameters

handler	<<out>> Pointer to store log handler function
param	<<out>> Pointer to store the current log handler parameter.

Returns: RTI_TRUE on success, RTI_FALSE on failure

◆ OSAPI_Log_set_display_handler()

RTI_BOOL OSAPI_Log_set_display_handler	(	OSAPI_LogDisplay_T	handler,
		void *	param )

Install a display handler.

The display handler is responsible for outputting log messages to a console.

Parameters

handler	<<in>> Pointer to display function
param	<<in>> Parameter passed to the display handler function. This parameter is transparent to the log functionality.

Returns: RTI_TRUE on success, RTI_FALSE on failure

◆ OSAPI_Log_get_display_handler()

RTI_BOOL OSAPI_Log_get_display_handler	(	OSAPI_LogDisplay_T *	handler,
		void **	param )

Return the current display function.

Return the current log handler.

Parameters

handler	<<in>> Pointer to store display handler function
param	<<in>> Pointer to store the current display handler parameters.

Returns: RTI_TRUE on success, RTI_FALSE on failure

◆ OSAPI_Log_set_verbosity()

void OSAPI_Log_set_verbosity ( OSAPI_LogVerbosity_T verbosity )

Set the log verbosity.

Change the log verbosity. The new setting takes immediate effect.

Parameters

verbosity <<in>> New log verbosity

◆ OSAPI_Log_clear()

RTI_BOOL OSAPI_Log_clear ( void )

Clear the log buffer.

Clear the log buffer, all the current entries are lost.

NOTE: This function must only be called inside a log-handler as it is not thread-safe.

Returns: RTI_TRUE on success, RTI_FALSE on failure

◆ OSAPI_Log_get_property()

void OSAPI_Log_get_property ( struct OSAPI_LogProperty * property )

Get the current log properties.

Return the current log properties

Parameters

property <<out>> Current log properties

◆ OSAPI_Log_set_property()

RTI_BOOL OSAPI_Log_set_property ( struct OSAPI_LogProperty * property )

Set the current log properties.

Configures the logging system before it is initialized. This function must be called before OSAPI_Log_initialize; calling it after initialization has no effect.

The OSAPI_LogProperty structure has three configurable fields:

max_buffer_size — the total number of bytes allocated to the in-memory log ring buffer. When this limit is reached, no further log entries can be stored until the buffer is cleared with OSAPI_Log_clear.

log_detail — a bitmap that controls which fields are recorded per log entry. See OSAPI_LogProperty::log_detail for the available flags and their meaning.

write_buffer — an optional function pointer of type ::DDS_OSAPI_Log_write_buffer_T that is invoked when the log buffer is output. If NULL, the default in-memory ring buffer behaviour is used.

Use OSAPI_LogProperty_INITIALIZER to obtain a structure pre-filled with sensible defaults, then modify only the fields that need to change. Use OSAPI_Log_get_property to read the current settings before modifying them.

Parameters

property <<in>> New log properties

◆ OSAPI_Log_get_verbosity()

OSAPI_LogVerbosity_T OSAPI_Log_get_verbosity ( void )

Get the current log verbosity.

Set the current log properties. It is not possible to set new properties after OSAPI_Log_initialize has been called.

Returns: Current verbosity

References RTI_INT32, and RTI_UINT32.

◆ OSAPI_Log_get_last_error_code()

RTI_INT32 OSAPI_Log_get_last_error_code ( void )

Returns the error code for a function that failed.

Many functions returns RTI_FALSE or NULL on failure. In order to provide additional information about reason for the failure fucntions may set an additional error code. This function returns the last error-code recorded for the calling thread.

Returns: Last error-code recorded for this thread

References RTI_INT32, RTI_INT64, and RTI_UINT32.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ OSAPI_LOG_DETAIL_MODULENAME

◆ OSAPI_LOG_DETAIL_SOURCEFILE

◆ OSAPI_LOG_DETAIL_LINENUMBER

◆ OSAPI_LOG_DETAIL_FUNCTIONAME

◆ OSAPI_LOG_DETAIL_DATA_ONLY

◆ OSAPI_LOG_DETAIL_ALL

◆ OSAPI_LOG_DETAIL_NO_DATA

◆ OSAPI_LogProperty_INITIALIZER

Typedef Documentation

◆ OSAPI_LogEntry_T

◆ OSAPI_Log_write_buffer_T

◆ OSAPI_LogHandler_T

Enumeration Type Documentation

◆ OSAPI_LogVerbosity_T

Function Documentation

◆ OSAPI_Log_set_log_handler()

◆ OSAPI_Log_get_log_handler()

◆ OSAPI_Log_set_display_handler()

◆ OSAPI_Log_get_display_handler()

◆ OSAPI_Log_set_verbosity()

◆ OSAPI_Log_clear()

◆ OSAPI_Log_get_property()

◆ OSAPI_Log_set_property()

◆ OSAPI_Log_get_verbosity()

◆ OSAPI_Log_get_last_error_code()