Share via

3.1.4.1.81 ApiOpenNetwork (Opnum 81)

  • Article

(Protocol Version 2) The ApiOpenNetwork method establishes context on the server about the interaction of a client with the specified cluster network by using the current RPC connection. ApiOpenNetwork returns a context handle so that the client can refer to the context that is created in subsequent method calls.

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

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

 HNETWORK_RPC ApiOpenNetwork(
   [in, string] LPCWSTR lpszNetworkName,
   [out] error_status_t *Status
 );

lpszNetworkName: A null-terminated Unicode string that contains the name of the cluster network for which to establish context on the cluster network.

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

Value

Meaning

ERROR_SUCCESS

0x00000000

Success.

ERROR_CLUSTER_NETWORK_NOT_FOUND

0x000013B5

A cluster network that matches the name lpszNetworkName was not found in the cluster configuration.

Return Values: 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.

The method MUST return a valid HNETWORK_RPC context handle, as specified in section 2.2.1.7, to indicate success; otherwise, it MUST return NULL.