3.1.4.27 EvtRpcGetEventMetadataEnum (Opnum 26)

  • Article

The EvtRpcGetEventMetadataEnum (Opnum 26) method obtains a handle for enumerating a publisher's event metadata.

 error_status_t EvtRpcGetEventMetadataEnum(
   [in, context_handle] PCONTEXT_HANDLE_PUBLISHER_METADATA pubMetadata,
   [in] DWORD flags,
   [in, unique, range(0, MAX_RPC_FILTER_LENGTH), string] 
     LPCWSTR reservedForFilter,
   [out, context_handle] PCONTEXT_HANDLE_EVENT_METADATA_ENUM* eventMetaDataEnum
 );

pubMetadata: This parameter is an RPC context handle, as specified in [C706], Context Handles. For information on handle security and authentication considerations, see sections 2.2.20 and 5.1.

flags: A 32-bit unsigned integer that MUST be set to zero when sent and MAY be ignored on receipt.<54>

reservedForFilter: A pointer to a null string that MUST be ignored on receipt.

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

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 handle. The server SHOULD save the context handle value it creates in the EvtRpcGetPublisherMetadata method (as specified in section 3.1.4.25) in its handle table and compare it with the handle passed here to perform the check.<55> The server MUST return ERROR_INVALID_PARAMETER (0x00000057) if the handle is invalid.

If the previous check succeeds, the server MUST attempt to create an event metadata object and assign it to the eventMetadataEnum parameter after casting to a CONTEXT_HANDLE_EVENT_METADATA_ENUM handle (see section 3.1.1.11 for the content of an event metadata object). The server SHOULD add the newly created handle to its handle table in order to track it. If the previous check fails, the server MUST NOT create the context handle or add it to the handle table. Creating the context handle SHOULD only fail due to a shortage of memory, in which case the server SHOULD return ERROR_OUTOFMEMORY (0x0000000E).

After the server creates the event metadata object, it SHOULD preload the EventsMetaData field for the metadata object. First, the server SHOULD cast the pubMetadata context handle into the publisher metadata object and then read out the ResourceFile value. Next, the server SHOULD open the resource file and find the events information section (as specified in section 3.1.1.14). The server SHOULD read all the events information into memory and assign the start address to the EventsMetaData field and then set the Enumerator field to 0.

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