Share via

3.1.4.27 ROpenServiceA (Opnum 28)

  • Article

The ROpenServiceA method creates an RPC context handle to an existing service record.

 DWORD ROpenServiceA(
   [in] SC_RPC_HANDLE hSCManager,
   [in, string, range(0, SC_MAX_NAME_LENGTH)] 
     LPSTR lpServiceName,
   [in] DWORD dwDesiredAccess,
   [out] LPSC_RPC_HANDLE lpServiceHandle
 );

hSCManager: An SC_RPC_HANDLE (section 2.2.4) data type that defines the handle to the SCM database, created using one of the open methods specified in section 3.1.4.

lpServiceName: A pointer to a null-terminated ANSI string that specifies the ServiceName of the service record to open.

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

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

lpServiceHandle: An LPSC_RPC_HANDLE (section 2.2.4) data type that defines the handle to the found service record.

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 access specified by the dwDesiredAccess parameter cannot be granted to the caller.

6

ERROR_INVALID_HANDLE

The handle is no longer valid.

123

ERROR_INVALID_NAME

The specified service name is invalid.

1060

ERROR_SERVICE_DOES_NOT_EXIST

The service record with a specified DisplayName does not exist in the SCM database.

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 service record identified by the lpServiceName parameter in the SCM database specified by the hSCManager parameter of the client request after evaluating the SecurityDescriptor found in the service record against the caller's security context for the requested access. The server MUST increment the HandleCount field of the service record and return this handle by setting the lpScHandle parameter.

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.