Export (0) Print
Expand All
Expand Minimize

3.1.4.2.121 ApiOpenNetInterfaceEx (Opnum 122)

(Protocol Version 3) The ApiOpenNetInterfaceEx method establishes context on the server about the interaction of a client with the specified cluster network interface by using the current RPC connection. ApiOpenNetInterfaceEx 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 node context it has established.

Servers SHOULD<91> support this method.

There are several ways by which the client can determine the name of the cluster network interface to specify for the lpszNetInterfaceName parameter. A cluster network interface can have a well-known name if the cluster network interface was configured as such by using implementation-specific methods between servers. Optionally, a client can use ApiCreateEnum with enumeration type CLUSTER_ENUM_NETINTERFACE, as specified in section 3.1.4.2.8. This method obtains a list of all cluster network interface names in the cluster state. The client then can examine names or open cluster network interfaces to call additional methods to determine which cluster network interfaces to operate on. Finally, a client supplying the name of the node and network to the ApiGetNetInterface method, will get back the corresponding cluster network interface object name for that combination, which then can be provided to this method.

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

HNETINTERFACE_RPC ApiOpenNetInterfaceEx(
  [in, string] LPCWSTR lpszNetInterfaceName,
  [in] DWORD dwDesiredAccess,
  [out] DWORD* lpdwGrantedAccess,
  [out] error_status_t* Status,
  [out] error_status_t* rpc_status
);

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

dwDesiredAccess: The value for this parameter is the same as specified for dwDesiredAccess in ApiOpenClusterEx.

lpdwGrantedAccess: The value for this parameter is the same as specified for lpdwGrantedAccess in ApiOpenClusterEx.

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.

ERROR_CLUSTER_NETINTERFACE_NOT_FOUND
0x000013b7

A cluster network interface that matches the name lpszNetInterfaceName 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 HNETINTERFACE_RPC (section 2.2.1.8) context handle to indicate success; otherwise, it MUST return NULL.

 
Show:
© 2015 Microsoft