3.1.4.1.98 ApiNetInterfaceControl (Opnum 98)

(Protocol Version 2) The ApiNetInterfaceControl method instructs the server to initiate, on the specified cluster network interface, an operation that is defined by the specified control code. The operation is executed on the node where the specified cluster network interface context handle was obtained.

 error_status_t ApiNetInterfaceControl(
   [in] HNETINTERFACE_RPC hNetInterface,
   [in] DWORD dwControlCode,
   [in, unique, size_is(nInBufferSize)] UCHAR *lpInBuffer,
   [in] DWORD nInBufferSize,
   [out, size_is(nOutBufferSize), 
     length_is (*lpBytesReturned)] UCHAR *lpOutBuffer,
   [in] DWORD nOutBufferSize,
   [out] DWORD *lpBytesReturned,
   [out] DWORD *lpcbRequired
 );

hNetInterface: An HNETINTERFACE_RPC context handle that is obtained in a previous ApiOpenNetInterface method call.

dwControlCode: Indicates the operation to perform on the cluster network interface. It MUST be one of the following values.

Value

Meaning

CLUSCTL_NETINTERFACE_UNKNOWN

0x6000000

Verifies that control codes for the cluster network interface are being processed.

CLUSCTL_NETINTERFACE_GET_CHARACTERISTICS

0x6000005

Retrieves the intrinsic characteristics associated with the cluster network interface.

CLUSCTL_NETINTERFACE_GET_FLAGS

0x6000009

Retrieves the flags that are set for the cluster network interface.

CLUSCTL_NETINTERFACE_GET_NAME

0x6000029

Retrieves the name of the cluster network interface.

CLUSCTL_NETINTERFACE_GET_NODE

0x6000031

Retrieves the name of the node on the cluster network interface is installed.

CLUSCTL_NETINTERFACE_GET_NETWORK

0x6000035

Retrieves the name of the cluster network to which the cluster network interface is connected.

CLUSCTL_NETINTERFACE_GET_ID

0x6000039

Retrieves the unique ID for the cluster network interface.

CLUSCTL_NETINTERFACE_ENUM_COMMON_PROPERTIES

0x6000051

Retrieves a list of the common property names for the designated cluster network interface.

CLUSCTL_NETINTERFACE_GET_RO_COMMON_PROPERTIES

0x6000055

Retrieves the read-only common property values for the designated cluster network interface.

CLUSCTL_NETINTERFACE_GET_COMMON_PROPERTIES

0x6000059

Retrieves all common property values for the designated cluster network interface.

CLUSCTL_NETINTERFACE_SET_COMMON_PROPERTIES

0x640005E

Sets the common property values for the designated cluster network interface.

CLUSCTL_NETINTERFACE_VALIDATE_COMMON_PROPERTIES

0x6000061

Validates that the values supplied for the common properties are acceptable for the designated cluster network interface.

CLUSCTL_NETINTERFACE_ENUM_PRIVATE_PROPERTIES

0x6000079

Retrieves a list of the private property names for the designated cluster network interface.

CLUSCTL_NETINTERFACE_GET_RO_PRIVATE_PROPERTIES

0x600007D

Retrieves the read-only private property names for the designated cluster network interface.

CLUSCTL_NETINTERFACE_GET_PRIVATE_PROPERTIES

0x6000081

Retrieves all private property values for the designated cluster network interface.

CLUSCTL_NETINTERFACE_SET_PRIVATE_PROPERTIES

0x6400086

Sets the private property values for the designated cluster network interface.

CLUSCTL_NETINTERFACE_VALIDATE_PRIVATE_PROPERTIES

0x6000089

Validates that the supplied property list is valid.

lpInBuffer: The input data for the operation that is specified by dwControlCode. See the following sections for the data structures that are required for each dwControlCode.

nInBufferSize: The size, in bytes, of the buffer that is specified by lpInBuffer.

lpOutBuffer: The output data for the operation that is specified by dwControlCode. The output buffer MUST be allocated and provided by the client.

nOutBufferSize: The available size of the buffer that is specified by lpOutBuffer, as allocated by the client.

lpBytesReturned: On successful completion of the method, the server MUST set lpBytesReturned to the number of bytes that are written to the lpOutBuffer buffer.

lpcbRequired: If nOutBufferSize indicates that the buffer that is specified by lpOutBuffer is too small for the output data, the server MUST return 0x000000EA (ERROR_MORE_DATA) and set lpcbRequired to the number of bytes that are required for the output buffer. If the method completes successfully and lpBytesReturned is 0x00000000 then the server MUST set lpcbRequired to 0x00000000. In any other condition the client MUST ignore lpcbRequired after this method completes.

Return Values: The method MUST return the following error codes for the specified conditions.

Return value/code

Description

0x00000000

ERROR_SUCCESS

Success.

0x00000001

ERROR_INVALID_FUNCTION

The cluster network interface that is designated by hNetInterface does not support the operation that is designated by dwControlCode.

0x0000000D

ERROR_INVALID_DATA

The input data was invalid or was incorrectly formatted.

0x00000057

ERROR_INVALID_PARAMETER

The input data was invalid or was incorrectly formatted.

0x000000EA

ERROR_MORE_DATA

The nOutBufferSize parameter indicates that the buffer that is pointed to by lpOutBuffer is not large enough to hold the data that resulted from the operation.

For any other condition, this method MUST return a value that is not one of the values listed in the preceding table. The client MUST behave in one consistent, identical manner for all values that are not listed in the preceding table. The client SHOULD treat errors specified in section 3.2.4.6 as recoverable errors and initiate the reconnect procedure as specified in section 3.2.4.6.

Upon receiving this message, the server MUST:

  • Determine the number of bytes that are required for lpOutBuffer. If the size indicated by nOutBufferSize is less than the number of bytes that are required for lpOutBuffer, return ERROR_MORE_DATA (0x000000EA), except as specified in the following sub-sections where a different value is returned, and set lpcbRequired to the number of bytes that are required for the output buffer.

  • Return either ERROR_INVALID_DATA or ERROR_INVALID_PARAMETER if the input data is invalid or incorrectly formatted. The client MUST treat these two error codes the same.