3.1.4.16 ElfrReportEventExW (Opnum 25)

The ElfrReportEventExW (Opnum 25) method<31> writes events to the event log; the server receives these events from the client.

 NTSTATUS ElfrReportEventExW(
   [in] IELF_HANDLE LogHandle,
   [in] PFILETIME TimeGenerated,
   [in] unsigned short EventType,
   [in] unsigned short EventCategory,
   [in] unsigned long EventID,
   [in, range(0, 256)] unsigned short NumStrings,
   [in, range(0, 61440)] unsigned long DataSize,
   [in] PRPC_UNICODE_STRING ComputerName,
   [in, unique] PRPC_SID UserSID,
   [in, size_is(NumStrings), unique] 
     PRPC_UNICODE_STRING Strings[*],
   [in, size_is(DataSize), unique] 
     unsigned char* Data,
   [in] unsigned short Flags,
   [in, out, unique] unsigned long* RecordNumber
 );

LogHandle: A handle to an event log. This parameter is a server context handle, as specified in section 2.2.6. This handle MUST NOT be obtained via the ElfrOpenBELA (section 3.1.4.2) method or the ElfrOpenBELW (section 3.1.4.1) method. A handle received from either of those two methods will have the backup flag set, so the server checks this flag before calling this method.

TimeGenerated: The time at which the event was generated by the event source. This time is represented as a pointer to FILETIME as defined in [MS-DTYP] section 2.3.3.<32>

EventType: The type of event, as specified in section 2.2.2.

EventCategory: The event category, as specified in section 1.8.5.

EventID: The EventID, as specified in section 3.1.1.4.

NumStrings: The number of strings in the array pointed to by the Strings parameter. A value of zero indicates that no strings are present.

DataSize: The number of bytes of event-specific raw binary data to write to the log. This binary data is passed in the Data parameter. If the DataSize parameter is zero, event-specific data MUST NOT be present.

ComputerName: A string to assist in identifying the machine that generated the event; for example, the name of the computer. There are no character restrictions on this field's content (for example, a FQDN can be used). The API is not intended to support dynamically changing computer names. The ComputerName parameter is cached the first time a client calls the API, and that name used on subsequent calls until the machine is rebooted.

UserSID: Either NULL or a user SID. If this is NULL, the event is to have a zero length UserSid field.

Strings: Specifies the strings containing information specific to the event. This parameter MUST be a valid pointer. If the NumStrings parameter is zero, this parameter MUST be NULL. For example, an event relating to file deletion could use a string to specify the path of the file being deleted.

Data: A pointer to the buffer that contains the event-specific binary data. This parameter MUST be a valid pointer (or NULL), even if the DataSize parameter is zero.

Flags: Unused. MUST be set to zero when sent and MUST be ignored on receipt.

RecordNumber: Unused. Can be set to any arbitrary value when sent, and any value sent by the client MUST be ignored on receipt by the server.

Return Values: The method returns STATUS_SUCCESS (0x00000000) on success; otherwise, it returns an implementation-based, nonzero NTSTATUS value specified in [MS-ERREF].

In response to this request from the client, the server first checks that the handle is valid. The server MUST fail the operation with the error STATUS_INVALID_HANDLE (0xC0000008) if the handle is invalid.

If the handle comes from the ElfrOpenBELA (section 3.1.4.2) method or the ElfrOpenBELW (section 3.1.4.1) method, a backup flag is attached in the handle. The server MUST check that flag, and if the backup flag is set, the server MUST return STATUS_INVALID_HANDLE (0xC0000008).

The server SHOULD<33> check that the EventType and the TimeGenerated value are valid as specified.

The server MUST check that the SID is valid if it is not NULL, and MUST fail the method if the UserSid is invalid with the error code STATUS_INVALID_PARAMETER (0xC000000D).

If the handle is valid, the method attempts to create an event with the supplied parameters and by setting the TimeGenerated and the RecordNumber fields in the event. The TimeGenerated is obtained from the system clock. The server MUST get the RecordNumber from the state maintained for the event log. The server can get the last record in the event log file, read the record number from that record, and use that record number plus 1 as the new record number. The new record number SHOULD be set to the value in the event log file header so that the total number of records in the file is stored. The server sets the RecordNumber parameter to the same value written to the event prior to returning from this method.

The server MUST ignore the RecordNumber parameter received from the client.

Note that write access to the event log is verified when the ElfrRegisterEventSourceW (section 3.1.4.5) method is called, and the event log handle is opened successfully. There is no write access check in the ElfrReportEventExW (Opnum 25) method.

The server MUST attempt to store the event source name in the event. This event source was originally specified when the ElfrRegisterEventSourceW (section 3.1.4.5) method or the ElfrRegisterEventSourceA (section 3.1.4.6) method was called. The event source name is attached to the LogHandle when the ElfrRegisterEventSourceW (section 3.1.4.5) method or the ElfrRegisterEventSourceA (section 3.1.4.6) method returns. The server gets the event source name from the LogPublisher object (specified in section 3.1.1.5) that is contained in the LogHandle that was passed in, and logs it in the event.

If the above checks all succeed, the server attempts to copy the event into the event log and attempt to update the log state so that the record number is incremented for the next write. The server returns STATUS_LOG_FILE_FULL (0xC0000188) when the live event log file is full (the log reaches its maximum allowed size and can't be overwritten) and returns STATUS_DISK_FULL (0xC000007F) when there is no physical disk space for the new event record.

The server MUST return a value indicating success or failure for this operation.

Note: This method is almost identical to the ElfrReportEventW (section 3.1.4.13) method except that: the Time (second parameter) is replaced by TimeGenerated, enabling a more precise time to be logged; and there is no TimeWritten parameter.