3.1.4.2.116 ApiOpenClusterEx (Opnum 117)

(Protocol Version 3) The ApiOpenClusterEx method SHOULD<78> 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.

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.

Show: