3.1.4.5 RQueryServiceObjectSecurity (Opnum 4)

  • Article

The RQueryServiceObjectSecurity method returns a copy of the SECURITY_DESCRIPTOR structure associated with a service object.

 DWORD RQueryServiceObjectSecurity(
   [in] SC_RPC_HANDLE hService,
   [in] SECURITY_INFORMATION dwSecurityInformation,
   [out, size_is(cbBufSize)] LPBYTE lpSecurityDescriptor,
   [in, range(0, 1024*256)] DWORD cbBufSize,
   [out] LPBOUNDED_DWORD_256K pcbBytesNeeded
 );

hService: An SC_RPC_HANDLE (section 2.2.4) data type that defines the handle to a service record or to the SCM database that MUST have been created previously using one of the open methods specified in section 3.1.4.

dwSecurityInformation: A SECURITY_INFORMATION (section 2.2.1) type definition that specifies the security information being requested.

lpSecurityDescriptor: A pointer to a buffer that contains a copy of the SECURITY_DESCRIPTOR structure (as specified in [MS-DTYP] section 2.4.6) for the specified service object.

cbBufSize: Size, in bytes, of the buffer to which the lpSecurityDescriptor parameter points.

pcbBytesNeeded: An LPBOUNDED_DWORD_256K (section 2.2.9) pointer to a variable that contains the number of bytes needed to return all the requested SECURITY_DESCRIPTOR information if the method fails.

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 required access rights had not been granted to the caller when the RPC context handle was created.

6

ERROR_INVALID_HANDLE

The handle is no longer valid.

87

ERROR_INVALID_PARAMETER

A parameter that was specified is invalid.

122

ERROR_INSUFFICIENT_BUFFER

The data area passed to a system call is too small.

The client MAY provide a combination of one or more SECURITY_INFORMATION bit flags for dwSecurityInformation.

If SACL_SECURITY_INFORMATION is specified for the dwSecurityInformation parameter, then an ACCESS_SYSTEM_SECURITY right MUST have been granted to the caller when hService was created. (See AS in ACCESS_MASK in [MS-DTYP] 2.4.3.)

If DACL_SECURITY_INFORMATION, LABEL_SECURITY_INFORMATION, OWNER_SECURITY_INFORMATION, or GROUP_SECURITY_INFORMATION is specified for the dwSecurityInformation parameter, then a READ_CONTROL right MUST have been granted to the caller when hService was created. (See RC in ACCESS_MASK in [MS-DTYP] 2.4.3.)

In response to this request from the client, for a successful operation the server MUST return a copy of the SECURITY_DESCRIPTOR structure containing requested information obtained from the SecurityDescriptor for the service record or the SCM database identified by the hService.

The server MUST return SECURITY_DESCRIPTOR in the buffer pointed to by the lpSecurityDescriptor parameter. The information returned depends on the values requested by the client in the dwSecurityInformation parameter.

The server MUST set the required buffer size, in bytes, in the pcbBytesNeeded parameter. If the buffer pointed to by lpSecurityDescriptor is insufficient to hold all the configuration data, the server MUST fail the call with ERROR_INSUFFICIENT_BUFFER (122).

The server MUST return ERROR_INVALID_PARAMETER (87) if dwSecurityInformation contains bits not defined for SECURITY_INFORMATION (section 2.2.1).