3.1.4 Message Processing Events and Sequencing Rules

  • Article

 

This section is an overview of the 21 RPC methods used by the EventLog Remoting Protocol. With one exception, there are two versions of each method that have one or more strings in the argument list: One version takes Unicode strings as arguments (such methods are denoted by a 'W' at the end of the method, which is short for Wide), and one version takes ANSI strings as arguments (such methods are denoted by an 'A' at the end of the method, which is short for ANSI). ANSI strings are converted to Unicode strings at the server (as specified in section 2.2.10) before being further interpreted at the server.

The names and opnums of each method are given below as well as a simple description of the method.

Methods in RPC Opnum Order

Method

Description

ElfrClearELFW

Clears event logs.

Opnum: 0

ElfrBackupELFW

Creates a backup of a live event log.

Opnum: 1

ElfrCloseEL

Used to close context handles obtained by the ElfrOpenELW method, ElfrOpenELA method, ElfrOpenBELW method, or ElfrOpenBELA method.

Opnum: 2

ElfrDeregisterEventSource

Used to close context handles obtained by the ElfrRegisterEventSourceW method or the ElfrRegisterEventSourceA method.

Opnum: 3

ElfrNumberOfRecords

Obtains the number of records in an event log.

Opnum: 4

ElfrOldestRecord

Obtains the record number of the oldest record in an event log.

Opnum: 5

ElfrChangeNotify

Reserved for local use. Notifies local processes about changes to the event log.

Opnum: 6

ElfrOpenELW

Opens a handle to a live event log that can be used for reading or clearing.

Opnum: 7

ElfrRegisterEventSourceW

Opens a handle to a live event log that can be used for writing.

Opnum: 8

ElfrOpenBELW

Opens a handle to a previously backed up event log. The handle is used for reading.

Opnum: 9

ElfrReadELW

Reads one or more events from an event log.

Opnum: 10

ElfrReportEventW

Writes an event to an event log.

Opnum: 11

ElfrClearELFA

Clears an event log.

Opnum: 12

ElfrBackupELFA

Creates a backup of a live event log.

Opnum: 13

ElfrOpenELA

Opens a handle to a live event log that can be used for reading or clearing.

Opnum: 14

ElfrRegisterEventSourceA

Opens a handle to a live event log that can be used for writing.

Opnum: 15

ElfrOpenBELA

Opens a handle to a previously backed up event log that can be used for reading.

Opnum: 16

ElfrReadELA

Reads one or more events from an event log.

Opnum: 17

ElfrReportEventA

Writes an event to an event log.

Opnum: 18

Opnum19NotUsedOnWire

Reserved for local use.

Opnum: 19

Opnum20NotUsedOnWire

Reserved for local use.

Opnum: 20

Opnum21NotUsedOnWire

Reserved for local use.

Opnum: 21

ElfrGetLogInformation

Gets information on an event log.

Opnum: 22

Opnum23NotUsedOnWire

Reserved for local use.

Opnum: 23

ElfrReportEventAndSourceW

Writes a single event to an event log.

Opnum: 24

ElfrReportEventExW

Writes an event to an event log.

Opnum: 25

ElfrReportEventExA

Writes an event to an event log.

Opnum: 26

In the preceding table, the phrase "Reserved for local use" means that the client MUST NOT send the opnum, and the server behavior is undefined because it does not affect interoperability.

The first group of conceptual operations relates to initiating interaction with an event log, which is either a backup event log or a live event log (for the distinction between live and backup, see section 1.3). Interaction can be initiated with a live event log for either writing to the event log or for reading or clearing the event log. Because each of the three conceptual operations can use either Unicode or ANSI strings, this accounts for six of the 20 methods.

The second group of conceptual operations relates to interacting with a log by reading from the log, clearing the log, creating a backup of the log, writing to the log, or writing to the log and specifying the name of the source at the time of the write. Four of these five conceptual operations can use either Unicode or ANSI strings as arguments, accounting for another (2 x 4 + 1) = 9 of the 20 methods.

The third group of conceptual operations relates to getting metadata on the log: the number of the oldest record in the log, the total number of records in the log, or other information on the log. These account for another three of the 20 methods.

The fourth group of conceptual operations relates to freeing resources maintained on the server to support its interaction with this client. These account for the remaining two of the 20 methods.

The methods are presented in the table above in the same order as this conceptual grouping.

All methods MUST NOT throw exceptions. All return values use the NTSTATUS numbering space; and, in particular, a value of 0x00000000 indicates success, and any other return value indicates an error. All possible error values are specified in [MS-ERREF] section 2.3 and they MUST be treated the same, unless specified otherwise.<14>

Because the server makes access control decisions as part of the response to Eventlog Remoting Protocol requests, the client MUST authenticate to the server, as specified in section 2.1.1. This is the responsibility of a lower-layer protocol, RPC with named pipes (as specified in [C706]); and the access control decisions affecting the Eventlog Remoting Protocol are made based on the identity conveyed by this lower-layer protocol.

The RPC interface for the Eventlog Remoting Protocol only uses handles of type IELF_HANDLE. There are two groups of functions that can be used to obtain one of these handles. This protocol asks the RPC runtime via the strict_context_handle attribute to reject use of context handles created by a method of a RPC interface different from this one, as specified in [MS-RPCE] section 3.1.1.5.3.2.2.2.

There are specific methods used for opening handles for reading. These methods are log-oriented. The caller specifies the particular log (such as Application) or the name of a previously backed up log. These methods MUST succeed if the caller has read access, independent of if the caller has write or clear access (security permissions that allow the user to write to or clear the event log). The server has an access control list (ACL) that is used to control access to the log. The protocol has no methods for reading or setting that ACL. A caller with read access can read events, get log information (such as the number of records or oldest record), and determine if the log is full. These methods are:

  • ElfrOpenELW (section 3.1.4.3)

  • ElfrOpenELA (section 3.1.4.4)

  • ElfrOpenBELW (section 3.1.4.1)

  • ElfrOpenBELA (section 3.1.4.2)

The ElfrOpenELA (section 3.1.4.4) and ElfrOpenELW (section 3.1.4.3) methods are used to obtain handles for backing up and clearing event logs.

For writing purposes, a second group is used. In addition to requiring that the caller have Write permission, the methods use the name of the event source to determine the event log to write to. These methods are:

  • ElfrRegisterEventSourceW (section 3.1.4.5)

  • ElfrRegisterEventSourceA (section 3.1.4.6)

The 'A' or 'W' suffix in the method name signifies whether the string arguments to the method contain ANSI or Unicode characters. This MUST NOT affect calls to subsequent methods. For example, a handle obtained by using the ElfrOpenELW (section 3.1.4.3) method MUST be usable with either ElfrReadELW (section 3.1.4.7) or ElfrReadELA (section 3.1.4.8).

When opening the handles, the server MUST check for additional rights. For example, the ElfrRegisterEventSourceW (section 3.1.4.5) method MUST succeed if and only if the caller has write access, independent of if the caller has read or clear access. However, the handle returned by the server MUST also be associated with the read and clear accesses if they are possessed by the client. Therefore, a handle returned by the ElfrRegisterEventSourceW (section 3.1.4.5) method MUST be usable for purposes other than writing if the caller has the appropriate permissions. Similarly, a handle returned via ElfrOpenELW (section 3.1.4.3) or ElfrOpenELA (section 3.1.4.4) MUST be usable for writing if the caller has write access.

Later in this section, the requirements on the internal state at the server for these methods to succeed are specified as well as the updates to server state caused by each method if the method succeeds.

The return values of these methods are of the type NTSTATUS. Some of the return values are specified in the server processing rule section for each method. Protocol implementers can choose to return other, implementation-based return values, such as those returned from operating system components that are used to implement the protocol. Protocol implementers SHOULD only use return values listed in [MS-ERREF].