3.1.1.5 Context Handles

  • Article

Clients obtain context handles for both reading and writing purposes. The methods for doing so are specified in section 3.1.4. The server MUST maintain a relationship between each particular handle and a particular log. For handles used for writing, the server MUST also maintain the name of the event source so that it can be injected into any events written using the handle. For handles used for reading, the server MUST maintain the position of the last read so that subsequent sequential mode reads can succeed. Server implementations define the following context_handle structure to maintain this information:

 typedef [context_handle] struct _ELF_HANDLE {
     ULONG    Signature;
     ULONG    Flags;
     unsigned __int64 LastRecordRead;
     ULONG    MajorVersion;  
     ULONG    MinorVersion;
     void*    LogPublisher;
     ULONG    NameLength;
     [size_is(NameLength)] WCHAR Name[]; 
 } *IELF_HANDLE;
  
 typdef IELF__HANDLE *PIELF_HANDLE;

Signature: A ULONG value that is always 0x654c6648 to indicate a valid handle.

Flags: This is used to distinguish the log handle type. A backup log handle or a normal log handle. The allowed flag values and their meanings are specified as follows.

  • 0x00000001: This flag is used to specify that the handle is out of sync and that the reader needs to sync the latest content because some writing has occurred.

  • 0x00000002: This flag is used to specify that the log file is opened for backup.

  • 0x00000004: This flag is used to specify that the log handle is a remote handle.

  • 0x00000008: The flag is used to specify that the event log read direction is forward.

LastRecordRead: The last record ID read by the event log server. The record ID is the identifier of event log records in the event log file. The server uses this value as the hint to get the next record when fetching the event records to the user.

MajorVersion: The major version number of this structure definition.

MinorVersion: The minor version number of this structure definition.

LogPublisher: The event provider object. This object is the internal representation of the event source.

NameLength: The length of the event log file name.

Name: The event log file name string.

Unless otherwise specified, all handles in section 3.1.4 and its subsections are context handles.