Across all streams, the log implementation is responsible for automatically supplying the following information in some manner (possibly encoded into a file name, possibly in a data header, possibly as part of each log message) for end consumer use:
In addition, for diagnostic logging the log implementation is responsible for defining a mechanism for enabling/disabling messages on an individual tag basis without requiring a recompile for use by consumers of the diagnostic log. It is critical that Diagnostic( ) is highly efficient for cases when the tag is disabled: in other words, the lookup for seeing if a tag (an integer) is enabled should be done using a simple array or some other extremely low-overhead mechanism. It is highly recommended that log implementations provide a way to enable/disable tags on-the-fly (without needing to restart the software), and log implementations should consider providing a way to enable/disable tabs on a per-channel basis (for enabling tags in tight loops where the performance impact can be large).
Each of the streams has fields that need to be allocated by developers. The rules for each follows. As background, several of these fields require following the rules for XML names: it must begin with a letter, underscore, or colon, and is followed by one or more of those plus digits, hyphens, or periods. However, colons must only be used when indicating XML namespaces, and the "vxi" and "swi" namespaces (such as "swi:SBprompt") are reserved for use by Vocalocity, Inc.
Module names (moduleName) must follow XML name rules as described above, and must be unique for each implementation of each VXI interface.
Error IDs (errorID) are unsigned integers that for each module start at 0 and increase from there, allocated by each named module as it sees fit. Each VXI interface implementation must provide a document that provides the list of error IDs and the recommended text (for at least one language) and severity. Severities should be constrained to one of three levels: "Critical - out of service" (affects multiple callers), "Severe - service affecting" (affects a single caller), "Warning - not service affecting" (not readily apparent to callers, or it is at least fairly likely callers will not notice).
Attribute names must follow XML name rules as described above. However, these need not be unique for each implementation as they are interpreted relative to the module name (and frequently not interpreted at all, but merely output). For consumer convenience the data type for each attribute name should never vary, although most log implementations will not enforce this.
Tags (tagID) are unsigned integers that must be globally unique across the entire run-time environment in order to allow VXIlog implementations to have very low overhead diagnostic log enablement lookups (see above). The recommended mechanism for avoiding conflicts with components produced by other developers is to make it so the initialization function for your component takes an unsigned integer argument that is a tag ID base. Then within your component code, allocate locally unique tag ID numbers starting at zero, but offset them by the base variable prior to calling the VXIlog Diagostic( ) method. This way integrators of your component can assign a non-conflicting base as they see fit.
There are no restrictions on subtag use, as they are relative to the tag ID and most log implementations will merely output them as a prefix to the diagnostic text.
Events (eventID) are unsigned integers that are defined by each developer as they see fit in coordination with other component developers to avoid overlaps. Globally unique events are required to make it easy for event log consumers to parse the log, all events should be well-known and well documented.
Attribute names must follow XML name rules as described above. However, these need not be unique for each implementation as they are interpreted relative to the module name (and frequently not interpreted at all, but merely output). For consumer convenience the data type for each attribute name should never vary, although most log implementations will not enforce this.
Module names (moduleName) must follow XML name rules as described above, and must be unique for each implementation of each VXI interface.
When a content stream is opened for writing data, a key/value pair is returned by the VXIlog interface. This key/value pair must be used to cross-reference this data in error, diagnostic, and/or event logging messages.
Classes | |
struct | VXIlogInterface |
VXIlog interface for logging The VXIlogInterface provides a set of functions which are used for logging by all the OpenVXI browser components. More... | |
Defines | |
#define | LOG_EVENT_VECTOR_SUPPORTED(logIntf) (logIntf->GetVersion( ) >= 0x00010001) |
Macros to determine the availability of new methods. | |
#define | LOG_CONTENT_METHODS_SUPPORTED(logIntf) (logIntf->GetVersion( ) >= 0x00010001) |
Typedefs | |
typedef *enum VXIlogEvent | VXIlogEvent |
Standard VXIlog events. | |
typedef enum VXIlogResult | VXIlogResult |
Result codes for interface methods. | |
typedef VXIlogInterface | VXIlogInterface |
VXIlog interface for logging The VXIlogInterface provides a set of functions which are used for logging by all the OpenVXI browser components. | |
Enumerations | |
enum | VXIlogEvent { VXIlog_EVENT_CALL_START = 0, VXIlog_EVENT_CALL_END = 1, VXIlog_EVENT_LOG_ELEMENT = 2, VXIlog_EVENT_SPEECH_DETECTED = 3, VXIlog_EVENT_ENDPOINTER_AUDIO = 4, VXIlog_EVENT_RECOGNIZER_AUDIO = 5, VXIlog_EVENT_RECOGNITION_START = 6, VXIlog_EVENT_RECOGNITION_END = 7, VXIlog_EVENT_SPEECH_RESULT = 8, VXIlog_EVENT_DTMF_RESULT = 9, VXIlog_EVENT_PLATFORM_DEFINED = 10000 } |
Standard VXIlog events. More... | |
enum | VXIlogResult { VXIlog_RESULT_FATAL_ERROR = -100, VXIlog_RESULT_IO_ERROR = -8, VXIlog_RESULT_OUT_OF_MEMORY = -7, VXIlog_RESULT_SYSTEM_ERROR = -6, VXIlog_RESULT_PLATFORM_ERROR = -5, VXIlog_RESULT_BUFFER_TOO_SMALL = -4, VXIlog_RESULT_INVALID_PROP_NAME = -3, VXIlog_RESULT_INVALID_PROP_VALUE = -2, VXIlog_RESULT_INVALID_ARGUMENT = -1, VXIlog_RESULT_SUCCESS = 0, VXIlog_RESULT_FAILURE = 1, VXIlog_RESULT_NON_FATAL_ERROR = 2, VXIlog_RESULT_UNSUPPORTED = 100 } |
Result codes for interface methods. More... | |
Functions | |
*SBLOGMAPPER_API VXIlogResult | SBlogErrorMapperCreate (const VXIVector *errorMapFiles, SBlogErrorMapper **mapper) |
Create a new XML error mapper. | |
SBLOGMAPPER_API VXIlogResult | SBlogErrorMapperDestroy (SBlogErrorMapper **mapper) |
Destroy an XML error mapper. | |
SBLOGMAPPER_API VXIlogResult | SBlogErrorMapperGetErrorInfo (SBlogErrorMapper *mapper, VXIunsigned errorID, const VXIchar *moduleName, const VXIchar **errorText, VXIint *severityLevel) |
Map an error ID to text and a severity. |
|
|
|
Macros to determine the availability of new methods.
|
|
Standard VXIlog events. Standardized events that may be reported to the VXIlog interface. Platform dependant events start at VXIlog_EVENT_PLATFORM_DEFINED and increase from there. |
|
VXIlog interface for logging The VXIlogInterface provides a set of functions which are used for logging by all the OpenVXI browser components.
|
|
Result codes for interface methods. Result codes less then zero are severe errors (likely to be platform faults), those greater then zero are warnings (likely to be application issues) |
|
|
Result codes for interface methods. Result codes less then zero are severe errors (likely to be platform faults), those greater then zero are warnings (likely to be application issues)
|
|
Create a new XML error mapper.
|
|
Destroy an XML error mapper.
|
|
Map an error ID to text and a severity.
|