3.1.4.25 EvtRpcGetPublisherMetadata (Opnum 24)

The EvtRpcGetPublisherMetadata (Opnum 24) method is used by a client to open a handle to publisher metadata. It also gets some initial information from the metadata.

 error_status_t EvtRpcGetPublisherMetadata(
   /* [in] RPC_BINDING_HANDLE binding, {the binding handle will be generated by MIDL} */
   [in, unique, range(0, MAX_RPC_PUBLISHER_ID_LENGTH), string] 
     LPCWSTR publisherId,
   [in, unique, range(0, MAX_RPC_FILE_PATH_LENGTH), string] 
     LPCWSTR logFilePath,
   [in] LCID locale,
   [in] DWORD flags,
   [out] EvtRpcVariantList* pubMetadataProps,
   [out, context_handle] PCONTEXT_HANDLE_PUBLISHER_METADATA* pubMetadata
 );

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

publisherId: A pointer to a string that contains the publisher for which information is needed.

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

locale: A Locale value, as specified in [MS-GPSI]. This is used later if the pubMetadata handle is used for rendering.

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

pubMetadataProps: A pointer to an EvtRpcVariantList (section 2.2.9) structure containing publisher properties.

pubMetadata: A pointer to a publisher handle. 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.

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 verify that the publisherID parameter specifies either a publisher name or NULL. The server MUST fail the method if the publisherID is non-NULL and is not the name of a publisher with the error code ERROR_INVALID_PARAMETER (0x00000057). The server SHOULD check whether the non-NULL publisherID is in the publisher table to verify whether the publisherID is a publisher name. If the publisherID parameter is NULL, the server MUST use the default publisher (as specified in section 3.1.1.14).

Next, the server MUST verify that the caller has read access to the information and MUST fail the method with the error ERROR_ACCESS_DENIED (0x00000005) 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 the server MAY get the security descriptor of the publisher table. The server MAY assign a security descriptor when the publisher is registered in its publisher table or if the publisher entry is built on the server's file system, it can get its security descriptor from the file system.<49> Next, the server SHOULD be able to perform the read access check using the Access Check algorithm (as specified in [MS-DTYP] section 2.5.3.2).

If the previous checks succeed, the server MUST attempt to create a CONTEXT_HANDLE_PUBLISHER_METADATA for the publisher. As specified in section 3.1.1.11, the server SHOULD create a publisher metadata object and then cast it to the context and assign the handle to the pubMetadata parameter. The server SHOULD add the newly created handle to its handle table in order to track it. The server SHOULD only fail the creation of handles in the case of inadequate memory and return ERROR_OUTOFMEMORY (0x0000000E). The server MUST store the locale value in the publisher metadata object.

The server MUST fill an EvtRpcVariantList (for more information, see section 2.2.9) that contains 29 EvtRpcVariants and save them in the pubMetadataProps parameter. As noted in the pubMetadataProps description, not all of the EvtRpcVariant entries are actually used, and all unused ones MUST be set to type EvtRpcVarTypeNULL. The following table lists those entries that are used.

Index	Type	Description
0	EvtVarTypeGuid	PublisherGuid: This is the identifier of the publisher which is mentioned in section 3.1.1.2.
1	EvtVarTypeString	ResourceFilePath: This is the publisher resource file path which is specified in section 3.1.1.14.
2	EvtVarTypeString	ParameterFilePath: This is the publisher parameter file which is specified in section 3.1.1.14.
3	EvtVarTypeString	MessageFilePath: This is the publisher message file which is specified in section 3.1.1.14.
7	EvtVarTypeStringArray	ChannelReferencePath: This is the array of the channel paths into which the publisher generates events.
8	EvtVarTypeUInt32Array	ChannelReferenceIndex: The channel start index values, as specified in section 3.1.1.2.
9	EvtVarTypeUInt32Array	ChannelReferenceID: The channel reference ID values, as specified in section 3.1.1.2.
10	EvtVarTypeUInt32Array	ChannelReferenceFlags: The channel reference flags, as specified in section 3.1.1.2.
11	EvtVarTypeUInt32Array	ChannelReferenceMessageID: This is the message Ids for the channels.

As specified earlier in this section, the server SHOULD find the publisher entry in its publisher table based on the specified publisherId parameter from the client. Once the server locates the publisher entry, the server SHOULD get the publisherGUID, ResourceFilePath, ParameterFilePath, MessageFilePath, ChannelReferenceIndex, ChannelReferenceID and ChannelReferenceFlags directly from the publisher table entry (as specified in sections 3.1.1.3 for publisher tables and 3.1.1.2 for publishers). Then the server SHOULD open the publisher resource file and locate the channel information in the resource file (as specified in section 3.1.1.14). Next, the server reads the channel name strings and channel message IDs, returning them as the result for the ChannelReferencePath and ChannelReferenceMessageID. See section 4.12 for an example EvtRpcVariantList containing all 29 EvtRpcVariants.

If the server can't allocate enough memory for the returning parameter pubMetadataProps, it SHOULD return the error ERROR_OUTOFMEMORY (0x0000000E).

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

If the server can't find the corresponding information from the publisher resource, the server SHOULD set the entry to EvtRpcVarTypeNULL to indicate some of the values are not retrieved, but SHOULD still proceed with the other eleven data fields without returning any error. Even if all of the eleven fields are all not found, the server SHOULD still return ERROR_SUCCESS (0x00000000).