3.1.4.2.76 ApiResourceTypeControl (Opnum 75)

Article
04/27/2022

(Protocol Version 3) The ApiResourceTypeControl method instructs the server to initiate, on the specified resource type, an operation that is defined by the specified control code. The operation is executed on the node where the specified cluster context handle was obtained.

The server MUST require that the access level associated with the hCluster context handle is "All" (section 3.1.4), if and only if the bitwise AND of dwControlCode and 0x00400000 is not equal to zero, except as otherwise specified for particular control codes in the following subsections.

 error_status_t ApiResourceTypeControl(
   [in] HCLUSTER_RPC hCluster,
   [in, string] LPCWSTR lpszResourceTypeName,
   [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,
   [out] error_status_t *rpc_status
 );

hCluster: An HCLUSTER_RPC context handle that is obtained in a previous ApiOpenCluster or ApiOpenClusterEx method call.

lpszResourceTypeName: A Unicode string that is the name of the type of resource that will execute this operation.

dwControlCode: Indicates the operation to perform on the resource type. MUST be one of the following values.

Value	Meaning
CLUSCTL_RESOURCE_TYPE_UNKNOWN 0x02000000	Verifies that control codes for the resource type are being processed.
CLUSCTL_RESOURCE_TYPE_GET_CHARACTERISTICS 0x02000005	Retrieves the intrinsic characteristics associated with the resource type.
CLUSCTL_RESOURCE_TYPE_GET_FLAGS 0x02000009	Retrieves the flags that are set for the resource type.
CLUSCTL_RESOURCE_TYPE_GET_CLASS_INFO 0x0200000D	Retrieves info about the class to which the resource type belongs.
CLUSCTL_RESOURCE_TYPE_GET_REQUIRED_DEPENDENCIES 0x02000011	Retrieves a list of the names of resource types on which an instance of this resource type MUST be dependent on in order to properly operate.
CLUSCTL_RESOURCE_TYPE_GET_ARB_TIMEOUT 0x02000015	Queries the arbitration time-out value for the designated storage class resource.
CLUSCTL_RESOURCE_TYPE_ENUM_COMMON_PROPERTIES 0x02000051	Retrieves a list of the common property names for the designated resource type.
CLUSCTL_RESOURCE_TYPE_GET_RO_COMMON_PROPERTIES 0x02000055	Retrieves the read-only common property values for the designated resource type.
CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTIES 0x02000059	Retrieves all common property values for the designated resource type.
CLUSCTL_RESOURCE_TYPE_SET_COMMON_PROPERTIES 0x0240005E	Sets the common property values for the designated resource type.
CLUSCTL_RESOURCE_TYPE_VALIDATE_COMMON_PROPERTIES 0x02000061	Validates that the values supplied for the common properties are acceptable for the designated resource type.
CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTY_FMTS 0x02000065	Retrieves a list of the common property formats for the designated resource type.
CLUSCTL_RESOURCE_TYPE_GET_COMMON_RESOURCE_PROPERTY_FMTS 0x02000069	Retrieves a list of the common property formats for resource instances of the designated resource type.
CLUSCTL_RESOURCE_TYPE_ENUM_PRIVATE_PROPERTIES 0x02000079	Retrieves a list of the private property names for the designated resource type.
CLUSCTL_RESOURCE_TYPE_GET_RO_PRIVATE_PROPERTIES 0x0200007D	Retrieves the read-only private property values for the designated resource type.
CLUSCTL_RESOURCE_TYPE_GET_PRIVATE_PROPERTIES 0x02000081	Retrieves all private property values for the designated resource type.
CLUSCTL_RESOURCE_TYPE_SET_PRIVATE_PROPERTIES 0x02400086	Sets the private property values for the designated resource type.
CLUSCTL_RESOURCE_TYPE_VALIDATE_PRIVATE_PROPERTIES 0x02000089	Validates that the values supplied for the private properties are acceptable for the designated resource type.
CLUSCTL_RESOURCE_TYPE_GET_PRIVATE_PROPERTY_FMTS 0x0200008D	Retrieves a list of the private property formats for the designated resource type.
CLUSCTL_RESOURCE_TYPE_GET_PRIVATE_RESOURCE_PROPERTY_FMTS 0x02000091	Retrieves a list of the private property formats for resource instances of the designated resource type.
CLUSCTL_RESOURCE_TYPE_STORAGE_GET_AVAILABLE_DISKS 0x02000195	Queries information on the designated node about disks that can be placed under cluster control.
CLUSCTL_RESOURCE_TYPE_NETNAME_VALIDATE_NETNAME 0x02000235	Confirms that the name is valid as an alternate connection point for the cluster.
CLUSCTL_RESOURCE_TYPE_VALIDATE_PATH 0x02000231	Confirms that for resources of type "Generic Application", the server can access the file using the supplied path.
CLUSCTL_RESOURCE_TYPE_GEN_APP_VALIDATE_DIRECTORY 0x02000239	Confirms that, for resources of type "Generic Application", the supplied directory exists.
CLUSCTL_RESOURCE_TYPE_STORAGE_GET_DRIVELETTERS 0x020001ED	Queries a bitmask of the drive letters that are in use on the designated node.
CLUSCTL_RESOURCE_TYPE_STORAGE_GET_AVAILABLE_DISKS_EX 0x020001F5	Queries information on the designated node about disks that can be placed under cluster control.
CLUSCTL_RESOURCE_TYPE_STORAGE_REMAP_DRIVELETTER 0x02000201	Modifies the drive letter of a disk on the designated node.
CLUSCTL_RESOURCE_TYPE_STORAGE_GET_DISKID 0x02000205	Queries the ID of a disk on the designated node.
CLUSCTL_RESOURCE_TYPE_STORAGE_IS_CLUSTERABLE 0x02000209	Confirms whether a disk on the designated node can be placed under cluster control.
CLUSCTL_RESOURCE_TYPE_STORAGE_RELEASE_OWNERSHIP 0x0240020E	Releases control of a disk on the designated node.
CLUSCTL_RESOURCE_TYPE_STORAGE_IS_CSV_FILE 0x1000229	Queries whether a file is stored on a cluster shared volume.
CLUSCTL_CLOUD_WITNESS_RESOURCE_TYPE_VALIDATE_CREDENTIALS 0x020020e1	Validates that the server can successfully access the witness using the supplied credentials.
CLUSCTL_RESOURCE_TYPE_REPLICATION_GET_ELIGIBLE_LOGDISKS 0x02002149	Retrieves the eligible storage replication log disks for a given source or target disk.
CLUSCTL_RESOURCE_TYPE_REPLICATION_GET_ELIGIBLE_TARGET_DATADISKS 0x0200214D	Retrieves the eligible storage replication target disks for a given source disk.
CLUSCTL_RESOURCE_TYPE_REPLICATION_GET_ELIGIBLE_SOURCE_DATADISKS 0x02002151	Retrieves the eligible storage replication data disks that can be aggregated into the same replication group as a given source disk.
CLUSCTL_RESOURCE_TYPE_REPLICATION_GET_REPLICA_VOLUMES 0x02002159	Retrieves the volumes on a given source disk and a given target disk that can be paired for storage replication.
CLUSCTL_RESOURCE_TYPE_REPLICATION_GET_LOG_VOLUME 0x0200215D	Retrieves the path where log data can be written given a source or target disk and a log disk.
CLUSCTL_RESOURCE_TYPE_REPLICATION_GET_REPLICATED_DISKS 0x02002155	Retrieves the storage replication disks from the cluster state.
CLUSCTL_RESOURCE_TYPE_REPLICATION_GET_RESOURCE_GROUP 0x02002161	Retrieves the cluster groups from the cluster state that contain a storage class resource configured for storage replication.
CLUSCTL_RESOURCE_TYPE_REPLICATION_GET_LOG_INFO 0x02002145	Gets the replication log constraints.

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.

rpc_status: A 32-bit integer used to indicate success or failure. The RPC runtime MUST indicate, by writing to this parameter, whether the runtime succeeded in executing this method on the server. A value of 0x00000000 indicates that the method call was successfully transported to the server, executed with no faults, and returned control to the client without encountering any communication faults. This value is separate from the value returned by the method and does not represent the success of the method. The client MUST treat all nonzero values the same, except as specified in section 3.2.4.6.

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 resource type that is designated by lpszResourceTypeName 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.
0x00001732 ERROR_FILE_SHARE_RESOURCE_CONFLICT	For CLUSCTL_RESOURCE_TYPE_VALIDATE_PATH, the path in lpInBuffer refers to a file share that is hosted by one of the nodes in the cluster of which the server is a member.

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 subsections of 3.1.4.3.2 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.

3.1.4.2.76 ApiResourceTypeControl (Opnum 75)

Additional resources