Tcl Windows API extension

This module provides commands for reading and writing the Windows event log. The following commands, although described here, are available in the twapi_base package itself and do not require this module to be loaded: eventlog_open, eventlog_log, eventlog_write and eventlog_close. This allows applications to write to the event log without this module being loaded.

Overview

The Windows event log provides a common application-independent mechanism for applications to log messages for diagnostic and informational purposes. The infrastructure and API's supporting this mechanism changed starting with Windows Vista. Although the older Windows API's will also work on Vista and later versions, they are limited in their support for events logged by applications using the newer API's.

TWAPI follows the Windows model by providing two sets of commands corresponding to the two Windows API sets and in addition also provides a set of unified commands:

Commands prefixed with eventlog are layered on top of the older pre-Vista API's. These will work on all Windows systems but reflect the inability of the underlying Windows API to fully format messages for events logged by applications using the new APIs.
Commands prefixed with evt are layered on top of the newer API's. These can deal with events logged by applications using either API version but can only be used on Windows Vista and later. They will raise an error on earlier versions of Windows.
Commands prefixed with winlog present a unified interface and direct calls to the appropriate Windows API depending on operating system version. They also present a single interface to the application irrespective of the operating system. However, they do not cover features that are unique to a specific Windows API and have a slight performance penalty.

For reading the event log, use of the winlog set of commands is recommended as those will use the underlying API that is most appropriate for that OS version. Alternatively, if platform-specific features not available through those commands are required, applications can call the eventlog or evt commands as appropriate after checking the operating system version.

Using eventlog Commands

This section describes the use of the older pre-Vista event log commands. Most access to the event log using this API requires a handle returned by the eventlog_open command. A handle allows either read or write access, but never both. Returned handles must be closed when no longer required by calling eventlog_close.

Events can be written using the eventlog_write command. The eventlog_log command provides an alternate, simpler but less flexible, interface for writing events.

Events can be read from an event log through the eventlog_read command. The returned event record can be formatted using eventlog_format_message and eventlog_format_category.

The command eventlog_count returns the number of records in the event log. eventlog_oldest returns the record number of the oldest record. The command eventlog_is_full indicates whether the event log is full.

To monitor the event log in real time, an application can poll at regular intervals. However, a more efficient way is to set up notifications through the eventlog_subscribe command.

Event logs can be backed up using eventlog_backup or as a side effect of clearing the log through eventlog_clear. The backup file can be read using the standard eventlog_open and eventlog_read commands.

Using evt Commands

This section describes the use of the newer event log commands available in Windows Vista and later Windows version. The corresponding Windows API functions are prefixed with Evt in the Windows SDK. TWAPI does not support writing events using the new API. Only reading of events is supported.

The new event logging subsystem in Windows Vista is considerably more flexible (and complex) than what was available in earlier Windows versions. The description below assumes the reader is familiar with the terms and concepts described in the Windows SDK.

In the Vista event logging system, channels implement a event stream to which event publishers can write events. The commands evt_channels and evt_publishers return the names of the channels and publishers on a system respectively.

Event consumers can consume events from channels in real time or from a saved event file using the the evt_query command. This command returns a handle to a result set containing matching events. These can then be retrieved and processed using the evt_next and evt_decode_events or evt_decode_event.

All handles returned by the evt_* commands, such as those returned from evt_next and evt_query must be closed by passing them to evt_close.

To monitor the event log in real time, use the evt_subscribe command.

Using winlog Commands

This section describes the use of the TWAPI's common interface to the old and new versions of Windows event log APIs. This is the recommended interface for consuming events but does not provide a command to write events.

The common access commands require a handle to the event log which can be obtained via the winlog_open command. The returned handle must be closed when no longer required by calling winlog_close.

Events can be read from an event log through the winlog_read command which returns a list of dictionaries containing the fields of each event. winlog_event_count returns the number of events in an event log.

Events can be written to a backup file using winlog_backup and cleared with winlog_clear.

To monitor the event log in real time, use the winlog_subscribe command.

Commands

eventlog_backup EVENTLOGHANDLE FILENAME

Backs up the specified event log to the file FILENAME. The file may be opened for reading using the eventlog_open command. EVENTLOGHANDLE must be a read handle.

eventlog_clear EVENTLOGHANDLE ?-backup FILENAME?

Clears the specified event log. If the -backup option is specified, the event log is first backed to the file FILENAME. EVENTLOGHANDLE must be a read handle (even though the command actually modifies the event log).

eventlog_close EVENTLOGHANDLE

Closes a handle previously returned by eventlog_open and frees any associated resources.

eventlog_count EVENTLOGHANDLE

Returns the number of records in the specified event log. EVENTLOGHANDLE must be a read handle.

eventlog_format_category EVENT_RECORD ?options?

Returns the text corresponding to the numeric category field in EVENT_RECORD by looking up the appropriate resources. EVENT_RECORD must be an element of the event record list returned from the eventlog_read command.

The following options may be specified with the command:

-langid LANGID	Passed to the format_message command for formatting. See the description of that function for details.
-width MAXLINEWIDTH	Passed to the format_message command for formatting. See the description of that function for details.

eventlog_format_message EVENT_RECORD ?options?

Returns the text corresponding to the message in EVENT_RECORD by looking up the appropriate resources. EVENT_RECORD must be an element of the event record list returned from the eventlog_read command.

The following options may be specified with the command:

-langid LANGID	Passed to the format_message command for formatting. See the description of that function for details.
-width MAXLINEWIDTH	Passed to the format_message command for formatting. See the description of that function for details.

eventlog_is_full EVENTLOGHANDLE

Returns 1 if the specified event log is full, and 0 otherwise. EVENTLOGHANDLE may be either a read or a write handle.

eventlog_log MESSAGE ?options?

Writes a record into the specified event log. This is a wrapper around eventlog_open, eventlog_write, eventlog_close for simple logging needs and should be used for applications that do not have a message file.

The following options may be specified to control the values of the various fields in the event log record:

-system SYSTEMNAME	Specifies the system on which the event log resides. By default, this is the local system.
-source SOURCENAME	Specifies a event log source. The returned handle will refer to the event log to which events from SOURCENAME are logged. This defaults to the filename portion (without the path or extension) of the executable file.
-type EVENTTYPE	Indicates the type or severity of the event. EVENTTYPE should be one of success, error, warning, information (default), auditsuccess or auditfailure.
-category CATEGORY	This should be a integer corresponding to a category id in the event source's category or message file. This value defaults to 0.

eventlog_monitor_start EVENTLOGHANDLE SCRIPT

Deprecated Registers SCRIPT to be invoked whenever the event log specified by EVENTLOGHANDLE receives a new event. EVENTLOGHANDLE must be a read handle to an event log on the local system. Windows will invoke SCRIPT only when new events are written to the event log but no more than once every 5 seconds. Note that EVENTLOGHANDLE must not be closed in order for the notifications to be sent.

The command returns an id for the notification. When the application is no longer interested in receiving notifications, it should release the associated resources by passing the id to eventlog_monitor_stop. This is required even if EVENTLOGHANDLE is closed.

eventlog_monitor_stop EVENTNOTIFICATIONID

Deprecated Stops notifications from the event log. EVENTNOTIFICATIONID is the id returned from a previous call to eventlog_monitor_start.

eventlog_oldest EVENTLOGHANDLE

Returns the record number of the oldest record in the specified event log. EVENTLOGHANDLE must be a read handle.

eventlog_open ?options?

Returns a handle to the specified event log. When no longer required, it should be closed by passing it to eventlog_close. Various options specify the event log to be opened and the read-write mode.

-file EVENTLOGBACKUPFILE	Specifies the name of a backed up event log file. This option may not be used with the -source or -system options.
-source SOURCENAME	Specifies a event log source. The returned handle will refer to the event log to which events from SOURCENAME are logged. This defaults to the filename portion (without the path or extension) of the executable file. This option may not be used with the -file option.
-system SYSTEMNAME	Specifies the system on which the event log resides. By default, this is the local system. This option cannot be used with the -file option.
-write	Returns a handle used for writing to the event log. By default, a read handle is returned. Note that event log handles are never read-write. Applications wishing to do both need to open two separate handles. This option may not be used with the -file option as event log backup files cannot be written to.

eventlog_read EVENTLOGHANDLE ?options?

Returns a list of event records read from the specified event log. EVENTLOGHANDLE must be a read handle. The number of records returned may vary depending on the number of records in the event log as well as internal buffering limits. Returns an empty list when no more records can be read. Each eventlog_read command moves the event log read pointer.

The following options may be specified to control the read operation:

-seek RECORDNUMBER	Normally the command returns event log records starting from current read pointer. If this option is specified, the command will return records starting with the one with record number RECORDNUMBER.
-direction backward\|forward	Controls the direction in which the read pointer moves. By default, the commands will return records reading forwards from the current read pointer.

Each element in the returned list corresponds to an event log record and is a list of the form field value .... The following fields are returned in each event record:

-category	This is an integer corresponding to a category id in the event source's category or message file.
-data	Raw binary data stored as part of the event record.
-eventid	The event id that identifies the event type. See eventlog_write for how this may be used.
-params	A list of strings corresponding to the positional %N format specifiers in the format string for the event in the message file.
-sid	The SID of the user account of the thread that logged the event. This may be a null string if this information was not included in the record.
-recordnum	The record number for this record. This may be used with the -seek option to locate a record.
-source	The event source that logged the event.
-system	The name of the system on which the event was generated.
-timegenerated	Contains the time that the event was generated (UTC) expressed as an offset in seconds since 00:00:00 Jan 1, 1970. This can be passed to the clock format command to convert to an absolute time.
-timewritten	Contains the time (UTC) that the event was written into the event log expressed as an offset in seconds since 00:00:00 Jan 1, 1970. This can be passed to the clock format command to convert to an absolute time.
-type	Indicates the type or severity of the event. The value is one of success, error, warning, information, auditsuccess or auditfailure.

eventlog_subscribe EVENTSOURCE

Registers for notifications when events are logged to the specified event log. Returns a pair of two handles, the first is a handle that can be passed to eventlog_read to retrieve logged events. The second is a handle that is signalled when events are available to be read on the channel. It can be used in either synchronous or asynchronous mode with wait_on_handle.

When notifications are no longer desired, the two handles in the returned pair must be released via eventlog_close and close_handle respectively.

This command is internally identical to winlog_subscribe on Windows version before Vista. On Vista and later, this command translates to the older Windows event log API while winlog_subscribe will invoke the new Vista APIs.

eventlog_write EVENTLOGHANDLE EVENTID ?options?

Writes a record into the specified event log. EVENTLOGHANDLE must be a write handle for an event log. EVENTID is a integer that identifies the specific event. If the event source is configured in the registry, this is the message id for the event in the message file for the source. If no message file has been configured, this event id is irrelevant.

The following options may be specified to control the values of the various fields in the event log record:

-type EVENTTYPE	Indicates the type or severity of the event. EVENTTYPE should be one of success, error, warning, information (default), auditsuccess or auditfailure. Note that the last two may only be used when writing to the Security event log.
-category CATEGORY	This should be a integer corresponding to a category id in the event source's category or message file. This value defaults to 1.
-loguser	Specifying this will cause the SID of the user account for this thread to be included in the event record.
-params PARAMLIST	Specifies a list of strings corresponding to the positional %N format specifiers in the format string for the event in the message file. If the source has not been configured with a message file in the registry, event viewers will generally display this as a list of strings.
-data DATA	Raw binary data that should be stored as part of the event record.

evt_channels

Returns a list of names of the channels on the system.

evt_clear_log CHANNELNAME ?-backup BACKUPFILE?

Clears the specified event channel of all events. If -backup is specified, the events are written to the specified backup file before the channel is cleared.

evt_close ?EVTHANDLE EVTHANDLE...?

Close handles returned by various EVT commands such as evt_query or evt_next.

evt_decode_event HEVENT ?options?

Returns information about an event. HEVENT is a handle to an event such as an element of the list returned from evt_next.

The returned information is in the form of a dictionary. The keys in the dictionary are the same as the fields of the record array returned by evt_decode_events. See the documentation of that command for fields and options.

Besides the options for evt_decode_events, the following additional options may also be specified:

-hpublisher HPUBLISHER	A handle to the event publisher metadata. If not specified, the publisher metadata for the event is extracted from the event itself.
-values HVALUES	By default, the command will pick any values to be inserted into the formatted event string from the event itself. If this option is specified, the values will instead be picked from HVALUES which must be a handle to a render values block.

evt_decode_events HEVENTLIST

Returns a record array containing decoded events. HEVENTLIST is a list of handles to events as returned from evt_next.

The returned record array always contains the following system fields which are present in all events:

-activityid	GUID containing the activity id associated with the event.
-channel	The channel to which the event was logged.
-computer	The name of the system on which the event was logged.
-eventid	The event id for the event's definition.
-eventrecordid	The id of this event record.
-keywordmask	An integer mask with bits corresponding to the event's keywords.
-level	The numeric level for the event.
-opcode	The numeric opcode for the event.
-pid	The process id of the process that logged the event.
-providerguid	The GUID of the logging event provider.
-providername	The name of the logging event provider.
-qualifiers
-relatedactivityid	GUID containing the relative activity id associated with the event.
-task	The numeric task for the event.
-tid	The thread id of the logging thread.
-timecreated	The time the event was logged in 100ns units since January 1, 1601 UTC.
-sid	The SID of the account under which the logging thread was running.
-version	The version of the event definition.

In addition, the returned record array will include the following keys if they are specified as options to the command:

-keywords	Contains a list of keywords with which the event is tagged.
-levelname	Contains the string associated by the publisher with the numeric level.
-message	Contains the formatted message corresponding to the event.
-opcodename	Contains the string associated by the publisher with the numeric opcode field.
-taskname	Contains the string associated by the publisher with the numeric task field.
-xml	Contains an XML fragment describing the event.

The following additional options may also be specified with the command:

-ignorestring STRING	If specified, STRING is returned for any field that cannot be obtained. Without this option, errors retrieving fields will generate a Tcl exception.
-lcid LCID	Specifies the language in which the message is to be formatted. Defaults to the locale of the calling thread. This option is ignored if the -hpublisher option is specified.
-logfile PATH	Specifies the path to the logfile containing archived publisher metadata for the event. This option is ignored if the -hpublisher option is specified.
-session HSESSION	Specifies the session to the event logging subsystem for the event. By default the local event logging subsystem is used.

evt_export_log OUTFILE ?options?

Exports events, optionally matching a query, from a channel or a previously exported log file to a target log file.

The following options may be specified to select which events are included in the result set.

-channel CHANNELNAME	Specifies the event channel from which events are to be read. Cannot be used with the -file option.
-file PATH	Specifies the event file from which events are to be read. Cannot be used with the -channel option.
-ignorequeryerrors	Normally, if retrieving a specific event results in an error, Windows will fail the query and a Tcl exception will be raised. If -ignorequeryerrors is specified, such events are simply skipped and any further events are returned.
-query QUERYSTRING	Specifies the selection criteria for events that should be included in the returned result set. QUERYSTRING should be * (for all events, default), an XPATH expression or a structured XML query. See the Windows SDK for details.

evt_next HEVTRESULTSET ?options?

Returns a list containing events from a event query result set. HEVTRESULTSET is a handle to a result set as returned by evt_query. The returned list elements are event handles which can be passed to evt_decode_event. These event handles must be closed via evt_close.

The command returns an empty list if no more events are available. The behaviour of further calls depends on whether HEVTRESULTSET was returned from evt_query or evt_subscribe. In the former case, an empty list will continue to be returned even if additional events are logged to a channel. In the latter case, the command will return those events.

The cursor in the event result set is moved past the returned events so each evt_next returns events from the result set in sequence.

The following options can be specified:

-count COUNT	Returns COUNT events from the result set. The actual number of events returned may be less if the end of the result set is reached. If unspecified, the number of returned events depends on various internal tuning factors and applications must not rely on a specific number being returned.
-status VARNAME	The name of a variable in which to return status. If there is an error when reading the next event, the command will normally generate an Tcl exception. If this option is specified, the command will instead return an empty list and store the error code in the specified variable.
-timeout MILLISECONDS	Specifies the number of milliseconds to wait for events. A value of -1 (default) indicates call should not time out.

evt_publishers

Returns a list of names of the publishers registered on the system.

evt_query ?options?

Returns a handle to a result set containing events matching the specified criteria. Events from the result set are read using the evt_next command. Note that once the end of the result set returned by evt_query is reached, further events that are logged will not be returned.

After processing events, the handle must be closed using the evt_close command.

The following options may be specified to select which events are included in the result set.

-channel CHANNELNAME	Specifies the event channel from which events are to be read. Cannot be used with the -file option.
-direction DIRECTION	If DIRECTION is forward events are returned oldest first. If DIRECTION is backward, events are returned newest first.
-file PATH	Specifies the event file from which events are to be read. Cannot be used with the -channel option.
-ignorequeryerrors	Normally, if retrieving a specific event results in an error, Windows will fail the query and a Tcl exception will be raised. If -ignorequeryerrors is specified, such events are simply skipped and any further events are returned.
-query QUERYSTRING	Specifies the selection criteria for events that should be included in the returned result set. QUERYSTRING should be * (for all events, default), an XPATH expression or a structured XML query. See the Windows SDK for details.

evt_subscribe CHANNELPATH ?options?

Registers for notifications when events are logged to the event channel CHANNELPATH. Returns a pair of two handles, the first is a handle that can be passed to evt_next to retrieve logged events. The second is a handle that is signalled when events are available to be read on the channel. It can be used in either synchronous or asynchronous mode with wait_on_handle.

Note that Windows will not signal the handle unless a call to evt_next fails and a new event arrives. The mere presence of unread events is not sufficient.

When notifications are no longer desired, the two handles in the returned pair must be released via evt_close and close_handle respectively.

The following options may be specified:

-ignorequeryerrors	Normally, if retrieving a specific event results in an error, Windows will fail the query and a Tcl exception will be raised. If this option is specified, such events are simply skipped and any further events are returned.
-includeexisting	By default the command will only subscribe to new events. If this option is specified, notification is sent for existing events as well.
-query QUERYSTRING	Specifies the selection criteria for events that should be included in the returned result set. QUERYSTRING should be * (for all events, default), an XPATH expression or a structured XML query. See the Windows SDK for details.

winlog_backup NAME BACKUPFILE

Writes events from the specified event channel or source to a backup file. NAME is the name of an event log source (pre-Vista) or channel (Vista and later).

winlog_clear NAME ?-backup BACKUPFILE?

Clears the specified event channel or source of all events. NAME is the name of an event log source (pre-Vista) or channel (Vista and later).

If -backup is specified, the events are written to the specified backup file before the channel is cleared.

winlog_close WINLOGHANDLE

Closes the handle WINLOGHANDLE which must have been previously returned by winlog_open and frees any associated resources.

winlog_event_count ?options?

Returns the number of events in the specified event log using the API appropriate for the Windows version. The following options may be specified with the command.

-channel NAME	Specifies a event log source (pre-Vista) or channel (Vista and later) from which events are to be read. This option may not be used with the -file option.
-file EVENTLOGBACKUPFILE	Specifies the name of a backed up event log file. This option may not be used with the -channel or -system options.
-system SYSTEMNAME	Specifies the system on which the event log resides. By default, this is the local system. This option cannot be used with the -file option.

winlog_open ?options?

Returns a handle to the specified event log using the API appropriate for the Windows version. When no longer required, it should be closed by passing it to winlog_close. The following options may be specified with the command.

-channel NAME	Specifies a event log source (pre-Vista) or channel (Vista and later) from which events are to be read. This option may not be used with the -file option.
-direction DIRECTION	If DIRECTION is forward events are returned oldest first. If DIRECTION is backward, events are returned newest first.
-file EVENTLOGBACKUPFILE	Specifies the name of a backed up event log file. This option may not be used with the -channel or -system options.
-system SYSTEMNAME	Specifies the system on which the event log resides. By default, this is the local system. This option cannot be used with the -file option.

winlog_read WINLOGHANDLE ?-lcid LCID?

Returns a record array containing events read from the specified event log. The handle WINLOGHANDLE must have been previously returned by winlog_open. LCID is the identifies the language in which messages are to be formatted.

The number of events returned may vary. Returns an empty record array when no more records can be read. Each winlog_read command moves the event log read pointer.

The returned record array contains the following fields describing the event : -channel, -taskname, -message, -providername, -eventid, -level, -levelname, -eventrecordid, -computer, -sid and -timecreated. Refer to evt_decode_events for details.

The record array may also contain additional fields that should be ignored.

winlog_subscribe CHANNEL_OR_SOURCE

Registers for notifications when events are logged to the specified event source or channel. Returns a pair of two handles, the first is a event log handle that can be passed to winlog_read to retrieve logged events. The second is a handle that is signalled when events are available to be read on the channel. It can be used in either synchronous or asynchronous mode with wait_on_handle.

Note that Windows will not signal the handle unless a call to winlog_read fails and a new event arrives. The mere presence of unread events is not sufficient.

When notifications are no longer desired, call winlog_close passing in the event log handle which is the first element in the returned list. This will also release the signal handle which need not be closed explicitly.

Event log

SYNOPSIS

DESCRIPTION

Overview

Using eventlog Commands

Using evt Commands

Using winlog Commands

Commands

COPYRIGHT

TWAPI 4.6.0 Documentation