3.1.4.2.9 ApiOpenResource (Opnum 8)

msdn link

(Protocol Version 3) The ApiOpenResource method establishes context on the server about the interaction of a client with the specified cluster resource by using the current RPC connection. ApiOpenResource returns a context handle so that the client can refer to the resource in subsequent method call.

There are several ways in which the client can determine the name of the resource to specify for the lpszResourceName parameter. A resource can have a well-known name if the resource was configured as such by using implementation-specific methods between servers. Optionally, a client can use ApiCreateEnum with enumeration type CLUSTER_ENUM_RESOURCE, as specified in section 3.1.4.2.8. This method obtains a list of all resource names in the cluster state. The client can then examine names or open resources to call additional methods to determine which resources to operate on.

The server SHOULD accept an ApiOpenResource 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.

The server MUST require that the client have a security access level of "All" (section 3.1.4).

Upon success, the server MUST associate a security access level of "All" with the context it has established.

 HRES_RPC ApiOpenResource(
   [in, string] LPCWSTR lpszResourceName,
   [out] error_status_t *Status,
   [out] error_status_t *rpc_status
 );

lpszResourceName: A Unicode string that contains the name of the resource for which to establish context on the server. The server MUST also accept the resource unique ID as returned by the ApiGetResourceId method.

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

0x0000000

Success.

ERROR_RESOURCE_NOT_FOUND

0x0000138f

A resource that matches name lpszResourceName was not found in the cluster configuration.

For any other condition, the server MUST set 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.

rpc_status: A 32-bit integer used to indicate success or failure. The RPC runtime MUST indicate, by writing to this parameter, whether it succeeded in executing this method on the server. The encoding of the value passed in this parameter MUST conform to encoding for  comm_status and fault_status, as specified in Appendix E of [C706].

Return Values: The method MUST return a valid HRES_RPC context handle, as specified in section 2.2.1.4, to indicate success; otherwise, it MUST return NULL.