3.1.4.2.116 ApiOpenClusterEx (Opnum 117)

Article
04/06/2021

(Protocol Version 3) The ApiOpenClusterEx method SHOULD <96> establish context on the server about client interaction with the cluster by means of the current RPC connection. ApiOpenClusterEx returns a context handle so that the client can refer to the context that is created in subsequent method calls.

The server MUST determine the level of access to be granted to the client (section 3.1.4). Upon success, the server MUST associate that level of access with the cluster context it has established.

The server SHOULD accept an ApiOpenClusterEx request if its protocol server state is read-only and MUST accept the request for processing if it is in the read/write state, as specified in section 3.1.1.

 HCLUSTER_RPC ApiOpenClusterEx(
   [in] DWORD dwDesiredAccess,
   [out] DWORD * lpdwGrantedAccess,
   [out] error_status_t *Status
 );

dwDesiredAccess: Indicates the access level desired by the caller. The client SHOULD set dwDesiredAccess to the bitwise OR of one or more values in the following table (except for restrictions as noted in the table). The server SHOULD permit the cluster security descriptor to express permissions other than those specified in the following table. The server SHOULD perform an access check against those other permissions if requested by the client, except if the client sets dwDesiredAccess to a value that is invalid as specified in the following table. The server SHOULD NOT support a value for dwDesiredAccess that allows the client to request an access level of "Read with Backup Privilege".

Value	Meaning
CLUSAPI_READ_ACCESS 0x00000001	The client requests a context handle that can be used in subsequent method calls that require "Read" access.
CLUSAPI_CHANGE_ACCESS 0x00000002	The client requests a context handle that can be used in subsequent method calls that require "All" access. The server MUST return ERROR_INVALID_PARAMETER (0x00000057) if the dwDesiredAccess bitwise OR includes CLUSAPI_CHANGE_ACCESS but not CLUSAPI_READ_ACCESS.
GENERIC_READ 0x80000000	The server MUST treat this value the same as CLUSAPI_READ_ACCESS.
GENERIC-WRITE 0x40000000	The server MUST treat this value the same as the bitwise OR of CLUSAPI_READ_ACCESS and CLUSAPI_CHANGE_ACCESS.
GENERIC_EXECUTE 0x20000000	The server MUST treat this value the same as the bitwise OR of CLUSAPI_READ_ACCESS and CLUSAPI_CHANGE_ACCESS.
GENERIC_ALL 0x10000000	The server MUST treat this value the same as the bitwise OR of CLUSAPI_READ_ACCESS and CLUSAPI_CHANGE_ACCESS.
MAXIMUM_ALLOWED 0x02000000	The client requests a context handle that can be used in subsequent method calls that require the maximum access level granted to the client, as specified in section 3.1.4.

lpdwGrantedAccess: A pointer to a 32-bit value that indicates the access level granted to the client. If the method fails, the client MUST ignore this value. Upon successful completion of this method, the server MUST set this value to one of the values in the following table.

Value	Meaning
GENERIC_READ 0x80000000	The returned context handle can be used in subsequent methods that require "Read" access. If the client has backup privilege, the returned context handle can also be used in subsequent methods that require "Read with Backup Privilege" access.
GENERIC_ALL 0x10000000	The returned context handle can be used in subsequent methods that require "All" access.

Value

Meaning

GENERIC_READ

0x80000000

The returned context handle can be used in subsequent methods that require "Read" access. If the client has backup privilege, the returned context handle can also be used in subsequent methods that require "Read with Backup Privilege" access.

GENERIC_ALL

0x10000000

The returned context handle can be used in subsequent methods that require "All" access.

Status: Indicates the status of this operation. The server MUST set Status to the following error codes for the specified conditions.

Value	Meaning
ERROR_SUCCESS 0x00000000	Success.
ERROR_ACCESS_DENIED 0x00000005	dwDesiredAccess indicates a level of access exceeding what the client is entitled to (section 3.1.4).
ERROR_INVALID_PARAMETER 0x00000057	dwDesiredAccess is invalid, as specified earlier in this section.
RPC_S_PROCNUM_OUT_OF_RANGE 0x000006D1	The server does not support this method.

For any other condition, the server sets Status to a value that is not one of the values listed in the preceding table. The client MUST treat all values that are not listed in the preceding table the same, except as specified in section 3.2.4.6.

Return Values: The method MUST return a valid HCLUSTER_RPC (section 2.2.1.1) context handle to indicate success; otherwise, it MUST return NULL.

3.1.4.2.116 ApiOpenClusterEx (Opnum 117)

Additional resources