3.1.4.15 ROpenSCManagerW (Opnum 15)

  • Article

The ROpenSCManagerW method establishes a connection to server and opens the SCM database on the specified server.

 DWORD ROpenSCManagerW(
   [in, string, unique, range(0, SC_MAX_COMPUTER_NAME_LENGTH)] 
     SVCCTL_HANDLEW lpMachineName,
   [in, string, unique, range(0, SC_MAX_NAME_LENGTH)] 
     wchar_t* lpDatabaseName,
   [in] DWORD dwDesiredAccess,
   [out] LPSC_RPC_HANDLE lpScHandle
 );

lpMachineName: An SVCCTL_HANDLEW (section 2.2.3) data type that defines the pointer to a null-terminated UNICODE string that specifies the server's machine name.

lpDatabaseName: A pointer to a null-terminated UNICODE string that specifies the name of the SCM database to open. The parameter MUST be set to NULL, "ServicesActive", or "ServicesFailed".

dwDesiredAccess: A value that specifies the access to the database. This MUST be one of the values as specified in section 3.1.4.

The client MUST also have the SC_MANAGER_CONNECT access right.

lpScHandle: An LPSC_RPC_HANDLE data type that defines the handle to the newly opened SCM database.

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

Return value/code

Description

5

ERROR_ACCESS_DENIED

The client does not have the required access rights to open the SCM database on the server or the desired access is not granted to it in the SCM SecurityDescriptor.

123

ERROR_INVALID_NAME

The specified service name is invalid.

1065

ERROR_DATABASE_DOES_NOT_EXIST

The database specified does not exist.

1115

ERROR_SHUTDOWN_IN_PROGRESS

The system is shutting down.

In response to this request from the client, for a successful operation the server MUST create an RPC context handle to the SCM database and grant subsequent access specified in the dwDesiredAccess parameter of the client request to clients using this handle after evaluating the client security context against SCM SecurityDescriptor. The server MUST return this handle by setting the lpScHandle parameter of the client request.

If the caller cannot be granted permission requested in the dwDesiredAccess parameter, the server MUST fail the call.<40>

The server MUST return ERROR_INVALID_NAME (123) if lpDatabaseName is not NULL and not ServicesActive or ServicesFailed.

The server MUST return ERROR_DATABASE_DOES_NOT_EXIST (1065) if lpDatabaseName is ServicesFailed.