NetIDMgr Error Reporting

Detailed Description

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 after an error occurs.


Modules

 Standard Facility IDs

Data Structures

struct  tag_kherr_param
struct  tag_kherr_event
 An event. More...
struct  tag_kherr_context
 An error context. More...

Customizable macros

#define KHERR_FACILITY   NULL
 The default facility when reporting errors.
#define KHERR_FACILITY_ID   0
 The default facility ID when reporting errors.

Defines

#define KHERR_EVENT_MAGIC   0x0423e84f
#define KHERR_CONTEXT_MAGIC   0x34f3238c
#define KHERR_MAXCCH_STRING   1024
 Maximum length of a string field in characters including terminating NULL.
#define KHERR_MAXCB_STRING   (KHERR_MAXCCH_STRING * sizeof(wchar_t))
 Maximum length of a string field in bytes including terminating NULL.
#define _reportf_ex   kherr_reportf_ex
#define _reportf   kherr_reportf
#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)
#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)
#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)
#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)
#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)
#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)
#define _location(l)   kherr_location(l)
#define _facility(f, fid)   kherr_facility((f),(fid))
#define _describe   kherr_set_desc_event
#define _del_event   kherr_del_last_event
#define _begin_task   kherr_push_new_context
#define _end_task   kherr_pop_context
#define _progress(num, denom)   kherr_set_progress((num),(denom))
#define _resolve   kherr_evaluate_last_event

Typedefs

typedef tag_kherr_param kherr_param
typedef enum tag_kherr_severity kherr_severity
typedef enum tag_kherr_suggestion kherr_suggestion
typedef tag_kherr_event kherr_event
 An event.
typedef khm_ui_4 kherr_serial
 Serial number for error contexts.
typedef tag_kherr_context kherr_context
 An error context.
typedef void(KHMAPI *) kherr_ctx_handler (enum kherr_ctx_event, kherr_context *)
 Context event handler.

Enumerations

enum  kherr_parm_types {
  KEPT_NONE = 0, KEPT_INT32 = 1, KEPT_UINT32, KEPT_INT64,
  KEPT_UINT64, KEPT_STRINGC, KEPT_STRINGT, KEPT_PTR
}
 The default module handleParameter types. More...
enum  tag_kherr_severity {
  KHERR_FATAL = 0, KHERR_ERROR, KHERR_WARNING, KHERR_INFO,
  KHERR_DEBUG_1 = 64, KHERR_DEBUG_2 = 65, KHERR_DEBUG_3 = 66, KHERR_RESERVED_BANK = 127,
  KHERR_NONE = 128
}
 Severity levels. More...
enum  tag_kherr_suggestion {
  KHERR_SUGGEST_NONE = 0, KHERR_SUGGEST_ABORT, KHERR_SUGGEST_RETRY, KHERR_SUGGEST_IGNORE,
  KHERR_SUGGEST_INTERACT, KHERR_SUGGEST_OTHER
}
 Suggestions. More...
enum  kherr_event_flags {
  KHERR_RF_CSTR_SHORT_DESC = 0x00000000, KHERR_RF_RES_SHORT_DESC = 0x00000001, KHERR_RF_MSG_SHORT_DESC = 0x00000002, KHERR_RF_FREE_SHORT_DESC = 0x00000004,
  KHERR_RFMASK_SHORT_DESC = 0x00000007, KHERR_RF_CSTR_LONG_DESC = 0x00000000, KHERR_RF_RES_LONG_DESC = 0x00000008, KHERR_RF_MSG_LONG_DESC = 0x00000010,
  KHERR_RF_FREE_LONG_DESC = 0x00000020, KHERR_RFMASK_LONG_DESC = 0x00000038, KHERR_RF_CSTR_SUGGEST = 0x00000000, KHERR_RF_RES_SUGGEST = 0x00000040,
  KHERR_RF_MSG_SUGGEST = 0x00000080, KHERR_RF_FREE_SUGGEST = 0x00000100, KHERR_RFMASK_SUGGEST = 0x000001C0, KHERR_RF_STR_RESOLVED = 0x00010000,
  KHERR_RF_CONTEXT_FOLD = 0x00020000, KHERR_RF_INERT = 0x00040000, KHERR_RF_COMMIT = 0x00080000
}
 Flags for kherr_event. More...
enum  kherr_context_flags {
  KHERR_CF_NONE = 0x00000000, KHERR_CF_DIRTY = 0x00000001, KHERR_CF_OWN_PROGRESS = 0x00000002, KHERR_CF_UNBOUND = 0x00000004,
  KHERR_CF_TRANSITIVE = 0x00000008, KHERR_CFMASK_INITIAL = 0x0000000a
}
enum  kherr_ctx_event {
  KHERR_CTX_BEGIN = 0x00000001, KHERR_CTX_DESCRIBE = 0x00000002, KHERR_CTX_END = 0x00000004, KHERR_CTX_ERROR = 0x00000008,
  KHERR_CTX_EVTCOMMIT = 0x00000010, KHERR_CTX_NEWCHILD = 0x00000020, KHERR_CTX_FOLDCHILD = 0x00000040, KHERR_CTX_PROGRESS = 0x00000080
}
 Context event. More...

Functions

KHMEXP void KHMAPI kherr_add_ctx_handler (kherr_ctx_handler h, khm_int32 filter, kherr_serial serial)
 Add a context event handler.
KHMEXP void KHMAPI kherr_remove_ctx_handler (kherr_ctx_handler h, kherr_serial serial)
 Remove a context event handler.
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, HMODULE h_module)
 Report an error.
KHMEXP kherr_event *__cdecl kherr_reportf_ex (kherr_severity severity, const wchar_t *facility, khm_int32 facility_id, HMODULE hModule, const wchar_t *long_desc_fmt,...)
 Report a formatted message.
KHMEXP kherr_event *__cdecl kherr_reportf (const wchar_t *long_desc_fmt,...)
 Report a formatted message.
KHMEXP kherr_param kherr_dup_string (const wchar_t *s)
 Create a parameter out of a transient string.
__inline KHMEXP kherr_param kherr_val (khm_octet ptype, khm_ui_8 pvalue)
KHMEXP void KHMAPI kherr_suggest (wchar_t *suggestion, khm_int32 suggestion_id, khm_int32 flags)
 Set the suggestion and suggestion identifier for the last event.
KHMEXP void KHMAPI kherr_location (wchar_t *location)
 Set the location string for the last event.
KHMEXP void KHMAPI kherr_facility (wchar_t *facility, khm_int32 facility_id)
 Set the facility string and identifier for the last event.
KHMEXP void KHMAPI kherr_set_desc_event (void)
 Marks the last event as the descriptor event for the current error context.
KHMEXP void KHMAPI kherr_del_last_event (void)
 Delete the last event.
KHMEXP kherr_context *KHMAPI kherr_create_new_context (khm_int32 flags)
 Create a new context.
KHMEXP void KHMAPI kherr_hold_context (kherr_context *c)
 Obtain a hold on a context.
KHMEXP void KHMAPI kherr_release_context (kherr_context *c)
 Release a context.
KHMEXP void KHMAPI kherr_push_new_context (khm_int32 flags)
 Push an empty context.
KHMEXP void KHMAPI kherr_push_context (kherr_context *c)
 Push a context.
KHMEXP void KHMAPI kherr_pop_context (void)
 Pop a context.
KHMEXP kherr_context *KHMAPI kherr_peek_context (void)
 Retrieve the current error context.
KHMEXP khm_boolean KHMAPI kherr_is_error (void)
 Check if the current error context indicates an error.
KHMEXP khm_boolean KHMAPI kherr_is_error_i (kherr_context *c)
 Check if an error context indicates an error.
KHMEXP void KHMAPI kherr_clear_error (void)
 Clear the error state of the current context.
KHMEXP void KHMAPI kherr_clear_error_i (kherr_context *c)
 Clear the error state of an error context.
KHMEXP void KHMAPI kherr_set_progress (khm_ui_4 num, khm_ui_4 denom)
 Set the progress meter of the current error context.
KHMEXP void KHMAPI kherr_get_progress (khm_ui_4 *num, khm_ui_4 *denom)
 Get the progress meter of the current error context.
KHMEXP void KHMAPI kherr_get_progress_i (kherr_context *c, khm_ui_4 *num, khm_ui_4 *denom)
 Get the progress meter of an error context.
KHMEXP kherr_event *KHMAPI kherr_get_first_event (kherr_context *c)
 Get the first event in a context.
KHMEXP kherr_event *KHMAPI kherr_get_next_event (kherr_event *e)
 Get the next event.
KHMEXP kherr_event *KHMAPI kherr_get_prev_event (kherr_event *e)
 Get the previous event.
KHMEXP kherr_event *KHMAPI kherr_get_last_event (kherr_context *c)
 Get the last event in an error context.
KHMEXP kherr_context *KHMAPI kherr_get_first_context (kherr_context *c)
 Get the first child context of a context.
KHMEXP kherr_context *KHMAPI kherr_get_next_context (kherr_context *c)
 Get the next sibling context of a context.
KHMEXP kherr_event *KHMAPI kherr_get_desc_event (kherr_context *c)
 Get the desciption event for the context.
KHMEXP kherr_event *KHMAPI kherr_get_err_event (kherr_context *c)
 Get the error event for the context.
KHMEXP void KHMAPI kherr_evaluate_event (kherr_event *e)
 Evaluate an event.
KHMEXP void KHMAPI kherr_evaluate_last_event (void)
 Evaluate the last event.

Define Documentation

#define KHERR_FACILITY   NULL

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_ID   0

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.

Typedef Documentation

typedef void(KHMAPI *) kherr_ctx_handler(enum kherr_ctx_event, kherr_context *)

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 serial field of the error context. The same context object may be reused, but the serial number is guaranteed to be unique.

See also:
kherr_add_ctx_handler()

Enumeration Type Documentation

enum kherr_context_flags

Enumerator:
KHERR_CF_NONE  None.
KHERR_CF_DIRTY  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  The context maintains its own progress meter as opposed to one that is derived from child contexts.
KHERR_CF_UNBOUND  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  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  Allowed initial flags

enum kherr_ctx_event

Context event.

See also:
kherr_add_ctx_handler()
Enumerator:
KHERR_CTX_BEGIN  A new context was created
KHERR_CTX_DESCRIBE  A context was described
KHERR_CTX_END  A context was closed
KHERR_CTX_ERROR  A context switched to an error state
KHERR_CTX_EVTCOMMIT  A event was committed into the context
KHERR_CTX_NEWCHILD  A new child context was created
KHERR_CTX_FOLDCHILD  A child context was folded
KHERR_CTX_PROGRESS  Progress marker updated for context

enum kherr_event_flags

Flags for kherr_event.

Each set of flags that define the type of resource for one value is mutually exclusive.

Enumerator:
KHERR_RF_CSTR_SHORT_DESC  Short description is a constant string
KHERR_RF_RES_SHORT_DESC  Short description is a string resource
KHERR_RF_MSG_SHORT_DESC  Short description is a message resource
KHERR_RF_FREE_SHORT_DESC  Short description is an allocated string
KHERR_RF_CSTR_LONG_DESC  Long description is a constant string
KHERR_RF_RES_LONG_DESC  Long description is a string resource
KHERR_RF_MSG_LONG_DESC  Long description is a message resouce
KHERR_RF_FREE_LONG_DESC  Long description is an allocated string
KHERR_RF_CSTR_SUGGEST  Suggestion is a constant string
KHERR_RF_RES_SUGGEST  Suggestion is a string resource
KHERR_RF_MSG_SUGGEST  Suggestion is a message resource
KHERR_RF_FREE_SUGGEST  Suggestion is an allocated string
KHERR_RF_STR_RESOLVED  The string resources in the event have been resolved.
KHERR_RF_CONTEXT_FOLD  The event is a representation of a folded context.
KHERR_RF_INERT  Inert event. The event has already been dealt with and is no longer considered significant.
KHERR_RF_COMMIT  Committed event. The commit handlers for this event have already been called.

enum kherr_parm_types

The default module handleParameter types.

Enumerator:
KEPT_STRINGC  String constant
KEPT_STRINGT  String. Will be freed using free() when the event is freed
KEPT_PTR  Pointer type.

enum tag_kherr_severity

Severity levels.

Larger the value, the less severe it is.

Enumerator:
KHERR_FATAL  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  Verbose debug level 1 (high) Events at this severity level are not required to be based on localized strings.
KHERR_DEBUG_2  Verbose debug level 2 (medium) Events at this severity level are not required to be based on localized strings.
KHERR_DEBUG_3  Verbose debug level 3 (low) Events at this severity level are not required to be based on localized strings.
KHERR_RESERVED_BANK  Internal use
KHERR_NONE  Nothing interesting has happened so far

enum tag_kherr_suggestion

Suggestions.

Enumerator:
KHERR_SUGGEST_NONE  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.

Function Documentation

KHMEXP void KHMAPI kherr_add_ctx_handler ( kherr_ctx_handler  h,
khm_int32  filter,
kherr_serial  serial 
)

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:

KHERR_CTX_BEGIN: 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.

KHERR_CTX_DESCRIBE: 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.

KHERR_CTX_ERROR: 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.

KHERR_CTX_END: 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.

KHERR_CTX_EVTCOMMIT: 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.

Parameters:
[in] h Context event handler, of type kherr_ctx_handler
[in] filter A combination of kherr_ctx_event values indication which notifications should be sent to the handler. If a filter value of zero is provided, all of the events will be sent to the handler.
[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 kherr_context* KHMAPI kherr_create_new_context ( khm_int32  flags  ) 

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().

Parameters:
[in] flags Initial flags for the context. Combination of kherr_context_flags
Note:
This function is for internal use only.

KHMEXP void KHMAPI kherr_del_last_event ( void   ) 

Delete the last event.

The event that will be deleted is the last event reported by the calling thread.

KHMEXP kherr_param kherr_dup_string ( const wchar_t *  s  ) 

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 resulign 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 void KHMAPI kherr_evaluate_event ( kherr_event *  e  ) 

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:

KHMEXP void KHMAPI kherr_evaluate_last_event ( void   ) 

Evaluate the last event.

Same as kherr_evaluate_event(), but operates on the last event logged by the current thread.

See also:
kherr_evaluate_event()

KHMEXP void KHMAPI kherr_facility ( wchar_t *  facility,
khm_int32  facility_id 
)

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 kherr_event* KHMAPI kherr_get_desc_event ( kherr_context *  c  ) 

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 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  ) 

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 c. Once the context is released with a call to kherr_release_context() all pointers to events in the context becomes invalid.

KHMEXP kherr_context* KHMAPI kherr_get_first_context ( kherr_context *  c  ) 

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 c is NULL, this returns the first root level context.

The returned pointer must be released with a call to kherr_release_context()

KHMEXP kherr_event* KHMAPI kherr_get_first_event ( kherr_context *  c  ) 

Get the first event in a context.

The returned pointer is only valid as long as there is a hold on 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 also:
kherr_get_next_event(), kherr_get_prev_event(), kherr_get_last_event()

KHMEXP kherr_event* KHMAPI kherr_get_last_event ( kherr_context *  c  ) 

Get the last event in an error context.

Returns a pointer to the last error event that that was reported to the context 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 also:
kherr_get_first_event(), kherr_get_next_event(), kherr_get_prev_event()

KHMEXP kherr_context* KHMAPI kherr_get_next_context ( kherr_context *  c  ) 

Get the next sibling context of a context.

The returned pointer must be released with a call to kherr_release_context()

See also:
kherr_get_first_context()

KHMEXP kherr_event* KHMAPI kherr_get_next_event ( kherr_event *  e  ) 

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 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 also:
kherr_get_first_event(), kherr_get_prev_event(), kherr_get_last_event()

KHMEXP kherr_event* KHMAPI kherr_get_prev_event ( kherr_event *  e  ) 

Get the previous event.

Returns a pointer to the event that was reported in the context containing e prior to 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 also:
kherr_get_first_event(), kherr_get_next_event(), kherr_get_last_event()

KHMEXP void KHMAPI kherr_get_progress ( khm_ui_4 *  num,
khm_ui_4 *  denom 
)

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. :

    kherr_context * ctx;

    ctx = kherr_peek_context();
    kherr_get_progress_i(ctx, &num, &denom);
    kherr_release_context(ctx);

See also:
kherr_get_progress_i()

KHMEXP void KHMAPI kherr_get_progress_i ( kherr_context *  c,
khm_ui_4 *  num,
khm_ui_4 *  denom 
)

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():

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 khm_boolean KHMAPI kherr_is_error ( void   ) 

Check if the current error context indicates an error.

Returns:
TRUE if there is an error. FALSE otherwise.
See also:
kherr_analyze()

KHMEXP khm_boolean KHMAPI kherr_is_error_i ( kherr_context *  c  ) 

Check if an error context indicates an error.

Returns:
TRUE if there is an error. FALSE otherwise.
See also:
kherr_analyze()

KHMEXP void KHMAPI kherr_location ( wchar_t *  location  ) 

Set the location string for the last event.

The event that will be modified is the last event reported by the calling thread.

KHMEXP kherr_context* KHMAPI kherr_peek_context ( void   ) 

Retrieve the current error context.

The returned pointer must be released with a call to kherr_release_context().

KHMEXP void KHMAPI kherr_pop_context ( void   ) 

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 also:
kherr_push_context() for more information about thread specific context stacks.

KHMEXP void KHMAPI kherr_push_context ( kherr_context *  c  ) 

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 also:
kherr_pop_context()

KHMEXP void KHMAPI kherr_push_new_context ( khm_int32  flags  ) 

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.

Parameters:
[in] flags Initial flags for the context. Combination of kherr_context_flags
See also:
kherr_push_new_context() for more information about thread specific context stacks.

KHMEXP void KHMAPI kherr_remove_ctx_handler ( kherr_ctx_handler  h,
kherr_serial  serial 
)

Remove a context event handler.

Undoes what was done with kherr_add_ctx_handler()

See also:
kherr_add_ctx_handler()

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,
HMODULE  h_module 
)

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.

Allocated strings: The application can allocate memory for a string. Since the application is not notified when the event is no longer used and freed, it must indicate that the string is an allocated string by setting the appropriate flag in the 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.

String resources: On WIN32, string resources can be passed in to kherr_report() using the MAKEINTRESOURCE macro. However, the application must specify that the parameter is a string resource using the appropriate flag in the flags parameter. The error reporting engine will expand the string against the module handle passed in the 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.

Message resources: 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 must indicate that the string is a message resource by using the appropriate flag in the flags parameter. When the value of the string is needed, it is expanded against the module handle passed in the 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.

Formatted fields: 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. p1, p2, p3, 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.

Parameters:
[in] severity One of kherr_severity_level
[in] short_desc Short description or title (localized). Can be a string resource, message resource, allocated string or constant string. The flags parameter should indicate the type of string used.
[in] facility Facility name of the reporter (not localized)
[in] location Usually the function name or such of where the event occured (not localized)
[in] long_desc Long description of event (localized, formatted). Can be a string resource, message resource, allocated string or constant string. The flags parameter should indicate the type of string used.
[in] suggestion Suggested action to correct situation, if applicable (localized). Can be a string resource, message resource, allocated string or constant string. The flags parameter should indicate the type of string used.
[in] facility_id Identifier of facility. Application defined.
[in] suggestion_id One of the suggestion identifiers from kherr_suggestion_ids
[in] p1 First parameter. Used for formatting.
[in] p2 Second parameter. Used for formatting.
[in] p3 Third parameter. Used for formatting.
[in] p4 Fourth parameter. Used for formatting.
[in] flags Flags. See kherr_report_flags
[in] h_module Handle to a module that resolves any string or message resources used for the short_description , long_desc or 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 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 flags.

KHMEXP kherr_event* __cdecl kherr_reportf ( const wchar_t *  long_desc_fmt,
  ... 
)

Report a formatted message.

The format string long_desc_fmt should be a string constant and the format specifiers follow that of 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,
HMODULE  hModule,
const wchar_t *  long_desc_fmt,
  ... 
)

Report a formatted message.

The format string long_desc_fmt should be a string constant and the format specifiers follow that of sprintf. This creates an event with the long description set to the expansion of the format string against the arguments.

KHMEXP void KHMAPI kherr_set_desc_event ( void   ) 

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 short_desc, long_desc, facility, 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_progress ( khm_ui_4  num,
khm_ui_4  denom 
)

Set the progress meter of the current error context.

Setting denom to zero removes the progress meter.

KHMEXP void KHMAPI kherr_suggest ( wchar_t *  suggestion,
khm_int32  suggestion_id,
khm_int32  flags 
)

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.

Generated on Fri Aug 3 08:27:15 2007 for Network Identity Manager by Doxygen 1.5.2
© 2004-2007 Massachusetts Institute of Technology.
© 2005-2007 Secure Endpoints Inc.
Contact khimaira@mit.edu