vxilog.h

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

    * @doc Basic error reporting mechanism.  Errors are reported by
    * moduleName, error number, a format, and a varargs argument list. <p>
    *
    * 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:<p>
    *
    *    L"%s%i%s%s", L"key1", 911, L"key2", L"value2" <p>
    *
    *    While this one is incorrect (second key missing):<br>
    *
    *    L"%s%i%f", L"key1", 911, (float)22 / 7<p>
    *
    *    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).<p>
    *
    *    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.
    *
    * @param  moduleName   [IN] Name of the software module that is 
    *                      outputting the error. See the top of this file
    *                      for moduleName allocation rules.
    * @param  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.
    * @param  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( ).
    *
    * @param  ...          [IN] Arguments matching the error details format
    *                      specified above.
    *
    * @return VXIlog_RESULT_SUCCESS on success 
    */
   VXIlogResult (*Error)(struct VXIlogInterface* pThis,
 			const VXIchar*          moduleName,
 			VXIunsigned             errorID,
 			const VXIchar*          format,
 			...);
   
   /**
    * @name VError
    * @memo Log an error (va_list variant)
    *
    * @doc
    * Same as <a href="Error.html"> Error</a>, 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.
    *  
    * @return VXIlog_RESULT_SUCCESS on success
    */
   VXIlogResult (*VError)(struct VXIlogInterface* pThis,
 			 const VXIchar*          moduleName,
 			 VXIunsigned             errorID,
 			 const VXIchar*          format,
 			 va_list                 vargs);
   
   /**
    * @name Diagnostic
    * @memo Log a diagnostic message
    * @doc Basic diagnostic reporting mechanism.  Diagnostic messages are
    * reported by moduleName, tag id, subtag, a format, and a variable length
    * argument list.
    *
    * @param  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.
    * @param  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.
    * @param  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( ).<p>
    *
    *                  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.
    * @param  ...      [IN] Arguments matching the free-form diagnostic text
    *                  format specified above.
    *
    * @return VXIlog_RESULT_SUCCESS on success
    */
   VXIlogResult (*Diagnostic)(struct VXIlogInterface* pThis,
 			     VXIunsigned             tagID,
 			     const VXIchar*          subtag,
 			     const VXIchar*          format,
 			     ...);
 
   /**
    * @name VDiagnostic
    * @memo Log a diagnostic message (va_list variant)
    *
    * @doc
    * Same as <a href="Diagnostic.html"> Diagnostic</a>, 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.
    *   
    * @return VXIlog_RESULT_SUCCESS on success
    */
   VXIlogResult (*VDiagnostic)(struct VXIlogInterface* pThis,
 			      VXIunsigned             tagID,
 			      const VXIchar*          subtag,
 			      const VXIchar*          format,
 			      va_list                 vargs);
 
   /**
    * @name DiagnosticIsEnabled
    * @memo Query whether diagnostic logging is enabled
    *
    * @doc
    * NOTE: Diagnostic log messages are automatically filtered in a
    *  high-performance way by the <a href="Diagnostic.html">
    *  Diagnostic </a>  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.
    *
    * @param  tagID        [IN] Identifier for a class of 
    *
    * @return 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)
    */
   VXIbool (*DiagnosticIsEnabled)(struct VXIlogInterface* pThis,
 				 VXIunsigned             tagID);
 
   /**
    * @name Event
    * @memo Log an event
    * @doc 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 </a> for a full explanation.
    *
    * @param  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.
    * @param  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(). <p>
    *
    *                      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 
    *                      <a href="Error.html"> Error </a> for a full 
    *                      explanation.
    * @param  ...          [IN] Arguments matching the event details format
    *                      specified above.
    *
    * @return VXIlog_RESULT_SUCCESS on success
    */
   VXIlogResult (*Event)(struct VXIlogInterface* pThis,
 			VXIunsigned             eventID,
 			const VXIchar*          format,
 			...);
 
   /**
    * @name VEvent
    * @memo Log an event (va_list variant)
    *
    * @doc
    * Same as <a href="Event.html"> Event </a>, 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.
    *    
    * @return VXIlog_RESULT_SUCCESS on success
    */
   VXIlogResult (*VEvent)(struct VXIlogInterface* pThis,
 			 VXIunsigned             eventID,
 			 const VXIchar*          format,
 			 va_list                 vargs);
 
   /**
    * @name EventVector
    * @memo 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.
    *
    * @doc
    * Same as <a href="Event.html"> Event </a>, 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)
    *
    * @param  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.
    * @param  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.
    * @param  values       [IN] Values for the event data. Each value must
    *                      be a VXIInteger, VXIFloat, VXIString, or VXIPtr.
    *
    * @return VXIlog_RESULT_SUCCESS on success
    */
   VXIlogResult (*EventVector)(struct VXIlogInterface* pThis,
 			      VXIunsigned             eventID,
 			      const VXIVector*        keys,
 			      const VXIVector*        values);
 
   /**
    * @name ContentOpen
    * @memo 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.
    *
    * @doc 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.
    *
    * @param  moduleName   [IN] Name of the software module that is 
    *                      outputting the data. See the top of this file
    *                      for moduleName allocation rules.
    * @param  contentType  [IN] MIME content type for the data
    * @param  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.
    * @param  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.
    * @param  stream       [OUT] Handle for writing the content via 
    *                      ContentWrite( ) and closing it via ContentClose( )
    *
    * @return VXIlog_RESULT_SUCCESS on success
    */
   VXIlogResult (*ContentOpen)(struct VXIlogInterface* pThis,
 			      const VXIchar*          moduleName,
 			      const VXIchar*          contentType,
 			      VXIString**             logKey,
 			      VXIString**             logValue,
 			      VXIlogStream**          stream);
 
   /**
    * @name ContentClose
    * @memo 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.
    *
    * @doc Close a content stream that was previously opened. Closing
    *      a NULL or previously closed stream will result in an error.
    *
    * @param  stream   [IN/OUT] Handle to the stream to close, will be
    *                  set to NULL on success
    *
    * @return VXIlog_RESULT_SUCCESS on success
    */
   VXIlogResult (*ContentClose)(struct VXIlogInterface* pThis,
 			       VXIlogStream**          stream);
 
   /**
    * @name ContentWrite
    * @memo 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.
    *
    * @doc Write data to a content stream that was previously opened.
    *
    * @param buffer   [OUT] Buffer of data to write to the stream
    * @param buflen   [IN]  Number of bytes to write
    * @param nwritten [OUT] Number of bytes actual written, may be less then
    *                 buflen if an error is returned
    * @param stream   [IN] Handle to the stream to write to
    *
    * @return VXIlog_RESULT_SUCCESS on success
    */
   VXIlogResult (*ContentWrite)(struct VXIlogInterface* pThis,
 			       const VXIbyte*          buffer,
 			       VXIulong                buflen,
 			       VXIulong*               nwritten,
 			       VXIlogStream*           stream);
   
 } VXIlogInterface;
 
 
 /*@}*/
 
 #ifdef __cplusplus
 }
 #endif
 
 #include "VXIheaderSuffix.h"
 
 #endif  /* include guard */