3.1.4.36 EvtRpcGetClassicLogDisplayName (Opnum 28)

  • Article

The EvtRpcGetClassicLogDisplayName (Opnum 28) method obtains a descriptive name for a channel.

 error_status_t EvtRpcGetClassicLogDisplayName(
   /* [in] RPC_BINDING_HANDLE binding, {the binding handle will be generated by MIDL} */
   [in, range(1, MAX_RPC_CHANNEL_NAME_LENGTH), string] 
     LPCWSTR logName,
   [in] LCID locale,
   [in] DWORD flags,
   [out] LPWSTR* displayName
 );

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

logName: The channel name for which the descriptive name is needed.

locale: The locale, as specified in [MS-GPSI] Appendix A, to be used for localizing the log.

flags: A 32-bit unsigned integer that MUST be set to one of the following values:

Value

Meaning

0x0

If a locale is specified, that locale will be used and no fallback locale will be attempted if the locale is not present.

0x100

If set, instructs the server to pick the best locale, if the locale specified by the locale parameter is not present. Please see the following processing rules for more information on how the server picks the best locale.

displayName: Returned display name.

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, for a successful operation, the server MUST attempt to retrieve a display name for a channel. In [MS-EVEN] section 3.1.1.2, there are two configuration entries for a classic event log: DisplayNameFile and DisplayNameID. The server tries to use the log name passed here to find the log entry in the registry and then locate the DisplayNameID and DisplayNameFile. The DisplayNameID is the message ID for the display name. The file which is pointed at by DisplayNameFile contains the localized string for the display name. The server uses the messageId and locale as the combination key to look for the string inside the file and then retrieve the classic event log display name. The server verifies that the channel name, as specified by the logName parameter, is a known classic event log. If the logName parameter does not specify a registered event log (the log name can't be located in the registry described in [MS-EVEN]), the server MUST fail the method with the error ERROR_NOT_FOUND (0x00000490). If the server can't find the DisplayNameID or the DisplayNameFile, the server SHOULD fail the method with the error ERROR_INVALID_DATA (0x0000000D).

If the locale is not specified (that is, the caller passes zero for the locale parameter) and the flags parameter is 0x0, the server MUST substitute the locale of its own execution thread as the value of the locale parameter.

If the display name is not present in the specified locale as specified above and the flags parameter is set to 0x100, the server makes a best effort attempt to find a localized display name string by following these steps:

  1. The server SHOULD attempt to find a fallback locale with the same base language which does contain the localized display name.<68> For example, if the caller requested the U.S. English "en-US" locale but the display name was only available in another "en" prefixed locale such as the British English "en-GB" locale, the server would return the British English version of the display name.

  2. Using the fallback locale, the server SHOULD attempt to find a localized display name string by searching the appropriate DisplayNameFile in the same manner as specified above.

  3. If the server cannot determine an appropriate fallback locale or cannot find a localized display name string using the fallback locale, the server MUST return ERROR_NOT_FOUND (0x00000490).

The server SHOULD validate the flags to ensure that no flags are present other than 0x0 and 0x100.<69>

Otherwise, the server MUST fail the method with the error ERROR_INVALID_PARAMETER (0x00000057).

This API only succeeds if called for a log name that is exposed by the obsolete Eventlog Remote protocol. If called on logs that are not exposed by the obsolete Eventlog Remote protocol, the method will fail with the error ERROR_NOT_FOUND (0x00000490). For more information, see section 3.1.1.6.

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