3.1.4.17 ElfrReportEventExA (Opnum 26)

  • Article

The ElfrReportEventExA (Opnum 26) method<36> writes events to the event log; the server receives these events from the client.

 NTSTATUS ElfrReportEventExA(
   [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_STRING ComputerName,
   [in, unique] PRPC_SID UserSID,
   [in, size_is(NumStrings), unique] 
     PRPC_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.

EventType: The type of the 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. In practice, 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 SHOULD use that name 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 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. This can be set to any arbitrary value when sent. Any value sent by the client MUST be ignored on receipt by the server.

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

This method is identical to the ElfrReportEventExW (section 3.1.4.16) method except that the string arguments are ANSI strings in this case. Thus, the remarks in ElfrReportEventExW (section 3.1.4.16) apply to this method as well.