3.1.4.19 EvtRpcOpenLogHandle (Opnum 17)

The EvtRpcOpenLogHandle (Opnum 17) method is used by a client to get information about a channel or a backup event log.

 error_status_t EvtRpcOpenLogHandle(
   /* [in] RPC_BINDING_HANDLE binding, {the binding handle will be generated by MIDL} */
   [in, range(1, MAX_RPC_CHANNEL_NAME_LENGTH), string] 
     LPCWSTR channel,
   [in] DWORD flags,
   [out, context_handle] PCONTEXT_HANDLE_LOG_HANDLE* handle,
   [out] RpcInfo* error
 );

binding: An RPC binding handle as specified in section 2.2.21.

channel: A pointer to a string that contains a channel or a file path.

flags: MUST be one of the following two values.

Value	Meaning
0x00000001	Channel parameter specifies a channel name.
0x00000002	Channel parameter specifies a file name.

handle: A pointer to a log handle. This parameter is an RPC context handle, as specified in [C706], Context Handles.

error: A pointer to an RpcInfo (section 2.2.1) structure in which to place error information in the case of a failure. The server MAY set the suberror fields to supply more comprehensive error information.<35> If the method succeeds, the server MUST set all of the values in the structure to 0.

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

In response to this request from the client, the server MUST first validate the channel parameter. The server SHOULD search for the given channel name in its channel table. If the server doesn't find the name, the specified channel name is not valid. If the specified channel name is invalid, the server SHOULD return the error code ERROR_EVT_CHANNEL_NOT_FOUND (0x00003A9F). If the flags parameter is set to 0x00000001, the server MUST interpret the channel parameter as a channel name. If the flags parameter is set to 0x00000002, the server MUST interpret channel as the path to an existing event log file. The server SHOULD return ERROR_INVALID_PARAMETER (0x00000057) if the flags parameter is not 0x00000001 or 0x00000002.<36> The server checks this by calling the file system to check if the file exists. If the event log file does not exist on the server, the server SHOULD return the error code ERROR_FILE_NOT_FOUND (0x00000002).

Next the server MUST verify that the caller has read access to the channel or the file and MUST fail the method if the caller does not have read access. To perform the access check, the server SHOULD first determine the identity of the caller. Information determining the identity of the caller for the purpose of performing an access check is specified in [MS-RPCE] section 3.2.3.4.2. Then, if the client specifies a channel, the server SHOULD read the channel's access property (as specified in section 3.1.4.21) as the security descriptor string. Next, the server SHOULD be able to perform the write and clear access check using the Access Check algorithm (as specified in [MS-DTYP] section 2.5.3.2). The server MUST fail the method with the error code ERROR_ACCESS_DENIED (0x00000005) if the client does not have read access to the channel or the file.

If the preceding checks succeed, the server MUST attempt to create a CONTEXT_HANDLE_LOG_HANDLE. To perform this operation, the server SHOULD create a log object as specified in section 3.1.1.11. This object is the server-side object for CONTEXT_HANDLE_LOG_HANDLE. The server SHOULD add the newly created handle to its handle table in order to track it.

The server SHOULD set the LogType field of the log object to be either a channel or a backup event log based on the client's input flags value. If the type is channel, the server SHOULD try to find the channel in its channel table and SHOULD fail the method with ERROR_CHANNEL_NOT_FOUND (0x00003A9F) if the server cannot find the channel. After the channel is found, the server SHOULD set the Channel field of the log object to be the pointer that points to the channel entry in the channel table. If the type is backup event log file, the server SHOULD try to check if the file exists and SHOULD fail the method with the ERROR_FILE_NOT_FOUND (0x00000002) if the backup event log file does not exist. If the backup event log file exists, the server SHOULD try to open the backup event log file (see [PRA-CreateFile]) and set the Channel field of the log object to be the file handle if the server successfully opens the file. If the server fails to open the file, it MUST return the error from the CreateFile method that is reporting the error.

If any of the preceding checks fail, the server MUST NOT create the context handle.

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