3.1.4.31 RGetServiceDisplayNameA (Opnum 32)

  • Article

The RGetServiceDisplayNameA method returns the display name of the specified service.

 DWORD RGetServiceDisplayNameA(
   [in] SC_RPC_HANDLE hSCManager,
   [in, string, range(0, SC_MAX_NAME_LENGTH)] 
     LPSTR lpServiceName,
   [out, string, size_is(*lpcchBuffer)] 
     LPSTR lpDisplayName,
   [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.

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

The forward slash, back slash, comma, and space characters are illegal in service names.

lpDisplayName: A pointer to a buffer that receives the null-terminated ANSI string that contains the service display 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's display 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 display name does not fit in the buffer.

123

ERROR_INVALID_NAME

The specified service name is invalid.

1060

ERROR_SERVICE_DOES_NOT_EXIST

The service record with the specified ServiceName 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 the ServiceName matching the specified lpServiceName in the SCM database identified by the hSCManager parameter. The server MUST return the DisplayName from the found service record in the lpDisplayName parameter and set the size in chars of the display name excluding the terminating null character in lpcchBuffer.

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

If a service is created with a Unicode-encoded display name using the RCreateServiceW method, then the server MUST convert the display 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.