GetServiceKeyNameA function (winsvc.h)

Article
02/09/2023

Retrieves the service name of the specified service.

Syntax

BOOL GetServiceKeyNameA(
  [in]            SC_HANDLE hSCManager,
  [in]            LPCSTR    lpDisplayName,
  [out, optional] LPSTR     lpServiceName,
  [in, out]       LPDWORD   lpcchBuffer
);

Parameters

[in] hSCManager

A handle to the computer's service control manager database, as returned by OpenSCManager.

[in] lpDisplayName

The service display name. This string has a maximum length of 256 characters.

[out, optional] lpServiceName

A pointer to a buffer that receives the service name. If the function fails, this buffer will contain an empty string.

The maximum size of this array is 4K bytes. To determine the required size, specify NULL for this parameter and 0 for the lpcchBuffer parameter. The function will fail and GetLastError will return ERROR_INSUFFICIENT_BUFFER. The lpcchBuffer parameter will receive the required size.

[in, out] lpcchBuffer

A pointer to variable that specifies the size of the buffer pointed to by the lpServiceName parameter, in TCHARs. When the function returns, this parameter contains the size of the service name, in TCHARs, excluding the null-terminating character.

If the buffer pointed to by lpServiceName is too small to contain the service name, the function stores no data in it. When the function returns, lpcchBuffer contains the size of the service name, excluding the NULL terminator.

Return value

If the functions succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

There are two names for a service: the service name and the display name. The service name is the name of the service's key in the registry. The display name is a user-friendly name that appears in the Services control panel application, and is used with the NET START command. Both names are specified with the CreateService function and can be modified with the ChangeServiceConfig function. Information specified for a service is stored in a key with the same name as the service name under the HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\ServiceName registry key.

To map the service name to the display name, use the GetServiceDisplayName function. To map the display name to the service name, use the GetServiceKeyName function.

Note

The winsvc.h header defines GetServiceKeyName as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	winsvc.h (include Windows.h)
Library	Advapi32.lib
DLL	Advapi32.dll