Pantheios Back-end API

---

Detailed Description

The Pantheios back-end API describes the required functionality of a back-end library.

The back-end is responsible solely for translating the log entry - severity indicator + length-specified, nul-terminated string - into output, as appropriate to its implementation.

There are several stock back-ends supplied with the Pantheios distribution (http://pantheios.org/), providing logging to stderr (using fprintf()), SysLog (using UNIX syslog(), or an emulation library on Windows), Windows Debugger, ACE output. You may also supply your own back-end by implementing the three simple functions of the API: pantheios_be_init(), pantheios_be_uninit(), and pantheios_be_logEntry().

Modules
	Pantheios Stock Back-ends
	Pre-built back-ends supplied with the Pantheios library.
	Pantheios Stock Back-end Ids
	Stock back-end identifiers used by the Pantheios back-end libraries.
	Pantheios Back-end Initialisation Flags
	Flags for the Pantheios Stock Back-ends.
Defines
#define	pantheios_be_console_parseArgs(numArgs, args, init)   pantheios_be_fprintf_parseArgs(numArgs, args, init)
	Parses the be.console back-end flags.
#define	pantheios_be_fprintf_parseArgs(num, args, init)   pantheios_be_parseStockArgs((num), (args), (NULL == (init)) ? NULL : (&(init)->flags))
	Parses the be.fprintf back-end flags.
#define	pantheios_be_null_parseArgs   NULL
	Parses the be.null back-end flags.
#define	pantheios_be_test_parseArgs   NULL
	Parses the be.test back-end flags.
#define	pantheios_be_WindowsDebugger_parseArgs(num, args, init)   pantheios_be_parseStockArgs((num), (args), (NULL == (init)) ? NULL : (&(init)->flags))
	Parses the be.WindowsDebugger back-end flags.
Functions
int	pantheios_be_init (PAN_CHAR_T const *processIdentity, void *reserved, void **ptoken)
	Initialises the back-end API.
void	pantheios_be_uninit (void *token)
	Uninitialises the back-end API.
int	pantheios_be_logEntry (void *feToken, void *beToken, int severity, PAN_CHAR_T const *entry, size_t cchEntry)
	Passes a log-entry to the back-end API.
int	pantheios_be_COMErrorObject_parseArgs (size_t numArgs, pantheios::pan_slice_t *const args, pan_be_COMErrorObject_init_t *init)
	Parses the be.COMErrorObject back-end flags.
int	pantheios_be_file_parseArgs (size_t numArgs, pantheios::pan_slice_t *const args, pan_be_file_init_t *init)
	Parses the be.file back-end flags.
int	pantheios_be_speech_parseArgs (size_t numArgs, pantheios::pan_slice_t *const args, pan_be_speech_init_t *init)
	Parses the be.speech back-end flags.
int	pantheios_be_syslog_parseArgs (size_t numArgs, pantheios::pan_slice_t *const args, pan_be_syslog_init_t *init)
	Parses the be.syslog back-end flags.
int	pantheios_be_WindowsConsole_parseArgs (size_t numArgs, pantheios::pan_slice_t *const args, pan_be_WindowsConsole_init_t *init)
	Parses the be.WindowsConsole back-end flags.
int	pantheios_be_WindowsSyslog_parseArgs (size_t numArgs, pantheios::pan_slice_t *const args, pan_be_WindowsSyslog_init_t *init)
	Parses the be.WindowsSyslog back-end flags.
int	pantheios_be_parseBooleanArg (size_t numArgs, pantheios::pan_slice_t *const args, pantheios::pan_char_t const *argName, int flagSuppressesAction, pantheios::pan_uint32_t flagValue, pantheios::uint32_t *flags)
	Parses a single boolean back-end argument.
int	pantheios_be_parseStringArg (size_t numArgs, pantheios::pan_slice_t *const args, pantheios::pan_char_t const *argName, pantheios::pan_slice_t *argValue)
	Parses a single string back-end argument.
int	pantheios_be_parseStockArgs (size_t numArgs, pantheios::pan_slice_t *const args, pantheios::uint32_t *flags)
	Parses the stock back-end arguments.

---

Define Documentation

#define pantheios_be_console_parseArgs	(	numArgs,
		args,
		init		)	pantheios_be_fprintf_parseArgs(numArgs, args, init)

Parses the be.console back-end flags.

Processes an argument list in the same way as pantheios_be_parseStockArgs(), filling out the pan_be_console_init_t in accordance with the arguments found.

Recognises the following standard argument names:

• "showProcessId" (Boolean)
• "showTime" (Boolean)
• "showSeverity" (Boolean)
• "useSystemTime" (Boolean)
• "showDetailsAtStart" (Boolean)
• "useUnixFormat" (Boolean)
• "showDate" (Boolean)
• "showTime" (Boolean)
• "highResolution" (Boolean)
• "lowResolution" (Boolean)

Recognises the following back-end specific argument names:

• "noColours" (Boolean) - Windows-only
• "noColors" (Boolean) - Windows-only

#define pantheios_be_fprintf_parseArgs	(	num,
		args,
		init		)	pantheios_be_parseStockArgs((num), (args), (NULL == (init)) ? NULL : (&(init)->flags))

Parses the be.fprintf back-end flags.

Processes an argument list in the same way as pantheios_be_parseStockArgs(), filling out the pan_be_fprintf_init_t in accordance with the arguments found.

Recognises the following standard argument names:

• "showProcessId" (Boolean)
• "showTime" (Boolean)
• "showSeverity" (Boolean)
• "useSystemTime" (Boolean)
• "showDetailsAtStart" (Boolean)
• "useUnixFormat" (Boolean)
• "showDate" (Boolean)
• "showTime" (Boolean)
• "highResolution" (Boolean)
• "lowResolution" (Boolean)

There are currently no back-end specific arguments, hence pantheios_be_fprintf_parseArgs is actually a #define for pantheios_be_parseStockArgs. At such time as back-end specific arguments are required, it will become a first-class function.

#define pantheios_be_null_parseArgs   NULL

Parses the be.null back-end flags.

There are currently no arguments whatsoever for be.null, hence pantheios_be_null_parseArgs is actually a #define for NULL. At such time as back-end specific arguments are required, it will become a first-class function.

#define pantheios_be_test_parseArgs   NULL

Parses the be.test back-end flags.

There are currently no arguments whatsoever for be.test, hence pantheios_be_test_parseArgs is actually a #define for NULL. At such time as back-end specific arguments are required, it will become a first-class function.

#define pantheios_be_WindowsDebugger_parseArgs	(	num,
		args,
		init		)	pantheios_be_parseStockArgs((num), (args), (NULL == (init)) ? NULL : (&(init)->flags))

Parses the be.WindowsDebugger back-end flags.

Processes an argument list in the same way as pantheios_be_parseStockArgs(), filling out the pan_be_WindowsDebugger_init_t in accordance with the arguments found.

Recognises the following standard argument names:

• "showProcessId" (Boolean)
• "showTime" (Boolean)
• "showSeverity" (Boolean)
• "useSystemTime" (Boolean)
• "showDetailsAtStart" (Boolean)
• "useUnixFormat" (Boolean)
• "showDate" (Boolean)
• "showTime" (Boolean)
• "highResolution" (Boolean)
• "lowResolution" (Boolean)

There are currently no back-end specific arguments, hence pantheios_be_WindowsDebugger_parseArgs is actually a #define for pantheios_be_parseStockArgs. At such time as back-end specific arguments are required, it will become a first-class function.

---

Function Documentation

int pantheios_be_COMErrorObject_parseArgs	(	size_t	numArgs,
		pantheios::pan_slice_t *const	args,
		pan_be_COMErrorObject_init_t *	init
	)

Parses the be.COMErrorObject back-end flags.

Processes an argument list in the same way as pantheios_be_parseStockArgs(), filling out the pan_be_COMErrorObject_init_t in accordance with the arguments found.

Recognises the following standard argument names:

• "showProcessId" (Boolean)
• "showTime" (Boolean)
• "showSeverity" (Boolean)
• "useSystemTime" (Boolean)
• "showDetailsAtStart" (Boolean)
• "useUnixFormat" (Boolean)
• "showDate" (Boolean)
• "showTime" (Boolean)
• "highResolution" (Boolean)
• "lowResolution" (Boolean)

Recognises the following back-end specific argument names:

• "overwriteExisting" (Boolean)

int pantheios_be_file_parseArgs	(	size_t	numArgs,
		pantheios::pan_slice_t *const	args,
		pan_be_file_init_t *	init
	)

Parses the be.file back-end flags.

Processes an argument list in the same way as pantheios_be_parseStockArgs(), filling out the pan_be_COMErrorObject_init_t in accordance with the arguments found.

Recognises the following standard argument names:

• "showProcessId" (Boolean)
• "showTime" (Boolean)
• "showSeverity" (Boolean)
• "useSystemTime" (Boolean)
• "showDetailsAtStart" (Boolean)
• "useUnixFormat" (Boolean)
• "showDate" (Boolean)
• "showTime" (Boolean)
• "highResolution" (Boolean)
• "lowResolution" (Boolean)

Recognises the following back-end specific argument names:

• "fileName" (String)
• "truncate" (Boolean)
• "discardCachedContents" (Boolean)
• "writeMultibyteContents" (Boolean)
• "writeWideContents" (Boolean)

int pantheios_be_init	(	PAN_CHAR_T const *	processIdentity,
		void *	reserved,
		void **	ptoken
	)

Initialises the back-end API.

This function is called once by the Pantheios core library to initialise the back-end library. It passes the process identity (in the form of a nul-terminated C-style string) and a second parameter (reserved for future use; currently always has value 0), which the back-end may use in its initialisation. The third parameter is a pointer to a void*, with which the back-end may store state, to be passed back to it in the pantheios_be_logEntry() and pantheios_be_uninit() functions.

Parameters:

	processIdentity	The identity of the process within which Pantheios is being used. Should be a meaningful human-readable string. Must not be NULL. Maximum length is limited solely by what the back-end library can accomodate. The string pointed to by this parameter may not persist after the call is complete, so the back-end should take a copy if required.
	reserved	Currently reserved. Will contain 0 in the current version of the Pantheios library
	ptoken	Pointer to a variable to receive the back-end token, which will be stored in the Pantheios library and passed to the pantheios_be_logEntry() and pantheios_be_uninit() functions

Note:

This function must be defined by each back-end implementation

This function is called at most once per process.

Returns:

A status indicating whether the back-end is initialised, and therefore whether the Pantheios library as a whole is initialised.

Return values:

	<0	Initialisation failed.
	>=0	Initialisation succeeded

Examples:

cpp/custom/example.cpp.custom.wrap_log4cplus/example.cpp.custom.wrap_log4cplus.cpp, cpp/custom/example.cpp.custom.wrap_log4cxx/example.cpp.custom.wrap_log4cxx.cpp, and cpp/misc/example.cpp.misc.extended_severity_information/example.cpp.misc.extended_severity_information.cpp.

int pantheios_be_logEntry	(	void *	feToken,
		void *	beToken,
		int	severity,
		PAN_CHAR_T const *	entry,
		size_t	cchEntry
	)

Passes a log-entry to the back-end API.

This function is called by the Pantheios core library to emit a log entry. It is passed five parameters. The severity, entry and cchEntry parameters describe the severity level, and the nul-terminated contents of the log entry. The feToken and beToken parameters hold the library-specific state of the front-end and back-end librarys, respectively.

Note:

This function must be defined by each back-end implementation

This may be called from any thread in a multi-threaded process.

Parameters:

	feToken	The front-end token, created by the pantheios_fe_init() function. This value does not hold any meaning to the back-end library, and may be used only to passed back to the front-end in calls to pantheios_fe_isSeverityLogged().
	beToken	The back-end token, created by the pantheios_be_init() function
	severity	The severity level.
	entry	The nul-terminated string containing the entry information
	cchEntry	The number of bytes in the string, not including the nul-terminating character

Examples:

cpp/custom/example.cpp.custom.wrap_log4cplus/example.cpp.custom.wrap_log4cplus.cpp, cpp/custom/example.cpp.custom.wrap_log4cxx/example.cpp.custom.wrap_log4cxx.cpp, and cpp/misc/example.cpp.misc.extended_severity_information/example.cpp.misc.extended_severity_information.cpp.

int pantheios_be_parseBooleanArg	(	size_t	numArgs,
		pantheios::pan_slice_t *const	args,
		pantheios::pan_char_t const *	argName,
		int	flagSuppressesAction,
		pantheios::pan_uint32_t	flagValue,
		pantheios::uint32_t *	flags
	)

Parses a single boolean back-end argument.

Searches the argument slices list for an argument of the given name. If it has one of the values ['yes', 'true', 'no', 'false'] the flags parameter is adjusted to either set or remove the flagValue value, as directed by the flagSuppressesAction parameter, and the argument is marked as having been processed by setting its length to 0.

Parameters:

	numArgs	Number of elements in the argument array. May be 0
	args	Pointer to the base of the argument array. May only be NULL if numArgs is 0
	argName	The name of the value to look for. May not be NULL
	flagSuppressesAction	Indicates whether the flagValue is a suppression flag, such as PANTHEIOS_BE_INIT_F_NO_SEVERITY, rather than an activation flag, such as PANTHEIOS_BE_INIT_F_USE_SYSTEM_TIME.
	flagValue	A flag value, such as PANTHEIOS_BE_INIT_F_NO_SEVERITY
	flags	A pointer to a flags variable whose value may be modified upon a successful match. May not be NULL.

Returns:

An indication of whether a valid argument was found

Return values:

	0	No matching arguments were found, or the argument was found but did not have boolean values
	1	An argument with the given name, and with values interpretable as boolean, was found.

Precondition:

NULL != args || 0 == numArgs

NULL != argName

NULL != flags

int pantheios_be_parseStockArgs	(	size_t	numArgs,
		pantheios::pan_slice_t *const	args,
		pantheios::uint32_t *	flags
	)

Parses the stock back-end arguments.

Searches the argument slices list for the arguments associated with all stock Pantheios Back-end Initialisation Flags. For each argument found (and having an appropriate value; see pantheios_be_parseBooleanArg()) its value is processed, the flags parameter's value is adjusted accordingly, and the argument slice's length is set to 0 to indicate that it has been successfully processed. Returns the number of arguments successfully matched.

Recognises the following argument names:

• "showProcessId" (Boolean)
• "showTime" (Boolean)
• "showSeverity" (Boolean)
• "useSystemTime" (Boolean)
• "showDetailsAtStart" (Boolean)
• "useUnixFormat" (Boolean)
• "showDate" (Boolean)
• "showTime" (Boolean)
• "highResolution" (Boolean)
• "lowResolution" (Boolean)

Parameters:

	numArgs	Number of elements in the argument array. May be 0
	args	Pointer to the base of the argument array. May only be NULL if numArgs is 0
	flags	A pointer to a flags variable whose value may be modified upon a successful matches. May not be NULL.

Returns:

The number of arguments successfully matched

Precondition:

NULL != args || 0 == numArgs

NULL != flags

int pantheios_be_parseStringArg	(	size_t	numArgs,
		pantheios::pan_slice_t *const	args,
		pantheios::pan_char_t const *	argName,
		pantheios::pan_slice_t *	argValue
	)

Parses a single string back-end argument.

Searches the argument slices list for an argument of the given name. If found, it transfers the slice (i.e. copies the pointers) to the given argument value parameter.

Parameters:

	numArgs	Number of elements in the argument array. May be 0
	args	Pointer to the base of the argument array. May only be NULL if numArgs is 0
	argName	The name of the value to look for. May not be NULL
	argValue	A pointer to a slice that will receive the value part of an argument if successfully matched. May not be NULL.

Precondition:

NULL != args || 0 == numArgs

NULL != argName

NULL != argValue

int pantheios_be_speech_parseArgs	(	size_t	numArgs,
		pantheios::pan_slice_t *const	args,
		pan_be_speech_init_t *	init
	)

Parses the be.speech back-end flags.

int pantheios_be_syslog_parseArgs	(	size_t	numArgs,
		pantheios::pan_slice_t *const	args,
		pan_be_syslog_init_t *	init
	)

Parses the be.syslog back-end flags.

Processes an argument list in the same way as pantheios_be_parseStockArgs(), filling out the pan_be_COMErrorObject_init_t in accordance with the arguments found.

Recognises the following standard argument names:

• "showProcessId" (Boolean)
• "showTime" (Boolean)
• "showSeverity" (Boolean)
• "useSystemTime" (Boolean)
• "showDetailsAtStart" (Boolean)
• "useUnixFormat" (Boolean)
• "showDate" (Boolean)
• "showTime" (Boolean)
• "highResolution" (Boolean)
• "lowResolution" (Boolean)

Recognises the following back-end specific argument names:

• "useStderr" (Boolean)
• "useConsole" (Boolean)
• "showPid" (Boolean)
• "connectImmediately" (Boolean)

void pantheios_be_uninit

(

void *

token

)

Uninitialises the back-end API.

This function is called to uninitialise the back-end library during the uninitialisation of the Pantheios core library. It is passed the value of the token stored on its behalf by the Pantheios core library.

Note:

This function must be defined by each back-end implementation

This function is called at most once per process.

Parameters:

token

The back-end token, created by the pantheios_be_init() function

Examples:

cpp/custom/example.cpp.custom.wrap_log4cplus/example.cpp.custom.wrap_log4cplus.cpp, cpp/custom/example.cpp.custom.wrap_log4cxx/example.cpp.custom.wrap_log4cxx.cpp, and cpp/misc/example.cpp.misc.extended_severity_information/example.cpp.misc.extended_severity_information.cpp.

int pantheios_be_WindowsConsole_parseArgs	(	size_t	numArgs,
		pantheios::pan_slice_t *const	args,
		pan_be_WindowsConsole_init_t *	init
	)

Parses the be.WindowsConsole back-end flags.

Processes an argument list in the same way as pantheios_be_parseStockArgs(), filling out the pan_be_WindowsConsole_init_t in accordance with the arguments found.

Recognises the following standard argument names:

• "showProcessId" (Boolean)
• "showTime" (Boolean)
• "showSeverity" (Boolean)
• "useSystemTime" (Boolean)
• "showDetailsAtStart" (Boolean)
• "useUnixFormat" (Boolean)
• "showDate" (Boolean)
• "showTime" (Boolean)
• "highResolution" (Boolean)
• "lowResolution" (Boolean)

Recognises the following back-end specific argument names:

• "noColours" (Boolean)
• "noColors" (Boolean)

int pantheios_be_WindowsSyslog_parseArgs	(	size_t	numArgs,
		pantheios::pan_slice_t *const	args,
		pan_be_WindowsSyslog_init_t *	init
	)

Parses the be.WindowsSyslog back-end flags.

Processes an argument list in the same way as pantheios_be_parseStockArgs(), filling out the pan_be_COMErrorObject_init_t in accordance with the arguments found.

Recognises the following standard argument names:

• "showProcessId" (Boolean)
• "showTime" (Boolean)
• "showSeverity" (Boolean)
• "useSystemTime" (Boolean)
• "showDetailsAtStart" (Boolean)
• "useUnixFormat" (Boolean)
• "showDate" (Boolean)
• "showTime" (Boolean)
• "highResolution" (Boolean)
• "lowResolution" (Boolean)

Recognises the following back-end specific argument names:

• "address" (String: hostname or dotted IPv4 address)
• "port" (Number)
• "facility" (Number)
• "useStderr" (Boolean)
• "useConsole" (Boolean)
• "showPid" (Boolean)
• "connectImmediately" (Boolean)

pantheios Library documentation © Matthew Wilson & Synesis Software, 2006-2011