3.1.4.28 EvtRpcGetNextEventMetadata (Opnum 27)

The EvtRpcGetNextEventMetadata (Opnum 27) method gets details about a possible event and also returns the next event metadata in the enumeration. It is used to enumerate through the event definitions for the publisher associated with the handle. The enumeration is in the forward direction only, and there is no reset functionality.

 error_status_t EvtRpcGetNextEventMetadata(
   [in, context_handle] PCONTEXT_HANDLE_EVENT_METADATA_ENUM eventMetaDataEnum,
   [in] DWORD flags,
   [in] DWORD numRequested,
   [out] DWORD* numReturned,
   [out, size_is(,*numReturned), range(0, MAX_RPC_EVENT_METADATA_COUNT)] 
     EvtRpcVariantList** eventMetadataInstances
 );

eventMetaDataEnum: A handle to an event metadata enumerator. 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. This is the value which comes from the return parameter eventMetaDataEnum of function EvtRpcGetEventMetadataEnum (as specified in 3.1.4.27).

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

numRequested: A 32-bit unsigned integer that contains the number of events for which the properties are needed.

numReturned: A pointer to a 32-bit unsigned integer that contains the number of events for which the properties are retrieved.

eventMetadataInstances: A pointer to an array of EvtRpcVariantList (section 2.2.9) structures.

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 that 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.<57> The server MUST return ERROR_INVALID_PARAMETER (0x00000057) if the handle is invalid.

The server MUST verify that event metadata entries remain in the publisher metadata that have not yet been enumerated. As specified in section 3.1.1.11, the event metadata context handle (eventsMetaDataEnum parameter) is an event metadata object in the server. The server SHOULD cast the context handle into the event metadata object. In the object, the Enumerator field tracks the delivered entries and remaining entries. If the enumeration has already returned the metadata for every event, the method SHOULD fail with the error ERROR_NO_DATA (0x000000E8).<58> Note that it is acceptable for a publisher to have no event metadata entries. In this case, the server MUST respond to the first call to EvtRpcGetNextEventMetadata with a return code of ERROR_SUCCESS (0x00000000) with numReturned set to zero. In particular, Windows event publishers that use the legacy protocol documented in [MS-EVEN] will not have event metadata associated with them. These include, but are not limited to, the events reported in the Application, System, and Security logs.

If the preceding checks succeed, the server MUST attempt to return the metadata for as many events as are specified in the numRequested, or until all the event metadata has been returned.

The server MUST fill an array of EvtRpcVariantList (section 2.2.9) objects, with an EvtRpcVariantList for each event's metadata, and assign the array to the eventMetadataInstances parameter. The server SHOULD only fail in creation of the array EvtRpcVariantList due to shortness of memory. In that case, the server SHOULD return ERROR_OUTOFMEMORY (0x000000E). Each EvtRpcVariantList MUST contain the following nine EvtVariant entries.

The preceding nine entries SHOULD be retrieved from the event information section in the publisher resource file (as specified in section 3.1.1.14).

If the preceding checks succeed and the server successfully creates the array of EvtRpcVariantList objects, the server MUST update the cursor value in the event metadata object to keep track of the event metadata that has already been enumerated. If the checks fail, or if the server is unable to create the array, the server MUST NOT update anything.

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