w32event.h File Reference

---

Detailed Description

declarations for utility functions.

Data Structures
struct	log_event_data
	Structure for log resources. More...
Defines
#define	MAX_INSERTIONS   32
	Maximum number of insertion strings.
Typedefs
typedef log_event_data	log_event_data
	Structure for log resources.
Functions
HANDLE	SetEventSource (LPTSTR pszSrcName, LPTSTR pszMsgDLL, DWORD dwNum)
	Register an event source.
PSID	GetEventSid (void)
	Obtain a SID for logging.
void	ClearEventSid (PSID)
	Deallocate the SID that was created by GetEventSid().
int	log_init (log_event_data *log, int category, LPTSTR pszSrcName, LPTSTR pszMsgDLL)
	Initialize a log_event_data structure.
void	log_clear (log_event_data *log)
	Free resources and zero the memory.
void	log_event (log_event_data const *log, DWORD msg,...)
	Log an event.
void	log_event_blob (log_event_data const *log, DWORD msg, DWORD blob_length, void *blob,...)
	Log an event and save additional binary data.
void	v_log_event (log_event_data const *log, DWORD msg, DWORD b_len, void *blob, va_list args)
	Log the event using a va_list.

---

Define Documentation

#define MAX_INSERTIONS   32

Maximum number of insertion strings. This is the maximum size of an array of string passed to ReportEvent. See also: v_log_event()

---

Typedef Documentation

typedef struct log_event_data log_event_data

Structure for log resources. That data has to be allocated by the user before initialization. The members are exposed so that they can be used independently of the functions defined in this module, e.g. to call ReportEvent directly. Note that log_event(), log_event_blob(), and v_log_event() consider this structure as read-only data. Therefore you may safely make a copy of the structure and use that instead of the original. See also: log_init()

---

Function Documentation

void ClearEventSid (  PSID  sid  )

Deallocate the SID that was created by GetEventSid(). Parameters: sid  the SID that was created by GetEventSid() See also: GetEventSid()

PSID GetEventSid (  void   )

Obtain a SID for logging. This functions tries to obtain a user SID, an owner SID or the groups logon SID, in that order. If it fails returns NULL. This function is called as part of the initialization, so it should be called only if doing custom initialization. Returns: a PSID for logging. See also: log_init() Other examples in MSDN

void log_clear (  log_event_data *  log  )

Free resources and zero the memory. This function may be needed if you are concerned with handle inheritance or before exiting the program if you use a tool to detect memory leakages. Parameters: log  the log_event_data structure to be cleared See also: log_init()

void log_event (  log_event_data const *  log, DWORD  id,   ... )

Log an event. This is coded as va_list ap; va_start(ap, id); v_log_event(log, id, 0, NULL, ap); va_end(ap); Parameters: log  a poiter to an initialized log_event_data id  the message id ...  insertion arguments See also: v_log_event() log_event_blob()

void log_event_blob (  log_event_data const *  log, DWORD  id, DWORD  blob_length, void *  blob,   ... )

Log an event and save additional binary data. Parameters: log  a poiter to an initialized log_event_data id  the message id blob_length  length of the blob blob  chunk of binary data ...  insertion arguments See also: v_log_event() log_event()

int log_init (  log_event_data *  log, int  category, LPTSTR  pszSrcName, LPTSTR  pszMsgDLL )

Initialize a log_event_data structure. After the structure is initialized, it will not be altered until you clear it, so there is no need to protect it from simultaneous acces by different threads. The caller can allocate the structure in static storage or wherever it can be easily accessed. Initialization fails with error 120 if not on WIN32, e.g. on win98. However, if NDEBUG is not defined, event will still be seen on stderr. In that case log_init returns 120. Pass a positive category for logging all messages with it. If the category is 0 or negative, the message facility will be used. Initializing an already initialized structure results in resource leaking. Parameters: log  the log_event_data structure to initialize category  the category that will be used for logging pszSrcName  event source name pszMsgDLL  name or path for message DLL Returns: 0 if successful See also: SetEventSource() GetEventSid() log_clear()

HANDLE SetEventSource (  LPTSTR  pszSrcName, LPTSTR  pszMsgDLL, DWORD  dwNum )

Register an event source. Create or update the key HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\Application\pszSrcName . This function is called as part of the initialization, so it should be called only when doing custom initialization. Parameters: pszSrcName  event source name pszMsgDLL  name or path for message file (.dll extension is used by default. The path is searched if the name contains no slashes.) dwNum  number of categories defined in the message file. Returns: a handle that can be used to call ReportEvent or NULL in case of failure. See also: log_init() Other examples in MSDN

void v_log_event (  log_event_data const *  log, DWORD  id, DWORD  b_len, void *  blob, va_list  args )

Log the event using a va_list. This is the workhorse function. It arranges the parameters for ReportEvent. The category is read from log_event_data. If it is less than 1, then the facility number will be used, thus implementing the category == facility schema. If the category is higher than the last_category, then the latter will be used. It retrieves the formal argument definition and rewrites it so as to exclude spurious characters (typically newlines). It recognizes a sequence %...T where the terminating character T is one of diouxXfeEgGcCsSp, and ... is one or more formatting flags. (Note that %n is not supported.) The special sequence %M is recognized. The corresponding integer argument is replaced with the system message string that can be retrieved via FormatMessage using the default language. The actual error number is appended to the message. For simple formats, %s and %M, the function directly substitutes the corresponding parameter. Otherwise, it rewrites the format string inserting an ARGUMENT_SEPARATOR after the terminating character. Then it calls vfprintf on a temporary file, passing all the remaining parameters. Finally, it reads back the temporary file and builds the array of insertions as required. Up to MAX_INSERTIONS parameters are accepted. That way, callers can seamlessly pass any parameter that printf would accept, including 64 bits data. All parameterts are converted to strings according to the format specified in the message file. Note that NT can make a savvy use of temporary files (most probably it will never reach the hard disk) therefore you only pay a negligible performance penality for this. However, under pathological circumstance this can fail: Warning: If the app has too many files opened and tries to report a failure using formats other than a combination of %s and %M, it may fail to create a temporary file. Similarly, if you experience severe memory shortage, don't try to report it using this function, as it needs some available memory for its own internal working. If you did not define NDEBUG when compiling this module, after registering the event this function will call FormatMessage to format the message and output it on stdout along with the return code from ReportEvent. Parameters: log  a poiter to an initialized log_event_data id  the message id b_len  length of the blob blob  chunk of binary data args  list of insertion arguments See also: log_event() log_event_blob()

---