Main Page | Modules | Namespace List | Class Hierarchy | Class List | File List | Class Members | File Members

VXIlogInterface Struct Reference
[Logging Interface]

#include <VXIlog.h>

List of all members.


Detailed Description

VXIlog interface for logging The VXIlogInterface provides a set of functions which are used for logging by all the OpenVXI browser components.


Public Attributes

VXIint32(* GetVersion )(void)
 Get the VXI interface version implemented.
const VXIchar *(* GetImplementationName )(void)
 Get the name of the implementation.
VXIlogResult(* Error )(struct VXIlogInterface *pThis, const VXIchar *moduleName, VXIunsigned errorID, const VXIchar *format,...)
 Log an error Basic error reporting mechanism.
VXIlogResult(* VError )(struct VXIlogInterface *pThis, const VXIchar *moduleName, VXIunsigned errorID, const VXIchar *format, va_list vargs)
 Log an error (va_list variant).
VXIlogResult(* Diagnostic )(struct VXIlogInterface *pThis, VXIunsigned tagID, const VXIchar *subtag, const VXIchar *format,...)
 Log a diagnostic message.
VXIlogResult(* VDiagnostic )(struct VXIlogInterface *pThis, VXIunsigned tagID, const VXIchar *subtag, const VXIchar *format, va_list vargs)
 Log a diagnostic message (va_list variant).
VXIbool(* DiagnosticIsEnabled )(struct VXIlogInterface *pThis, VXIunsigned tagID)
 Query whether diagnostic logging is enabled.
VXIlogResult(* Event )(struct VXIlogInterface *pThis, VXIunsigned eventID, const VXIchar *format,...)
 Log an event.
VXIlogResult(* VEvent )(struct VXIlogInterface *pThis, VXIunsigned eventID, const VXIchar *format, va_list vargs)
 Log an event (va_list variant).
VXIlogResult(* EventVector )(struct VXIlogInterface *pThis, VXIunsigned eventID, const VXIVector *keys, const VXIVector *values)
 Log an event (VXIVector variant).
VXIlogResult(* ContentOpen )(struct VXIlogInterface *pThis, const VXIchar *moduleName, const VXIchar *contentType, VXIString **logKey, VXIString **logValue, VXIlogStream **stream)
 Open a handle to log (potentially large or binary) content.
VXIlogResult(* ContentClose )(struct VXIlogInterface *pThis, VXIlogStream **stream)
 Close a stream for logging (potentially large or binary) content.
VXIlogResult(* ContentWrite )(struct VXIlogInterface *pThis, const VXIbyte *buffer, VXIulong buflen, VXIulong *nwritten, VXIlogStream *stream)
 Write (potentially large or binary) content to a logging stream.


Member Data Documentation

VXIlogResult(* VXIlogInterface::ContentClose)(struct VXIlogInterface *pThis, VXIlogStream **stream)
 

Close a stream for logging (potentially large or binary) content.

NOTE: This is only available as of version 1.1 of the VXIlogInterface, use LOG_CONTENT_METHODS_SUPPORTED( ) to determine availability.

Close a content stream that was previously opened. Closing a NULL or previously closed stream will result in an error.

Parameters:
stream [IN/OUT] Handle to the stream to close, will be set to NULL on success
Returns:
VXIlog_RESULT_SUCCESS on success

VXIlogResult(* VXIlogInterface::ContentOpen)(struct VXIlogInterface *pThis, const VXIchar *moduleName, const VXIchar *contentType, VXIString **logKey, VXIString **logValue, VXIlogStream **stream)
 

Open a handle to log (potentially large or binary) content.

NOTE: This is only available as of version 1.1 of the VXIlogInterface, use LOG_CONTENT_METHODS_SUPPORTED( ) to determine availability.

In situations where large blocks of data need to be logged and/or the data is binary, this method should be used to open a content logging stream. Data is written via ContentWrite( ), and the stream is then closed via ContentClose( ). The key/value pair returned by this method indicates the location of the logged data, and should be used to reference this content within error, event, and/or diagnostic messages.

Parameters:
moduleName [IN] Name of the software module that is outputting the data. See the top of this file for moduleName allocation rules.
contentType [IN] MIME content type for the data
logKey [OUT] Key name to cross-reference this content in logging errors, events, and/or diagnostic messages. Ownership is passed on success, call VXIStringDestroy( ) to free this when no longer required.
logValue [OUT] Value to cross-reference this content in logging errors, events, and/or diagnostic messages. Ownership is passed on success, call VXIStringDestroy( ) to free this when no longer required.
stream [OUT] Handle for writing the content via ContentWrite( ) and closing it via ContentClose( )
Returns:
VXIlog_RESULT_SUCCESS on success

VXIlogResult(* VXIlogInterface::ContentWrite)(struct VXIlogInterface *pThis, const VXIbyte *buffer, VXIulong buflen, VXIulong *nwritten, VXIlogStream *stream)
 

Write (potentially large or binary) content to a logging stream.

NOTE: This is only available as of version 1.1 of the VXIlogInterface, use LOG_CONTENT_METHODS_SUPPORTED( ) to determine availability.

Write data to a content stream that was previously opened.

Parameters:
buffer [OUT] Buffer of data to write to the stream
buflen [IN] Number of bytes to write
nwritten [OUT] Number of bytes actual written, may be less then buflen if an error is returned
stream [IN] Handle to the stream to write to
Returns:
VXIlog_RESULT_SUCCESS on success

VXIlogResult(* VXIlogInterface::Diagnostic)(struct VXIlogInterface *pThis, VXIunsigned tagID, const VXIchar *subtag, const VXIchar *format,...)
 

Log a diagnostic message.

Basic diagnostic reporting mechanism. Diagnostic messages are reported by moduleName, tag id, subtag, a format, and a variable length argument list.

Parameters:
tagID [IN] Identifier that classifies a group of logically associated diagnostic messages (usually from a single software module) that are desirable to enable or disable as a single unit. See the top of this file for tagID allocation rules.
subtag [IN] Arbitrary string that may be used to subdivide the diagnostic messages of that tagID, or provide additional standardized information such as the source file, function, or method. There are no rules for the content of this field.
format [IN] Format string as passed to wprintf( ) (the wchar_t version of printf( ) as defined by the ANSI C standard) for outputting free-form diagnostic text. This is followed by a variable list of arguments that supply values for insertion into the format string, also as passed to wprintf( ).

NOTE: Do NOT use C and S in the format string for inserting narrow character strings (char and char *) as supported by some compilers, as this is not portable and may result in system crashes on some UNIX variants if the VXIlog implementation uses the compiler supplied ...printf( ) family of functions for handling these variable argument lists.

Parameters:
... [IN] Arguments matching the free-form diagnostic text format specified above.
Returns:
VXIlog_RESULT_SUCCESS on success

VXIbool(* VXIlogInterface::DiagnosticIsEnabled)(struct VXIlogInterface *pThis, VXIunsigned tagID)
 

Query whether diagnostic logging is enabled.

NOTE: Diagnostic log messages are automatically filtered in a high-performance way by the Diagnostic method. This should only be used in the rare conditions when there is significant pre-processing work required to assemble the input parameters for Diagnostic( ), and thus it is best to suppress that performance impacting pre-processing as well.

Parameters:
tagID [IN] Identifier for a class of
Returns:
TRUE if that tag is enabled (information for that tag will be written to the diagnostic log), FALSE if that tag is disabled (information for that tag will be ignored)

VXIlogResult(* VXIlogInterface::Error)(struct VXIlogInterface *pThis, const VXIchar *moduleName, VXIunsigned errorID, const VXIchar *format,...)
 

Log an error Basic error reporting mechanism.

Errors are reported by moduleName, error number, a format, and a varargs argument list.

IMPORTANT: Error details are not free-form, they must be passed as a succession of key-value pairs, i.e. a string key followed by a value. For example, this format string and arguments is correct:

L"siss", L"key1", 911, L"key2", L"value2"

While this one is incorrect (second key missing):

L"sif", L"key1", 911, (float)22 / 7

Keys must always be specified by a s, and the key names must follow the rules for XML names as summarized at the top of this header. Values may be specified by the ANSI C defined format parameters for printf( ), including the ability to control string widths, number of decimals to output, padding etc. There are no restrictions on the variable values, it is the responsibility of the logging system to escape the variable values if required by the final output stream (such as output via XML).

NOTE: Do NOT use C and S in the format string for inserting narrow character buffers (char and char *) as supported by some compilers, as this is not portable and may result in system crashes on some UNIX variants if the VXIlog implementation uses the compiler supplied printf( ) family of functions for handling these variable argument lists.

Parameters:
moduleName [IN] Name of the software module that is outputting the error. See the top of this file for moduleName allocation rules.
errorID [IN] Error number to log, this is mapped to localized error text that is displayed to the system operator that has an associated severity level. It is CRITICAL that this provides primary, specific, actionable information to the system operator, with attribute/value pairs only used to provide details. See the top of this file for errorID allocation rules.
format [IN] Format string as passed to wprintf( ) (the wchar_t version of printf( ) as defined by the ANSI C standard) for outputting optional error details. This is followed by a variable list of arguments supplying variables for insertion into the format string, also as passed to wprintf( ).
... [IN] Arguments matching the error details format specified above.
Returns:
VXIlog_RESULT_SUCCESS on success

VXIlogResult(* VXIlogInterface::Event)(struct VXIlogInterface *pThis, VXIunsigned eventID, const VXIchar *format,...)
 

Log an event.

Basic error reporting mechanism. Errors are reported by moduleName, error number, and with a varargs format. Event details are not free-form, they must be passed as a succession of key-value pairs, i.e. a string key followed by a value. See the description of the format parameter for <a=href="Error.html"> Error for a full explanation.

Parameters:
eventID [IN] Event number to log, this is mapped to a localized event name that is placed in the event log. It is critical that this provide unambiguous information about the nature of the event. See the top of this file for eventID allocation rules.
format [IN] Format string as passed to wprintf( ) (the wchar_t version of printf( ) as defined by the ANSI C standard) for outputting optional event details. This is followed by a variable list of arguments supplying values for insertion into the format string, also as passed to wprintf().

IMPORTANT: Event details are not free-form, they must be passed as a succession of key-value pairs, i.e. a string key followed by a value. See the description of the format parameter for Error for a full explanation.

Parameters:
... [IN] Arguments matching the event details format specified above.
Returns:
VXIlog_RESULT_SUCCESS on success

VXIlogResult(* VXIlogInterface::EventVector)(struct VXIlogInterface *pThis, VXIunsigned eventID, const VXIVector *keys, const VXIVector *values)
 

Log an event (VXIVector variant).

NOTE: This is only available as of version 1.1 of the VXIlogInterface, use LOG_EVENT_VECTOR_SUPPORTED( ) to determine availability.

Same as Event , but a vector of keys and a vector of values is supplied as arguments to make it possible to build dynamic lists of key/value pairs for logging (such as event logging of recognition results)

Parameters:
eventID [IN] Event number to log, this is mapped to a localized event name that is placed in the event log. It is critical that this provide unambiguous information about the nature of the event. See the top of this file for eventID allocation rules.
keys [IN] Key names for the event data, where keys[i] is the key for the value in value[i]. Each key must be a VXIString.
values [IN] Values for the event data. Each value must be a VXIInteger, VXIFloat, VXIString, or VXIPtr.
Returns:
VXIlog_RESULT_SUCCESS on success

const VXIchar*(* VXIlogInterface::GetImplementationName)(void)
 

Get the name of the implementation.

Returns:
Implementation defined string that must be different from all other implementations. The recommended name is one where the interface name is prefixed by the implementator's Internet address in reverse order, such as com.xyz.rec for VXIrec from xyz.com. This is similar to how VoiceXML 1.0 recommends defining application specific error types.

VXIint32(* VXIlogInterface::GetVersion)(void)
 

Get the VXI interface version implemented.

Returns:
VXIint32 for the version number. The high high word is the major version number, the low word is the minor version number, using the native CPU/OS byte order. The current version is VXI_CURRENT_VERSION as defined in VXItypes.h.

VXIlogResult(* VXIlogInterface::VDiagnostic)(struct VXIlogInterface *pThis, VXIunsigned tagID, const VXIchar *subtag, const VXIchar *format, va_list vargs)
 

Log a diagnostic message (va_list variant).

Same as Diagnostic, but a va_list is supplied as an argument instead of "..." in order to make it easy to layer convenience functions/classes for logging on top of this interface.

Returns:
VXIlog_RESULT_SUCCESS on success

VXIlogResult(* VXIlogInterface::VError)(struct VXIlogInterface *pThis, const VXIchar *moduleName, VXIunsigned errorID, const VXIchar *format, va_list vargs)
 

Log an error (va_list variant).

Same as Error, but a va_list is supplied as an argument instead of "..." in order to make it easy to layer convenience functions/classes for logging on top of this interface.

Returns:
VXIlog_RESULT_SUCCESS on success

VXIlogResult(* VXIlogInterface::VEvent)(struct VXIlogInterface *pThis, VXIunsigned eventID, const VXIchar *format, va_list vargs)
 

Log an event (va_list variant).

Same as Event , but a va_list is supplied as an argument instead of "..." in order to make it easy to layer convenience functions/classes for logging on top of this interface.

Returns:
VXIlog_RESULT_SUCCESS on success


The documentation for this struct was generated from the following file:
Generated on Wed Jun 1 12:50:19 2005 for OpenVXI by  doxygen 1.4.2