/* * Copyright (c) 2005 Massachusetts Institute of Technology * * Permission is hereby granted, free of charge, to any person * obtaining a copy of this software and associated documentation * files (the "Software"), to deal in the Software without * restriction, including without limitation the rights to use, copy, * modify, merge, publish, distribute, sublicense, and/or sell copies * of the Software, and to permit persons to whom the Software is * furnished to do so, subject to the following conditions: * * The above copyright notice and this permission notice shall be * included in all copies or substantial portions of the Software. * * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE * SOFTWARE. */ /* $Id$ */ #ifndef __KHIMAIRA_KHERR_H #define __KHIMAIRA_KHERR_H /*! \defgroup kherr NetIDMgr Error Reporting Error reporting functions provide a mechanism to construct meaningful and user friendly error reports for the user. Unlike most of the other NetIDMgr API's, the error reporting APIs are lightweight and usually do not return an error value. This is mostly because, these functions are called \b after an error occurs. @{*/ #include<khdefs.h> #include<khlist.h> /*! \name Customizable macros @{ */ #ifndef KHERR_FACILITY /*! \brief The default facility when reporting errors When including this header file, if the KHERR_FACILITY macro is defined to be a wide character string, then it will be used as the default facility when for the convenience macros. All of the calls to the convenience macros in the source file would then have that facility. If left undefined, the convenience macros will leave the facility value undefined. */ #define KHERR_FACILITY NULL #endif #ifndef KHERR_FACILITY_ID /*! \brief The default facility ID when reporting errors When including this header file, if the KHERR_FACILITY_ID macro is defined to be non-zero, then it will be used as the default facility identifier for the convenience macros. All of the calls to the convenience macros in the source file would then have that facility identifier. The default value of 0 means that the facility is undefined. */ #define KHERR_FACILITY_ID 0 #endif /*! \define KHERR_HMODULE (undefined) \brief The default module handle When including this header file, if the KHERR_HMODULE macro is defined to be an identifier that holds the module handle, then the convenience macros that specify a module handle will use it. A default value is not defined for KHERR_HMODULE. Any attempt to invoke any of the convenience macros that use it should generate a compile time error. */ #ifdef _WIN32 #ifndef KHERR_HMODULE #endif #endif /*@}*/ /*! \brief Parameter types */ enum kherr_parm_types { KEPT_NONE = 0, KEPT_INT32 = 1, KEPT_UINT32, KEPT_INT64, KEPT_UINT64, KEPT_STRINGC, /*!< String constant */ KEPT_STRINGT, /*!< String. Will be freed using free() when the event is freed */ KEPT_PTR /*!< Pointer type. */ }; typedef struct tag_kherr_param { khm_octet type; khm_ui_8 data; } kherr_param; /*! \brief Severity levels Larger the value, the less severe it is. */ enum tag_kherr_severity { KHERR_FATAL = 0, /*!< Fatal error.*/ KHERR_ERROR, /*!< Non-fatal error. We'll probably survive. See the suggested action. */ KHERR_WARNING, /*!< Warning. Something almost broke or soon will. See the suggested action. */ KHERR_INFO, /*!< Informational. Something happened that we would like you to know about. */ KHERR_DEBUG_1 = 64, /*!< Verbose debug level 1 (high) Events at this severity level are not required to be based on localized strings. */ KHERR_DEBUG_2 = 65, /*!< Verbose debug level 2 (medium) Events at this severity level are not required to be based on localized strings. */ KHERR_DEBUG_3 = 66, /*!< Verbose debug level 3 (low) Events at this severity level are not required to be based on localized strings. */ KHERR_RESERVED_BANK = 127, /*!< Internal use */ KHERR_NONE = 128 /*!< Nothing interesting has happened so far */ }; typedef enum tag_kherr_severity kherr_severity; /*! \brief Suggestions */ enum tag_kherr_suggestion { KHERR_SUGGEST_NONE = 0, /*!< No suggestions. */ KHERR_SUGGEST_ABORT, /*!< Abort whatever it was you were trying. It's not gonna work. */ KHERR_SUGGEST_RETRY, /*!< Retry. It might work the second or third time over */ KHERR_SUGGEST_IGNORE, /*!< Ignore. It might go away. */ KHERR_SUGGEST_INTERACT, /*!< Further user interaction is necessary to resolve the situation. The suggest string in the event should be prompted to the user. */ KHERR_SUGGEST_OTHER, /*!< Something else. */ }; typedef enum tag_kherr_suggestion kherr_suggestion; /*! \brief An event */ typedef struct tag_kherr_event { khm_int32 magic; /*!< Magic number. Always set to KHERR_EVENT_MAGIC */ DWORD thread_id; /*!< The thread which reported this event. */ const wchar_t * short_desc; /*!< Short description or title (localized) */ const wchar_t * facility; /*!< Facility name of the reporter (not localized) */ const wchar_t * location; /*!< Location. Usually the function name or such of where the event occured (not localized) */ const wchar_t * long_desc; /*!< A long description of what went wrong (localized, formatted) */ const wchar_t * suggestion; /*!< A suggested way to fix it (localized,formatted) */ kherr_severity severity; /*!< Severity level. One of the severity levels listed in enumeration ::kherr_severity */ khm_int32 facility_id; /*!< Left to the application to interpret */ kherr_suggestion suggestion_id; /*!< One of the suggestion ID's from the enumeration ::kherr_suggestion */ int flags; /*!< Flags. */ kherr_param p1; /*!< Parameter 1 for formatting */ kherr_param p2; /*!< Parameter 2 for formatting */ kherr_param p3; /*!< Parameter 3 for formatting */ kherr_param p4; /*!< Parameter 4 for formatting */ DWORD time_ticks; /*!< Time at which event was reported (as returned by GetTickCount(). */ FILETIME time_ft; /*!< Time at which event was reported. Current system time as FILETIME. */ #ifdef _WIN32 HMODULE h_module; /*!< Handle to the module which should resolve any unresolved resources references above. */ #endif LDCL(struct tag_kherr_event); } kherr_event; #define KHERR_EVENT_MAGIC 0x0423e84f /*! \brief Flags for kherr_event Each set of flags that define the type of resource for one value is mutually exclusive. */ enum kherr_event_flags { KHERR_RF_CSTR_SHORT_DESC= 0x00000000, /*!< Short description is a constant string */ KHERR_RF_RES_SHORT_DESC = 0x00000001, /*!< Short description is a string resource */ KHERR_RF_MSG_SHORT_DESC = 0x00000002, /*!< Short description is a message resource */ KHERR_RF_FREE_SHORT_DESC= 0x00000004, /*!< Short description is an allocated string */ KHERR_RFMASK_SHORT_DESC = 0x00000007, KHERR_RF_CSTR_LONG_DESC = 0x00000000, /*!< Long description is a constant string */ KHERR_RF_RES_LONG_DESC = 0x00000008, /*!< Long description is a string resource */ KHERR_RF_MSG_LONG_DESC = 0x00000010, /*!< Long description is a message resouce */ KHERR_RF_FREE_LONG_DESC = 0x00000020, /*!< Long description is an allocated string */ KHERR_RFMASK_LONG_DESC = 0x00000038, KHERR_RF_CSTR_SUGGEST = 0x00000000, /*!< Suggestion is a constant string */ KHERR_RF_RES_SUGGEST = 0x00000040, /*!< Suggestion is a string resource */ KHERR_RF_MSG_SUGGEST = 0x00000080, /*!< Suggestion is a message resource */ KHERR_RF_FREE_SUGGEST = 0x00000100, /*!< Suggestion is an allocated string */ KHERR_RFMASK_SUGGEST = 0x000001C0, KHERR_RF_STR_RESOLVED = 0x00010000, /*!< The string resources in the event have been resolved. */ KHERR_RF_CONTEXT_FOLD = 0x00020000, /*!< The event is a representation of a folded context. */ KHERR_RF_INERT = 0x00040000, /*!< Inert event. The event has already been dealt with and is no longer considered significant. */ KHERR_RF_COMMIT = 0x00080000 /*!< Committed event. The commit handlers for this event have already been called. */ }; /*! \brief Serial number for error contexts */ typedef khm_ui_4 kherr_serial; /*! \brief An error context */ typedef struct tag_kherr_context { khm_int32 magic; /*!< Magic number. Always set to KHERR_CONTEXT_MAGIC */ kherr_serial serial; /*!< Context instance serial number. Context objects themselves may be reused for different contexts as they are freed and reallocated. However every instance of a context is guaranteed to have a unique serial number as specified in this field. If an external entity wants to keep track of the context, it should keep track of the serial number as well as the pointer to the context object. */ kherr_severity severity; /*!< Severity level. One of the severity levels listed below. This is the severity level of the context and is the maximum severity level of all the events in the queue of events. */ khm_int32 flags; /*!< Flags. Used internally. */ khm_ui_4 refcount; /*!< Reference count. Used internally */ kherr_event *desc_event; /*!< Description event. The event that describes the error context. This points to an event that is not in the event queue. */ kherr_event *err_event; /*!< Significant event. The last one that caused the severity level to be what it is right now. This points to an event that is listed in the event queue for this context.*/ khm_ui_4 progress_num; /*!< Progress numerator */ khm_ui_4 progress_denom; /*!< Progress denominator */ TDCL(struct tag_kherr_context); QDCL(struct tag_kherr_event); } kherr_context; #define KHERR_CONTEXT_MAGIC 0x34f3238c enum kherr_context_flags { KHERR_CF_NONE = 0x00000000, /*!< None. */ KHERR_CF_DIRTY = 0x00000001, /*!< Used Internally. Denotes that the err_event and severity may need to be recalculated. Cannot be set as an initial flag. */ KHERR_CF_OWN_PROGRESS = 0x00000002, /*!< The context maintains its own progress meter as opposed to one that is derived from child contexts. */ KHERR_CF_UNBOUND = 0x00000004, /*!< Unbound context. The context can't be used to log events. Call kherr_push_context() to associate the context with the global context hierarchy. Cannot be set as an initial flag. */ KHERR_CF_TRANSITIVE = 0x00000008, /*!< Transitive. The context is automatically made the current context for all other threads that handle messages sent or posted by threads whose current error context is this one. */ KHERR_CFMASK_INITIAL = 0x0000000a, /*!< Allowed initial flags */ }; /*! \brief Maximum length of a string field in characters including terminating NULL */ #define KHERR_MAXCCH_STRING 1024 /*! \brief Maximum length of a string field in bytes including terminating NULL */ #define KHERR_MAXCB_STRING (KHERR_MAXCCH_STRING * sizeof(wchar_t)) /*! \brief Context event \see kherr_add_ctx_handler() */ enum kherr_ctx_event { KHERR_CTX_BEGIN = 0x00000001, /*!< A new context was created */ KHERR_CTX_DESCRIBE = 0x00000002, /*!< A context was described */ KHERR_CTX_END = 0x00000004, /*!< A context was closed */ KHERR_CTX_ERROR = 0x00000008, /*!< A context switched to an error state */ KHERR_CTX_EVTCOMMIT = 0x00000010, /*!< A event was committed into the context */ KHERR_CTX_NEWCHILD = 0x00000020, /*!< A new child context was created */ KHERR_CTX_FOLDCHILD = 0x00000040, /*!< A child context was folded */ KHERR_CTX_PROGRESS = 0x00000080, /*!< Progress marker updated for context */ }; /*! \brief Context event handler Context event handlers are invoked when specific events occur with respect to an error context. The ::kherr_ctx_event parameter specifies which event occurred using one of the event values described in the enumeration. The error context in which this event occurred is specified by the ::kherr_context pointer. Note that if the handler needs to keep track of the error context for later processing, it also needs to keep track of the \a serial field of the error context. The same context object may be reused, but the serial number is guaranteed to be unique. \see kherr_add_ctx_handler() */ typedef void (KHMAPI * kherr_ctx_handler)(enum kherr_ctx_event, kherr_context *); /*! \brief Add a context event handler An application can register an event handler that gets notified of events that pertain to error contexts. More than one handler can be registered. The order in which the handlers are called is undefined for any specific event. These event occur in the context of individual application threads. The handler will be called from within the thread that caused the event. Therefore it is important that the handler is both reentrant and returns quickly. The events that the handler will be notified of are explained below: <b>KHERR_CTX_BEGIN</b>: Notification that a new context was created. A pointer to the context will be supplied to the handler. The supplied pointer should not be used to obtain a hold on the context, as it will prevent the context from being closed. <b>KHERR_CTX_DESCRIBE</b>: The thread called kherr_set_desc_event() to set the description of a context. Once again, the pointer should not be used to obtain a hold on the context. <b>KHERR_CTX_ERROR</b>: The last event that was reported for the context was an error event (the severity was was equal or higher than KHERR_ERROR). The pointer may be used to obtain a hold on the context. However, it is the application's resonsibility to make sure that the hold is released later. Otherwise the event will never be closed. <b>KHERR_CTX_END</b>: Closure. This event is signalled when the last open handle to the context is closed and there is no thread that is currently active which has this context in its error context stack. At the time the handler is invoked, the context is still intact. The pointer that is supplied should not be used to obtain a handle on the context. <b>KHERR_CTX_EVTCOMMIT</b>: An event was committed into the error context. An event is committed when another event is reported after the event, or if the context is closed. Since the last event that is reported can still be modified by adding new information, the event remains open until it is no longer the last event or the context is no longer active. When this notification is received, the last event in the context's event queue is the event that was committed. \param[in] h Context event handler, of type ::kherr_ctx_handler \param[in] filter A combination of ::kherr_ctx_event values indication which notifications should be sent to the handler. If a \a filter value of zero is provided, all of the events will be sent to the handler. \param[in] serial The serial number of the error context that should be tracked. If this is zero, all error contexts can trigger the handler. */ KHMEXP void KHMAPI kherr_add_ctx_handler(kherr_ctx_handler h, khm_int32 filter, kherr_serial serial); /*! \brief Remove a context event handler Undoes what was done with kherr_add_ctx_handler() \see kherr_add_ctx_handler() */ KHMEXP void KHMAPI kherr_remove_ctx_handler(kherr_ctx_handler h, kherr_serial serial); /*! \brief Report an error Creates an event, fills in the details specified in the arguments, and adds it to the current error context. If the current thread does not have an error context, no reporting happens. However, if any of the supplied strings or parameters are marked as allocated, they will be freed before the function returns. Certain parameters that expect strings can instead be given string resources, message resources or allocated strings in addition to constant string. By default, the parameters are expected to be constant strings. <b>Allocated strings</b>: The application can allocate memory for a string. Since the application is not notified when the event is no longer used and freed, it \b must indicate that the string is an allocated string by setting the appropriate flag in the \a flags parameter. When the event is no longer used, the memory pointed to by the relevant pointer will be freed through a call to free(). Not all string parameters take allocated strings. See individual parameter documentation for details. <b>String resources</b>: On WIN32, string resources can be passed in to kherr_report() using the MAKEINTRESOURCE macro. However, the application \b must specify that the parameter is a string resource using the appropriate flag in the \a flags parameter. The error reporting engine will expand the string against the module handle passed in the \a h_module parameter when the value of the string is required. Not all string parameters take string resources. See individual parameter documentation for details. Strings loaded through string resources cannot be longer than ::KHERR_MAXCCH_STRING in characters inclusive of terminating NULL. <b>Message resources</b>: On WIN32, message resources can be passed in to kherr_report() by specifying the message ID where it ordinarily expects a pointer to a constant string. The application \b must indicate that the string is a message resource by using the appropriate flag in the \a flags parameter. When the value of the string is needed, it is expanded against the module handle passed in the \a h_module parameter using the message ID. Not all string parameters take message resources. See individual parameter documentation for details. Note that the facility and severity values associated with a message resource are ignored. Strings loaded through message resources cannot be longer than ::KHERR_MAXCCH_STRING in characters inclusive of terminating NULL. <b>Formatted fields</b>: Parameters that are formatted can have can have parameter inserts like in printf(). However, specifying inserts is different from printf() and follows the conventions used in WIN32 API FormatMessage(). This is because for localized strings, the order of the parameters in the string may be different. See the documentation for FormatMessage() for details on the format string. The same set of parameters (i.e. \a p1, \a p2, \a p3, \a p4) is used for all formatted strings with appropriate marshalling for 64 bit types. The size of the string after expansion must not exceed 65536 bytes inclusive of terminating NULL. \param[in] severity One of ::kherr_severity_level \param[in] short_desc Short description or title (localized). Can be a string resource, message resource, allocated string or constant string. The \a flags parameter should indicate the type of string used. \param[in] facility Facility name of the reporter (not localized) \param[in] location Usually the function name or such of where the event occured (not localized) \param[in] long_desc Long description of event (localized, formatted). Can be a string resource, message resource, allocated string or constant string. The \a flags parameter should indicate the type of string used. \param[in] suggestion Suggested action to correct situation, if applicable (localized). Can be a string resource, message resource, allocated string or constant string. The \a flags parameter should indicate the type of string used. \param[in] facility_id Identifier of facility. Application defined. \param[in] suggestion_id One of the suggestion identifiers from ::kherr_suggestion_ids \param[in] p1 First parameter. Used for formatting. \param[in] p2 Second parameter. Used for formatting. \param[in] p3 Third parameter. Used for formatting. \param[in] p4 Fourth parameter. Used for formatting. \param[in] flags Flags. See ::kherr_report_flags \param[in] h_module Handle to a module that resolves any string or message resources used for the \a short_description , \a long_desc or \a suggestion parameters. This parameter is only available on WIN32. \note With the exception of parameters of type KEPT_STRINGT and parameters which are flagged for freeing using the \a flags parameter, all other string parameters are assumed to be pointers to constant strings. The strings are not copied and the pointers are used as is. Also, no clean-up is performed when the event is freed other than that implied by \a flags. */ KHMEXP kherr_event * KHMAPI kherr_report( kherr_severity severity, const wchar_t * short_desc, const wchar_t * facility, const wchar_t * location, const wchar_t * long_desC, const wchar_t * suggestion, khm_int32 facility_id, kherr_suggestion suggestion_id, kherr_param p1, kherr_param p2, kherr_param p3, kherr_param p4, khm_int32 flags #ifdef _WIN32 ,HMODULE h_module #endif ); /*! \brief Report a formatted message The format string \a long_desc_fmt should be a string constant and the format specifiers follow that of \a sprintf. This creates an event with the long description set to the expansion of the format string against the arguments. */ KHMEXP kherr_event * __cdecl kherr_reportf_ex(kherr_severity severity, const wchar_t * facility, khm_int32 facility_id, #ifdef _WIN32 HMODULE hModule, #endif const wchar_t * long_desc_fmt, ...); #define _reportf_ex kherr_reportf_ex /*! \brief Report a formatted message The format string \a long_desc_fmt should be a string constant and the format specifiers follow that of \a sprintf. This creates an event with the long description set to the expansion of the format string against the arguments. */ KHMEXP kherr_event * __cdecl kherr_reportf(const wchar_t * long_desc_fmt, ...); #define _reportf kherr_reportf /*! \brief Create a parameter out of a transient string A parameter is created by duplicating the string that is passed into the function. If the string exceeds KHERR_MAXCCH_STRING, then only the first part of the string that fits within the limit is duplicated. The resulting ::kherr_param must be passed in to kherr_report(). The event logging framework will free the duplicated string once the data is no longer required. */ KHMEXP kherr_param kherr_dup_string(const wchar_t * s); __inline KHMEXP kherr_param kherr_val(khm_octet ptype, khm_ui_8 pvalue) { kherr_param p; p.type = ptype; p.data = pvalue; return p; } #define _int32(i) kherr_val(KEPT_INT32, (khm_ui_8) i) #define _uint32(ui) kherr_val(KEPT_UINT32, (khm_ui_8) ui) #define _int64(i) kherr_val(KEPT_INT64, (khm_ui_8) i) #define _uint64(ui) kherr_val(KEPT_UINT64, (khm_ui_8) ui) #define _cstr(cs) kherr_val(KEPT_STRINGC, (khm_ui_8) cs) #define _tstr(ts) kherr_val(KEPT_STRINGT, (khm_ui_8) ts) #define _cptr(p) kherr_val(KEPT_PTR, (khm_ui_8) p) #define _vnull() kherr_val(KEPT_NONE, 0) #define _dupstr(s) kherr_dup_string(s) /* convenience macros for calling kherr_report */ #ifdef KHERR_HMODULE #define _report_cs0(severity, long_description) \ kherr_report((severity), NULL, KHERR_FACILITY, NULL, (long_description), NULL, KHERR_FACILITY_ID, 0, _vnull(), _vnull(), _vnull(), _vnull(), 0, KHERR_HMODULE) #define _report_cs1(severity, long_description, p1) \ kherr_report((severity), NULL, KHERR_FACILITY, NULL, (long_description), NULL, KHERR_FACILITY_ID, 0, p1, _vnull(), _vnull(), _vnull(), 0, KHERR_HMODULE) #define _report_cs2(severity, long_description, p1, p2) \ kherr_report((severity), NULL, KHERR_FACILITY, NULL, (long_description), NULL, KHERR_FACILITY_ID, 0, p1, p2, _vnull(), _vnull(), 0, KHERR_HMODULE) #define _report_cs3(severity, long_description, p1, p2, p3) \ kherr_report((severity), NULL, KHERR_FACILITY, NULL, (long_description), NULL, KHERR_FACILITY_ID, 0, p1, p2, p3, _vnull(), 0, KHERR_HMODULE) #define _report_cs4(severity, long_description, p1, p2, p3, p4) \ kherr_report((severity), NULL, KHERR_FACILITY, NULL, (long_description), NULL, KHERR_FACILITY_ID, 0, p1, p2, p3, p4, 0, KHERR_HMODULE) #else #define _report_cs0(severity, long_description) \ kherr_report((severity), NULL, KHERR_FACILITY, NULL, (long_description), NULL, KHERR_FACILITY_ID, 0, _vnull(), _vnull(), _vnull(), _vnull(), 0, NULL) #define _report_cs1(severity, long_description, p1) \ kherr_report((severity), NULL, KHERR_FACILITY, NULL, (long_description), NULL, KHERR_FACILITY_ID, 0, p1, _vnull(), _vnull(), _vnull(), 0, NULL) #define _report_cs2(severity, long_description, p1, p2) \ kherr_report((severity), NULL, KHERR_FACILITY, NULL, (long_description), NULL, KHERR_FACILITY_ID, 0, p1, p2, _vnull(), _vnull(), 0, NULL) #define _report_cs3(severity, long_description, p1, p2, p3) \ kherr_report((severity), NULL, KHERR_FACILITY, NULL, (long_description), NULL, KHERR_FACILITY_ID, 0, p1, p2, p3, _vnull(), 0, NULL) #define _report_cs4(severity, long_description, p1, p2, p3, p4) \ kherr_report((severity), NULL, KHERR_FACILITY, NULL, (long_description), NULL, KHERR_FACILITY_ID, 0, p1, p2, p3, p4, 0, NULL) #endif /* !defined(KHERR_HMODULE) */ #ifdef _WIN32 #define _report_sr0(severity, long_desc_id) \ kherr_report((severity), NULL, KHERR_FACILITY, NULL, MAKEINTRESOURCE(long_desc_id), NULL, KHERR_FACILITY_ID, 0, _vnull(), _vnull(), _vnull(), _vnull(), KHERR_RF_RES_LONG_DESC, KHERR_HMODULE) #define _report_sr1(severity, long_desc_id, p1) \ kherr_report((severity), NULL, KHERR_FACILITY, NULL, MAKEINTRESOURCE(long_desc_id), NULL, KHERR_FACILITY_ID, 0, p1, _vnull(), _vnull(), _vnull(), KHERR_RF_RES_LONG_DESC, KHERR_HMODULE) #define _report_sr2(severity, long_desc_id, p1, p2) \ kherr_report((severity), NULL, KHERR_FACILITY, NULL, MAKEINTRESOURCE(long_desc_id), NULL, KHERR_FACILITY_ID, 0, p1, p2, _vnull(), _vnull(), KHERR_RF_RES_LONG_DESC, KHERR_HMODULE) #define _report_sr3(severity, long_desc_id, p1, p2, p3) \ kherr_report((severity), NULL, KHERR_FACILITY, NULL, MAKEINTRESOURCE(long_desc_id), NULL, KHERR_FACILITY_ID, 0, p1, p2, p3, _vnull(), KHERR_RF_RES_LONG_DESC, KHERR_HMODULE) #define _report_sr4(severity, long_desc_id, p1, p2, p3, p4) \ kherr_report((severity), NULL, KHERR_FACILITY, NULL, MAKEINTRESOURCE(long_desc_id), NULL, KHERR_FACILITY_ID, 0, p1, p2, p3, p4, KHERR_RF_RES_LONG_DESC, KHERR_HMODULE) #endif #ifdef _WIN32 #define _report_mr0(severity, long_desc_msg_id) \ kherr_report((severity), NULL, KHERR_FACILITY, NULL, (wchar_t *)(long_desc_msg_id), NULL, KHERR_FACILITY_ID, 0, _vnull(), _vnull(), _vnull(), _vnull(), KHERR_RF_MSG_LONG_DESC, KHERR_HMODULE) #define _report_mr1(severity, long_desc_msg_id, p1) \ kherr_report((severity), NULL, KHERR_FACILITY, NULL, (wchar_t *)(long_desc_msg_id), NULL, KHERR_FACILITY_ID, 0, p1, _vnull(), _vnull(), _vnull(), KHERR_RF_MSG_LONG_DESC, KHERR_HMODULE) #define _report_mr2(severity, long_desc_msg_id, p1, p2) \ kherr_report((severity), NULL, KHERR_FACILITY, NULL, (wchar_t *)(long_desc_msg_id), NULL, KHERR_FACILITY_ID, 0, p1, p2, _vnull(), _vnull(), KHERR_RF_MSG_LONG_DESC, KHERR_HMODULE) #define _report_mr3(severity, long_desc_msg_id, p1, p2, p3) \ kherr_report((severity), NULL, KHERR_FACILITY, NULL, (wchar_t *)(long_desc_msg_id), NULL, KHERR_FACILITY_ID, 0, p1, p2, p3, _vnull(), KHERR_RF_MSG_LONG_DESC, KHERR_HMODULE) #define _report_mr4(severity, long_desc_msg_id, p1, p2, p3, p4) \ kherr_report((severity), NULL, KHERR_FACILITY, NULL, (wchar_t *)(long_desc_msg_id), NULL, KHERR_FACILITY_ID, 0, p1, p2, p3, p4, KHERR_RF_MSG_LONG_DESC, KHERR_HMODULE) #endif #define _report_ts0(severity, long_desc_ptr) \ kherr_report((severity), NULL, KHERR_FACILITY, NULL, (long_desc_ptr), NULL, KHERR_FACILITY_ID, 0, _vnull(), _vnull(), _vnull(), _vnull(), KHERR_RF_FREE_LONG_DESC, NULL) #define _report_ts1(severity, long_desc_ptr, p1) \ kherr_report((severity), NULL, KHERR_FACILITY, NULL, (long_desc_ptr), NULL, KHERR_FACILITY_ID, 0, p1, _vnull(), _vnull(), _vnull(), KHERR_RF_FREE_LONG_DESC, NULL) #define _report_ts2(severity, long_desc_ptr, p1, p2) \ kherr_report((severity), NULL, KHERR_FACILITY, NULL, (long_desc_ptr), NULL, KHERR_FACILITY_ID, 0, p1, p2, _vnull(), _vnull(), KHERR_RF_FREE_LONG_DESC, NULL) #define _report_ts3(severity, long_desc_ptr, p1, p2, p3) \ kherr_report((severity), NULL, KHERR_FACILITY, NULL, (long_desc_ptr), NULL, KHERR_FACILITY_ID, 0, p1, p2, p3, _vnull(), KHERR_RF_FREE_LONG_DESC, NULL) #define _report_ts4(severity, long_desc_ptr, p1, p2, p3, p4) \ kherr_report((severity), NULL, KHERR_FACILITY, NULL, (long_desc_ptr), NULL, KHERR_FACILITY_ID, 0, p1, p2, p3, p4, KHERR_RF_FREE_LONG_DESC, NULL) /*! \brief Set the suggestion and suggestion identifier for the last event The event that will be modified is the last event reported by the calling thread. */ KHMEXP void KHMAPI kherr_suggest(wchar_t * suggestion, khm_int32 suggestion_id, khm_int32 flags); #define _suggest_cs(cs,sid) kherr_suggest((cs), (sid), KHERR_RF_CSTR_SUGGEST) #define _suggest_ts(ts,sid) kherr_suggest((ts), (sid), KHERR_RF_FREE_SUGGEST) #define _suggest_sr(sr,sid) kherr_suggest(MAKEINTRESOURCE(sr), (sid), KHERR_RF_RES_SUGGEST) #define _suggest_mr(mr,sid) kherr_suggest((wchar_t *)(DWORD_PTR)(mr), (sid), KHERR_RF_MSG_SUGGEST) /*! \brief Set the location string for the last event The event that will be modified is the last event reported by the calling thread. */ KHMEXP void KHMAPI kherr_location(wchar_t * location); #define _location(l) kherr_location(l) /*! \brief Set the facility string and identifier for the last event The event that will be modified is the last event reported by the calling thread. */ KHMEXP void KHMAPI kherr_facility(wchar_t * facility, khm_int32 facility_id); #define _facility(f,fid) kherr_facility((f),(fid)) /*! \brief Marks the last event as the descriptor event for the current error context Note that marking an event as the descriptor event has the effect of removing the event from event queue. The event will henceforth be used as the descriptor for the context. The only effective fields of a descriptor event are \a short_desc, \a long_desc, \a facility, \a facility_id and the parameters which are used for resolving formatted strings in the aforementioned fields. Upon calling kherr_set_desc_event(), the event will be automatically evaluated as if kherr_evaluate_event() was called. The event that will be referenced is the last event reported by the calling thread. */ KHMEXP void KHMAPI kherr_set_desc_event(void); #define _describe kherr_set_desc_event /*! \brief Delete the last event The event that will be deleted is the last event reported by the calling thread. */ KHMEXP void KHMAPI kherr_del_last_event(void); #define _del_event kherr_del_last_event /*! \brief Create a new context The created context is not bound to any thread or any context hierarchy. Hence it cannot be used to capture any events until it is used in a call to kherr_push_context(). Release the returned context pointer with a call to kherr_release_context(). \param[in] flags Initial flags for the context. Combination of ::kherr_context_flags \note This function is for internal use only. */ KHMEXP kherr_context * KHMAPI kherr_create_new_context(khm_int32 flags); /*! \brief Obtain a hold on a context */ KHMEXP void KHMAPI kherr_hold_context(kherr_context * c); /*! \brief Release a context */ KHMEXP void KHMAPI kherr_release_context(kherr_context * c); /*! \brief Push an empty context Creates an empty context, adds it as a child of the current thread's error context. If the current thread does not have an error context, then the created error context will be a root level context. The new context will be the current error context for the calling thread. \param[in] flags Initial flags for the context. Combination of ::kherr_context_flags \see kherr_push_new_context() for more information about thread specific context stacks. */ KHMEXP void KHMAPI kherr_push_new_context(khm_int32 flags); #define _begin_task kherr_push_new_context /*! \brief Push a context Each thread has a stack of error contexts. The topmost one is current. The thread can push or pop contexts on to the stack independently of the hierarchy of contexts (the only exception, as explained below is when the context that is being pushed is unbound). If the context being pushed by kherr_push_context() is unbound, then it will be attached to the current context of the thread as a child. Once the new context is pushed to the top of the stack, it will become the current context for the thread. The calling thread must call kherr_pop_context() to remove the context from the top of the stack. Each call to kherr_push_new_context() or kher_push_context() must have a corresponding kherr_pop_context() call. When the thread terminates, all of the contexts in the thread's context stack will be automatically removed. \see kherr_pop_context() */ KHMEXP void KHMAPI kherr_push_context(kherr_context * c); /*! \brief Pop a context Remove the current error context from the thread's context stack. If no other open handles exist to the error context, this causes the error context to collapse into it's parent context or vanish entirely unless the context contains an error. \see kherr_push_context() for more information about thread specific context stacks. */ KHMEXP void KHMAPI kherr_pop_context(void); #define _end_task kherr_pop_context /*! \brief Retrieve the current error context The returned pointer must be released with a call to kherr_release_context(). */ KHMEXP kherr_context * KHMAPI kherr_peek_context(void); /*! \brief Check if the current error context indicates an error \return TRUE if there is an error. FALSE otherwise. \see kherr_analyze() */ KHMEXP khm_boolean KHMAPI kherr_is_error(void); /*! \brief Check if an error context indicates an error \return TRUE if there is an error. FALSE otherwise. \see kherr_analyze() */ KHMEXP khm_boolean KHMAPI kherr_is_error_i(kherr_context * c); /*! \brief Clear the error state of the current context */ KHMEXP void KHMAPI kherr_clear_error(void); /*! \brief Clear the error state of an error context */ KHMEXP void KHMAPI kherr_clear_error_i(kherr_context * c); /*! \brief Set the progress meter of the current error context Setting \a denom to zero removes the progress meter. */ KHMEXP void KHMAPI kherr_set_progress(khm_ui_4 num, khm_ui_4 denom); #define _progress(num,denom) kherr_set_progress((num),(denom)) /*! \brief Get the progress meter of the current error context This is equivalent to calling kherr_get_progress_i() for the current error context. I.e. : \code kherr_context * ctx; ctx = kherr_peek_context(); kherr_get_progress_i(ctx, &num, &denom); kherr_release_context(ctx); \endcode \see kherr_get_progress_i() */ KHMEXP void KHMAPI kherr_get_progress(khm_ui_4 * num, khm_ui_4 * denom); /*! \brief Get the progress meter of an error context The progress meter for the current context can be set by calling kherr_set_progress() (or using the ::_progress macro). The progress value returned by this function is as follows: If one or more of the following conditions are true, then the returned progress values are the values set for the context using the most recent call to kherr_set_progress(): - if the numerator and the denominator are non-zero - if the ::KHERR_CF_OWN_PROGRESS flag is set for the context. Otherwise, the function will calculate the progress by enumerating all the child context for the context and summing up the normalized numerators and the denominators for them. */ KHMEXP void KHMAPI kherr_get_progress_i(kherr_context * c, khm_ui_4 * num, khm_ui_4 * denom); /*! \brief Get the first event in a context The returned pointer is only valid as long as there is a hold on \a c. Once the context is released with a call to kherr_release_context() all pointers to events in the context become invalid. In addition, the last event in a context may still be "active". A thread can still modify the last event as long as the context is active. \see kherr_get_next_event(), kherr_get_prev_event(), kherr_get_last_event() */ KHMEXP kherr_event * KHMAPI kherr_get_first_event(kherr_context * c); /*! \brief Get the next event Call kherr_get_first_event() to obtain the first event in a context. Subsequent calls to kherr_get_next_event() will yield other events in the order in which they were reported. The list ends when kherr_get_next_event() returns NULL. The returned pointer is only valid as long as there is a hold on \a c. Once the context is released with a call to kherr_release_context() all pointers to events in the context become invalid. In addition, the last event in a context may still be "active". A thread can still modify the last event as long as the context is active. \see kherr_get_first_event(), kherr_get_prev_event(), kherr_get_last_event() */ KHMEXP kherr_event * KHMAPI kherr_get_next_event(kherr_event * e); /*! \brief Get the previous event Returns a pointer to the event that was reported in the context containing \a e prior to \a e being reported. The returned pointer is only valid as long as there is a hold on the error context. Once the context is released with a call to kherr_release_context() all pointers to events in the context become invalid. In addition, the last event in a context may still be "active". A thread can still modify the last event as long as the context is active. \see kherr_get_first_event(), kherr_get_next_event(), kherr_get_last_event() */ KHMEXP kherr_event * KHMAPI kherr_get_prev_event(kherr_event * e); /*! \brief Get the last event in an error context Returns a pointer to the last error event that that was reported to the context \a c. The returned pointer is only valid as long as there is a hold on the error context. Once the context is released with a call to kherr_release_context(), all pointers to events in the context become invalid. In addtion, the last event in a context may still be "active". A thread can still modify the last event as long as the context is active. \see kherr_get_first_event(), kherr_get_next_event(), kherr_get_prev_event() */ KHMEXP kherr_event * KHMAPI kherr_get_last_event(kherr_context * c); /*! \brief Get the first child context of a context Contexts are arranged in a hiearchy. This function returns the first child of an error context. Use kherr_get_next_context() to obtain the other contexts. If \a c is \a NULL, this returns the first root level context. The returned pointer must be released with a call to kherr_release_context() */ KHMEXP kherr_context * KHMAPI kherr_get_first_context(kherr_context * c); /*! \brief Get the next sibling context of a context The returned pointer must be released with a call to kherr_release_context() \see kherr_get_first_context() */ KHMEXP kherr_context * KHMAPI kherr_get_next_context(kherr_context * c); /*! \brief Get the desciption event for the context The description event is the event that was denoted using kherr_set_desc_event() as the event which describes the context. The returned pointer is only valid as long as there is a hold on \a c. Once the context is released with a call to kherr_release_context() all pointers to events in the context becomes invalid. */ KHMEXP kherr_event * KHMAPI kherr_get_desc_event(kherr_context * c); /*! \brief Get the error event for the context The error event for a context is the last event that had the highest severity level. The returned pointer is only valid as long as there is a hold on \a c. Once the context is released with a call to kherr_release_context() all pointers to events in the context becomes invalid. */ KHMEXP kherr_event * KHMAPI kherr_get_err_event(kherr_context * c); /*! \brief Evaluate an event When an event is reported, all the parameters and resource references that were passed to kherr_report() are kept as-is until the actual string values are required by the error reporting library. However, if the string fields are required before then, an application can call kherr_evaluate_event() to get them. This function does the following: - Load any referenced string or message resources that are referenced in the event's short description, long description or suggestion. - Expand any inserts using the parameters that were passed in. - Free up allocated strings in for the descriptions or suggestion fields and any parameters. - Update the string fields in the event to contain the newly generated strings. */ KHMEXP void KHMAPI kherr_evaluate_event(kherr_event * e); /*! \brief Evaluate the last event Same as kherr_evaluate_event(), but operates on the last event logged by the current thread. \see kherr_evaluate_event() */ KHMEXP void KHMAPI kherr_evaluate_last_event(void); #define _resolve kherr_evaluate_last_event /*! \defgroup kherr_fids Standard Facility IDs @{*/ #define KHM_FACILITY_KMM 1 #define KHM_FACILITY_KCDB 2 #define KHM_FACILITY_UI 3 #define KHM_FACILITY_KRB5 64 #define KHM_FACILITY_KRB4 65 #define KHM_FACILITY_AFS 66 #define KHM_FACILITY_USER 128 /*@}*/ /*@}*/ /* In debug mode, outputs the formatted string to the debug console */ #ifdef DEBUG KHMEXP void kherr_debug_printf(wchar_t * fmt, ...); #endif #endif