Share via

3.1.4.5 ElfrRegisterEventSourceW (Opnum 8)

  • Article

The ElfrRegisterEventSourceW (Opnum 8) method instructs the server to return a server context handle to an event log for writing. The caller MUST have permission to write to the file containing the event log for this to succeed. The module name argument specifies the event source that is used to determine the relevant event log as specified below.

 NTSTATUS ElfrRegisterEventSourceW(
   [in] EVENTLOG_HANDLE_W UNCServerName,
   [in] PRPC_UNICODE_STRING ModuleName,
   [in] PRPC_UNICODE_STRING RegModuleName,
   [in] unsigned long MajorVersion,
   [in] unsigned long MinorVersion,
   [out] IELF_HANDLE* LogHandle
 );

UNCServerName: A server interface handle. A pointer to a Unicode (as specified in [MS-DTYP]) string specifying the server, as specified in section 2.2.7. The client MUST map this string to an RPC binding handle, and the server MUST ignore this argument, as specified in [C706] sections 4.3.5 and 5.1.5.2.

ModuleName: Specifies the event source, as defined in section 1.8.3 and specified in section 2.2.11, for which a handle is needed.

RegModuleName: This parameter MUST be ignored by the server. Clients MUST specify an empty string.

MajorVersion: Major version of the client. This value MUST be set to 1.

MinorVersion: Minor version of the client. This value MUST be set to 1.

LogHandle: Pointer to an event log handle. This parameter is a server context handle, as specified in section 2.2.6.

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].

In response to this request from the client, the server MUST determine what event log the client is requesting the handle for. The server MUST treat the ModuleName parameter as the event source name, as specified in section 1.8.3. If the ModuleName parameter does not specify a known event source, the server MUST default to requesting access to the application log that MUST always exist. As to the known application logs, refer to section 3.1.4.3. Note that the server checks the known event source by going over the registry sub keys under the event log registry key. As to how the event sources are registered under an event log key, refer to section 3.1.1.3.

The client SHOULD know the configured event log source names in the server before issuing this call. The client SHOULD NOT call this function unless the given event source name exists in the server.

Then the server MUST verify that the caller has write access to the event log, and the server MUST fail the operation if the caller does not have write access to the log. The server SHOULD return STATUS_ACCESS_DENIED (0xC0000022) to indicate this failure.

If the checks above are successful, the server MUST attempt to create a handle to the wanted log and if successful, the server MUST return the handle via the LogHandle parameter. Creating the handle only fails in the case where the server runs out of memory resources, if that happens, the server returns STATUS_NO_MEMORY (0xC0000017).

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