OpenServiceA function (winsvc.h)

Opens an existing service.

Syntax

SC_HANDLE OpenServiceA(
  [in] SC_HANDLE hSCManager,
  [in] LPCSTR    lpServiceName,
  [in] DWORD     dwDesiredAccess
);

Parameters

[in] hSCManager

A handle to the service control manager database. The OpenSCManager function returns this handle. For more information, see Service Security and Access Rights.

[in] lpServiceName

The name of the service to be opened. This is the name specified by the lpServiceName parameter of the CreateService function when the service object was created, not the service display name that is shown by user interface applications to identify the service.

The maximum string length is 256 characters. The service control manager database preserves the case of the characters, but service name comparisons are always case insensitive. Forward-slash (/) and backslash (\) are invalid service name characters.

[in] dwDesiredAccess

The access to the service. For a list of access rights, see Service Security and Access Rights.

Before granting the requested access, the system checks the access token of the calling process against the discretionary access-control list of the security descriptor associated with the service object.

Return value

If the function succeeds, the return value is a handle to the service.

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

The following error codes can be set by the service control manager. Others can be set by the registry functions that are called by the service control manager.

Return code Description
ERROR_ACCESS_DENIED
The handle does not have access to the service.
ERROR_INVALID_HANDLE
The specified handle is invalid.
ERROR_INVALID_NAME
The specified service name is invalid.
ERROR_SERVICE_DOES_NOT_EXIST
The specified service does not exist.

Remarks

The returned handle is only valid for the process that called OpenService. It can be closed by calling the CloseServiceHandle function.

To use OpenService, no privileges are required aside from SC_MANAGER_CONNECT.

Examples

For an example, see Starting a Service.

Note

The winsvc.h header defines OpenService as an alias that 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 is 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

See also

ChangeServiceConfig

CloseServiceHandle

ControlService

CreateService

DeleteService

EnumDependentServices

OpenSCManager

QueryServiceConfig

QueryServiceDynamicInformation

QueryServiceObjectSecurity

QueryServiceStatusEx

SCM Handles

Service Functions

SetServiceObjectSecurity

StartService