3.1.4.32 RGetServiceKeyNameA (Opnum 33)

  • Article

The RGetServiceKeyNameA method returns the ServiceName of the service record with the specified DisplayName.

 DWORD RGetServiceKeyNameA(
   [in] SC_RPC_HANDLE hSCManager,
   [in, string, range(0, SC_MAX_NAME_LENGTH)] 
     LPSTR lpDisplayName,
   [out, string, size_is(*lpcchBuffer)] 
     LPSTR lpKeyName,
   [in, out] LPBOUNDED_DWORD_4K lpcchBuffer
 );

hSCManager: An SC_RPC_HANDLE (section 2.2.4) data type that defines the handle to the SCM database created previously, using one of the open methods specified in section 3.1.4.

lpDisplayName: A pointer to a null-terminated ANSI string that specifies the service display name.

lpKeyName: A pointer to a buffer that receives the null-terminated ANSI string that contains the service name.

lpcchBuffer: An LPBOUNDED_DWORD_4K (section 2.2.7) data type that defines the pointer to a variable that specifies the size, in chars, of the buffer. On output, this variable receives the size of the service name, excluding the terminating null character.

Return Values: The method returns 0x00000000 (ERROR_SUCCESS) on success; otherwise, it returns one of the following error codes.

Return value/code

Description

122

ERROR_INSUFFICIENT_BUFFER

The data area passed to a system call is too small.

123

ERROR_INVALID_NAME

The name specified in lpDisplayName is invalid or set to NULL.

1060

ERROR_SERVICE_DOES_NOT_EXIST

The service record with the DisplayName matching the specified lpDisplayName does not exist in the SCM database identified by the hSCManager parameter.

In response to this request from the client, for a successful operation the server MUST look up the service record with DisplayName matching the display name specified by the lpDisplayName parameter in the SCM database identified by hSCManager.

The server MUST return the ServiceName from the found service record in the lpKeyName parameter and set the size in chars of the service name excluding the terminating null character in lpcchBuffer.

If the lpKeyName buffer is insufficient to hold the complete service name of the service, the server MUST fail the call with ERROR_INSUFFICIENT_BUFFER (122) and set the required size in chars of the service name excluding the terminating null character in lpcchBuffer.<50> If the size is sufficient for data returned, the server also returns the size that was set in lpcchBuffer.

If a service record is created with a Unicode-encoded display name using the RCreateServiceW method, then the server MUST convert the service name to an ANSI string before returning it. The conversion process is specified in [MS-UCODEREF] section 3.1.5.1.1.2, Pseudocode for Mapping a UTF-16 String to an ANSI Codepage.

The server MUST use the process described in Conversion Between ANSI and Unicode String Formats (section 3.1.7) to convert a string to the appropriate format.