Log API

Classes
struct	OSAPI_LogProperty
	Configuration of logging functionality. More...

Typedefs
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_trace_handler (OSAPI_TraceHandler_T handler, void *param)
	Install a trace handler.
RTI_BOOL	OSAPI_Log_get_trace_handler (OSAPI_TraceHandler_T *handler, void **param)
	Return the trace 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.
void	OSAPI_Trace_set_trace_mask (RTI_UINT32 mask)
	Set the trace mask.
RTI_BOOL	OSAPI_Log_clear (void)
	Clear the log buffer.
RTI_INT32	OSAPI_Log_get_last_error_code (void)
	Returns the error code for a function that failed.
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 log properties.

---

Detailed Description

---

Typedef Documentation

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:

[in]	buffer	Pointer to buffer with log to write
[in]	length	Length of the buffer to write

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().

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

Parameters:

[in]	param	User-defined payload
[in]	msg	Log entry
[in]	kind	Kind of log message
[in]	ec	Unique error code of log message
[in]	module	Module of log message
[in]	file	Name of source file. Optional.
[in]	func	Name of function. Optional.
[in]	line	Line number. Optional.
[in]	argc	Variable length argument count
[in]	ap	Variable length argument list

---

Enumeration Type Documentation

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

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:

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

Returns:

RTI_TRUE on success, RTI_FALSE on failure

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

Return the current log handler.

Return the current log handler.

Parameters:

[in]	handler	Pointer to store log handler function
[in]	param	Pointer to store the current log handler parameter.

Returns:

RTI_TRUE on success, RTI_FALSE on failure

RTI_BOOL OSAPI_Log_set_trace_handler	(	OSAPI_TraceHandler_T	handler,
		void *	param
	)

Install a trace handler.

Install a custom trace handler. Traces are not stored in the log-buffer and is generally used to analyze behavior interactively. the default trace handler outputs the trace data to a console.

Parameters:

[in]	handler	Pointer to trace handler function
[in]	param	Parameter passed to the trace handler function. This parameter is transparent to the trace functionality.

Returns:

RTI_TRUE on success, RTI_FALSE on failure

RTI_BOOL OSAPI_Log_get_trace_handler	(	OSAPI_TraceHandler_T *	handler,
		void **	param
	)

Return the trace handler.

Return the current trace handler and trace parameter. This information can be used to daisy-chain calls to multiple trace-handlers.

Parameters:

[in]	handler	Pointer to store trace handler function
[in]	param	Pointer to store the trace handler parameter.

Returns:

RTI_TRUE on success, RTI_FALSE on failure

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:

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

Returns:

RTI_TRUE on success, RTI_FALSE on failure

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

Return the current display function.

Return the current log handler.

Parameters:

[in]	handler	Pointer to store display handler function
[in]	param	Pointer to store the current display handler parameters.

Returns:

RTI_TRUE on success, RTI_FALSE on failure

void OSAPI_Log_set_verbosity

(

OSAPI_LogVerbosity_T

verbosity

)

Set the log verbosity.

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

Parameters:

[in]

verbosity

New log verbosity

void OSAPI_Trace_set_trace_mask

(

RTI_UINT32

mask

)

Set the trace mask.

Parameters:

[in]

mask

New trace mask

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 hander as it is not thread-safe.

Returns:

RTI_TRUE on success, RTI_FALSE on failure

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

void OSAPI_Log_get_property

(

struct OSAPI_LogProperty *

property

)

Get the current log properties.

Return the current log properties

Parameters:

[out]

property

- Current log properties

See Also OSAPI_Log_set_property

RTI_BOOL OSAPI_Log_set_property

(

struct OSAPI_LogProperty *

property

)

Set the log properties.

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

Parameters:

[in]

property

New log properties

Returns:

RTI_TRUE if new properties can be set, RTI_FALSE otherwise See Also OSAPI_Log_get_property