3.1.4.26 ROpenSCManagerA (Opnum 27)

  • Article

The ROpenSCManagerA method opens a connection to the SCM from the client and then opens the specified SCM database.

 DWORD ROpenSCManagerA(
   [in, string, unique, range(0, SC_MAX_COMPUTER_NAME_LENGTH)] 
     SVCCTL_HANDLEA lpMachineName,
   [in, string, unique, range(0, SC_MAX_NAME_LENGTH)] 
     LPSTR lpDatabaseName,
   [in] DWORD dwDesiredAccess,
   [out] LPSC_RPC_HANDLE lpScHandle
 );

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

lpDatabaseName: A pointer to a null-terminated ANSI 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 specified in section 3.1.4.

The client MUST also have the SC_MANAGER_CONNECT access right.

lpScHandle: An LPSC_RPC_HANDLE (section 2.2.4) data type that defines the handle to the newly opened SCM connection.

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 SC_MANAGER_CONNECT access right or the desired access is not granted to the caller 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 after evaluating the client security context against the 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.<45>

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.

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

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