vxilog.h

OSB-PIK-OpenVXI-3.0.0源代码 “中国XML论坛 - 专业的XML技术讨论区--XML在语音技术中的应用”

 /****************License************************************************
  *
  * Copyright 2000-2003.  ScanSoft, Inc.    
  *
  * Use of this software is subject to notices and obligations set forth 
  * in the SpeechWorks Public License - Software Version 1.2 which is 
  * included with this software. 
  *
  * ScanSoft is a registered trademark of ScanSoft, Inc., and OpenSpeech, 
  * SpeechWorks and the SpeechWorks logo are registered trademarks or 
  * trademarks of SpeechWorks International, Inc. in the United States 
  * and other countries.
  *
  ***********************************************************************/
 

 #ifndef _VXILOG_H                 /* Allows multiple inclusions */
 #define _VXILOG_H
 
 #include <stdarg.h>               /* For va_list */
 #include "VXItypes.h"             /* For VXIchar */
 #include "VXIvalue.h"             /* For VXIString */
 
 #include "VXIheaderPrefix.h"
 #ifdef VXILOG_EXPORTS
 #define VXILOG_API SYMBOL_EXPORT_DECL
 #else
 #define VXILOG_API SYMBOL_IMPORT_DECL
 #endif
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 #ifdef __cplusplus
 struct VXIlogStream;
 #else
 typedef struct VXIlogStream { void * dummy; } VXIlogStream;
 #endif
 
 
 /**
   @name VXIlog
  
   @memo Abstract interface for logging errors, diagnostic logging, and
   event logging.
   @version 1.0 <br>		       
   @doc
   <ul>
   The VXIlog Facility supports the following types of log streams:
 
   <li><b> Error stream:</b><br/>
    Used to report system faults (errors) and possible system faults
    (warnings) to the system operator for diagnosis and repair. Errors
    are reported by error numbers that are mapped to text with an
    associated severity level. This mapping may be maintained in a
    separate XML document.  This allows integrators to localize and
    customize the text without code changes, and also allows integrators
    and developers to review and re-define severity levels without code
    changes. Optional attribute/value pairs are used to convey details
    about the fault, such the file or URL that is associated with the
    fault.
   </li>
  
   <li><b>Diagnostic stream: </b><br/>
    Used by developers and support staff to trace and diagnose system
    behavior. Diagnostic messages are hard-coded text since they are
    private messages that are not intended for system operator
    use. Diagnostic messages are all associated with developer defined
    "tags" for grouping, where each tag may be independently
    enabled/disabled. It is guaranteed that diagnostic logging will have
    little or no performance impact if the tag is disabled, meaning that
    developers should be generous in their insertion of diagnostic log
    messages. These will be disabled by default, but specific tags can
    then be enabled for rapid diagnosis with minimal performance impact
    when issues arise.
   </li>
 
   <li><b>Event stream: </b><br/>
    Summarizes normal caller activity in order to support service
    bureau billing; reporting for capacity planning, application and
    recognition monitoring, and caller behavior trending; and traces of
    individual calls for application tuning.  Events are reported by
    event numbers that are mapped to event names. Optional
    attribute/value pairs are used to convey details about the event,
    such as the base application for a new call event.
   </li>
 
   <li><b>Content stream: </b><br/>
    The content stream is not really a seperate conceptual stream: it
    is merely a mechanism to log large blocks of data (BLOBs) in a 
    flexible and efficient manner, for example diagnostic logging of
    the VoiceXML page being executed, or event logging of the audio
    input for recognition. To log this information, a request to
    open a content stream handle is made, then the data is written
    to that stream handle. Next the client uses a key/value pair
    returned by the VXIlog implementation to cross-reference the
    content within an appropriate error, diagnostic, or event log
    entry. This mechanism gives the VXIlog implementation high
    flexibility: the implementation may simply write each request
    to a new file and return a cross-reference key/value pair that
    indicates the file path (key = "URL", value = <path>), or may
    POST the data to a centralized web server, or may write each 
    request to a database. The system operator console software
    may then transparently join the error, diagnostic, and event
    log streams with the appropriate content data based on the
    key/value pair.
   </li>
   </ul>
 <p>
 
   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:
  <ul>
     <li> timestamp </li>
     <li> channel name and/or number </li>
     <li> host name </li>
     <li> application name </li>
     <li> (Error only) error text and severity based on the error number,
          and the supplied module name </li>
     <li> (Diagnostic only) tag name based on the tag number, and the
          supplied subtag name </li>
     <li> (Event only) event name based on the event number </li>
  </ul>
  <p>
 
   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).
  
   <p>
   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
   SpeechWorks International, Inc.
 
   <p>
   <ul>
   <li><b>Error logging:</b><br/>
 
     Module names (moduleName) must follow XML name rules as described
     above, and must be unique for each implementation of each VXI
     interface. <p>
  
     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). <p>
 
     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. <p>
  </li>
 
  <li><b>Diagnostic logging:</b><br/>
 
     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. <p>
  
     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. <p>
   </li>
  
   <li><b>Event logging:</b><br/>
 
     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. <p>
  
     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. <p> 
   </li>
 
   <li><b>Content logging:</b><br/>
 
     Module names (moduleName) must follow XML name rules as described
     above, and must be unique for each implementation of each VXI
     interface. <p>
 
     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. <p>
   </li>
   </ul> 
 */
 
 /*@{*/
 
 /**
  * @memo Standard VXIlog events
  *
  * @doc Standardized events that may be reported to the VXIlog
  * interface. Platform dependant events start at
  * VXIlog_EVENT_PLATFORM_DEFINED and increase from there.
  */
 typedef 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,
 } VXIlogEvent;
 
 /**
  * @memo Macros to determine the availability of new methods
  */
 #define LOG_EVENT_VECTOR_SUPPORTED(logIntf) \
   (logIntf->GetVersion( ) >= 0x00010001)
 #define LOG_CONTENT_METHODS_SUPPORTED(logIntf) \
   (logIntf->GetVersion( ) >= 0x00010001)
 
 /**
  * @name VXIlogResult
  * @memo Result codes for interface methods
  * 
  * @doc Result codes less then zero are severe errors (likely to be
  * platform faults), those greater then zero are warnings (likely to
  * be application issues) 
  */
 typedef enum VXIlogResult {
   /** Fatal error, terminate call    */
   VXIlog_RESULT_FATAL_ERROR       =  -100, 
   /** I/O error                      */
   VXIlog_RESULT_IO_ERROR           =   -8,
   /** Out of memory                  */
   VXIlog_RESULT_OUT_OF_MEMORY      =   -7, 
   /** System error, out of service   */
   VXIlog_RESULT_SYSTEM_ERROR       =   -6, 
   /** Errors from platform services  */
   VXIlog_RESULT_PLATFORM_ERROR     =   -5, 
   /** Return buffer too small        */
   VXIlog_RESULT_BUFFER_TOO_SMALL   =   -4, 
   /** Property name is not valid    */
   VXIlog_RESULT_INVALID_PROP_NAME  =   -3, 
   /** Property value is not valid   */
   VXIlog_RESULT_INVALID_PROP_VALUE =   -2, 
   /** Invalid function argument      */
   VXIlog_RESULT_INVALID_ARGUMENT   =   -1, 
   /** Success.  Note that Success is defined as 0 and that all
     critical errors are less than 0 and all non critical errors are
     greater than 0.            */
   VXIlog_RESULT_SUCCESS            =    0,
   /** Normal failure, nothing logged */
   VXIlog_RESULT_FAILURE            =    1,
   /** Non-fatal non-specific error   */
   VXIlog_RESULT_NON_FATAL_ERROR    =    2, 
   /** Operation is not supported     */
   VXIlog_RESULT_UNSUPPORTED        =  100
 } VXIlogResult;
 
 
 /*
 ** ==================================================
 ** VXIlogInterface Interface definition
 ** ==================================================
 */
 /** @name VXIlogInterface
  ** @memo VXIlog interface for logging
  ** @doc The VXIlogInterface provides a set of functions which are used for
  ** logging by all the OpenVXI browser components.
  **
  */
 
 typedef struct VXIlogInterface {
   /**
    * @name GetVersion
    * @memo Get the VXI interface version implemented
    *
    * @return  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.
    */ 
   VXIint32 (*GetVersion)(void);
   
   /**
    * @name GetImplementationName
    * @memo Get the name of the implementation
    *
    * @return  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.
    */
   const VXIchar* (*GetImplementationName)(void);
   
   /**
    * @name Error
    * @memo Log an error