3.1.4.2.74 ApiResourceControl (Opnum 73)

Article
04/27/2022

(Protocol Version 3) The ApiResourceControl method instructs the server to initiate, on the node hosting the specified resource, an operation that is defined by the specified control code.

The access level associated with the hResource context handle MUST be "All" (section 3.1.4), 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 ApiResourceControl(
   [in] HRES_RPC hResource,
   [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
 );

hResource: An HRES_RPC (section 2.2.1.4) context handle that is obtained in a previous ApiOpenResource (section 3.1.4.2.9), ApiOpenResourceEx (section 3.1.4.2.119) or ApiCreateResource (section 3.1.4.2.10) method call.

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

Value	Meaning
CLUSCTL_RESOURCE_UNKNOWN (section 3.1.4.3.1.1) 0x1000000	Verifies that control codes for the resource are being processed.
CLUSCTL_RESOURCE_GET_CHARACTERISTICS (section 3.1.4.3.1.2) 0x1000005	Retrieves the intrinsic characteristics associated with the resource.
CLUSCTL_RESOURCE_GET_FLAGS (section 3.1.4.3.1.3) 0x1000009	Retrieves the flags that are set for a resource.
CLUSCTL_RESOURCE_GET_CLASS_INFO (section 3.1.4.3.1.4) 0x100000D	Retrieves info about the class to which the designated resource belongs.
CLUSCTL_RESOURCE_GET_REQUIRED_DEPENDENCIES (section 3.1.4.3.1.5) 0x1000011	Retrieves a list of the names of resource types on which the designated resource MUST be dependent on in order to properly operate.
CLUSCTL_RESOURCE_GET_NAME (section 3.1.4.3.1.6) 0x1000029	Retrieves the name of the resource.
CLUSCTL_RESOURCE_GET_RESOURCE_TYPE (section 3.1.4.3.1.7) 0x100002D	Retrieves the resource type of the designated resource.
CLUSCTL_RESOURCE_GET_ID (section 3.1.4.3.1.8) 0x1000039	Retrieves the unique ID for the resource.
CLUSCTL_RESOURCE_ENUM_COMMON_PROPERTIES (section 3.1.4.3.1.9) 0x1000051	Retrieves a list of the common property names for the designated resource.
CLUSCTL_RESOURCE_GET_RO_COMMON_PROPERTIES (section 3.1.4.3.1.10) 0x1000055	Retrieves the read-only common property values for the designated resource.
CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES (section 3.1.4.3.1.11) 0x1000059	Retrieves all common property values for the designated resource.
CLUSCTL_RESOURCE_SET_COMMON_PROPERTIES (section 3.1.4.3.1.12) 0x140005E	Sets the common property values for the designated resource.
CLUSCTL_RESOURCE_VALIDATE_COMMON_PROPERTIES (section 3.1.4.3.1.13) 0x1000061	Validates that the values supplied for the common properties are acceptable for the designated resource.
CLUSCTL_RESOURCE_GET_COMMON_PROPERTY_FMTS (section 3.1.4.3.1.14) 0x1000065	Retrieves a list of the common properties formats for the designated resource.
CLUSCTL_RESOURCE_ENUM_PRIVATE_PROPERTIES (section 3.1.4.3.1.15) 0x1000079	Retrieves a list of the private property names for the designated resource.
CLUSCTL_RESOURCE_GET_RO_PRIVATE_PROPERTIES (section 3.1.4.3.1.16) 0x100007D	Retrieves the read-only private property values for the designated resource.
CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES (section 3.1.4.3.1.17) 0x1000081	Retrieves all private property values for the designated resource.
CLUSCTL_RESOURCE_SET_PRIVATE_PROPERTIES (section 3.1.4.3.1.18) 0x1400086	Sets the private property values for the designated resource.
CLUSCTL_RESOURCE_VALIDATE_PRIVATE_PROPERTIES (section 3.1.4.3.1.19) 0x1000089	Validates that the values supplied for the private properties are acceptable for the designated resource.
CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTY_FMTS (section 3.1.4.3.1.20) 0x100008D	Retrieves a list of the private property formats for the designated resource.
CLUSCTL_RESOURCE_ADD_REGISTRY_CHECKPOINT (section 3.1.4.3.1.21) 0x14000A2	Adds a registry checkpoint to the designated resource.
CLUSCTL_RESOURCE_DELETE_REGISTRY_CHECKPOINT (section 3.1.4.3.1.22) 0x14000A6	Removes a registry checkpoint from the designated resource.
CLUSCTL_RESOURCE_GET_REGISTRY_CHECKPOINTS (section 3.1.4.3.1.23) 0x10000A9	Retrieves a list of registry checkpoints associated with the designated resource.
CLUSCTL_RESOURCE_ADD_CRYPTO_CHECKPOINT (section 3.1.4.3.1.24) 0x14000AE	Associates a cryptographic container checkpoint with the designated resource.
CLUSCTL_RESOURCE_DELETE_CRYPTO_CHECKPOINT (section 3.1.4.3.1.25) 0x14000B2	Removes the cryptographic container checkpoint from the designated resource.
CLUSCTL_RESOURCE_GET_CRYPTO_CHECKPOINTS (section 3.1.4.3.1.26) 0x010000B5	Retrieves a list of cryptographic container checkpoints associated with the designated resource.
CLUSCTL_RESOURCE_UPGRADE_DLL (section 3.1.4.3.1.27) 0x14000BA	Instructs the server to change the resource DLL for the resource type of the designated resource without stopping the cluster service.
CLUSCTL_RESOURCE_ADD_REGISTRY_CHECKPOINT_64BIT (section 3.1.4.3.1.28) 0x14000BE	Add a registry checkpoint to the designated resource.
CLUSCTL_RESOURCE_ADD_REGISTRY_CHECKPOINT_32BIT (section 3.1.4.3.1.29) 0x14000C2	Add a registry checkpoint to the designated resource.
CLUSCTL_RESOURCE_GET_NETWORK_NAME (section 3.1.4.3.1.30) 0x1000169	Queries the NetBIOS name of the designated resource.
CLUSCTL_RESOURCE_NETNAME_REGISTER_DNS_RECORDS (section 3.1.4.3.1.31) 0x1000172	Instructs the server to register the Domain Name System (DNS) records associated with the designated resource.
CLUSCTL_RESOURCE_GET_DNS_NAME (section 3.1.4.3.1.32) 0x1000175	Queries the DNS of the designated resource.
CLUSCTL_RESOURCE_NETNAME_SET_PWD_INFO (section 3.1.4.3.1.33) 0x100017A	Updates information about the security principal of the designated resource.
CLUSCTL_RESOURCE_NETNAME_DELETE_CO (section 3.1.4.3.1.34) 0x100017E	Deletes the security principal of the designated resource.
CLUSCTL_RESOURCE_NETNAME_VALIDATE_VCO (section 3.1.4.3.1.35) 0x1000181	Confirms whether the security principal of the designated resource can be managed by the cluster.
CLUSCTL_RESOURCE_NETNAME_RESET_VCO (section 3.1.4.3.1.36) 0x1000185	Resets the password for the designated alternate computer name's associated security principal.
CLUSCTL_RESOURCE_NETNAME_CREDS_UPDATED (section 3.1.4.3.1.37) 0x1c0018a	Notifies the resource that the credentials for the domain account associated with the resource have changed.
CLUSCTL_RESOURCE_STORAGE_GET_DISK_INFO 0x1000191	Retrieves data about the disk that the designated storage-class resource represents.
CLUSCTL_RESOURCE_STORAGE_IS_PATH_VALID (section 3.1.4.3.1.39) 0x1000199	Confirms that the path exists on the designated resource.
CLUSCTL_RESOURCE_IPADDRESS_RENEW_LEASE (section 3.1.4.3.1.40) 0x14001BE	Acquires or renews the IP address associated with the designated resource.
CLUSCTL_RESOURCE_IPADDRESS_RELEASE_LEASE (section 3.1.4.3.1.41) 0x14001C2	Releases the IP address associated with the designated resource.
CLUSCTL_RESOURCE_QUERY_MAINTENANCE_MODE (section 3.1.4.3.1.42) 0x10001E1	Queries the maintenance state of the designated storage-class resource.
CLUSCTL_RESOURCE_SET_MAINTENANCE_MODE (section 3.1.4.3.1.43) 0x14001E6	Places the designated storage-class resource into maintenance.
CLUSCTL_RESOURCE_STORAGE_SET_DRIVELETTER (section 3.1.4.3.1.44) 0x14001EA	Modifies the drive letter associated with the designated storage-class resource.
CLUSCTL_RESOURCE_STORAGE_GET_DISK_INFO_EX (section 3.1.4.3.1.45) 0x10001F1	Retrieves data about the disk that the designated storage-class resource represents.
CLUSCTL_RESOURCE_STORAGE_GET_DIRTY (section 3.1.4.3.1.46) 0x1000219	Retrieves a list of dirty volumes on the disk.
CLUSCTL_RESOURCE_STORAGE_GET_MOUNTPOINTS (section 3.1.4.3.1.47) 0x1000211	Retrieves a list of volume path names for a partition on the disk.
CLUSCTL_RESOURCE_STORAGE_GET_SHARED_VOLUME_INFO (section 3.1.4.3.1.48) 0x1000225	Retrieves information about a cluster shared volume.
CLUSCTL_RESOURCE_VM_START_MIGRATION (section 3.1.4.3.1.49) 0x1600004	Indicates to the VM resource that it needs to migrate to the specified cluster node.
CLUSCTL_RESOURCE_VM_CANCEL_MIGRATION (section 3.1.4.3.1.50) 0x1600008	Indicates to the VM resource that it needs to cancel any pending migration.
CLUSCTL_RESOURCE_SET_CSV_MAINTENANCE_MODE (section 3.1.4.3.1.51) 0x1400296	Enables or disables volume maintenance mode on the designated cluster shared volume.<81>
CLUSCTL_RESOURCE_ENABLE_SHARED_VOLUME_DIRECTIO (section 3.1.4.3.1.52) 0x140028a	Disables redirected mode on the designated cluster shared volume.
CLUSCTL_RESOURCE_DISABLE_SHARED_VOLUME_DIRECTIO (section 3.1.4.3.1.53) 0x140028e	Enables redirected mode on the designated cluster shared volume.
CLUSCTL_RESOURCE_SET_SHARED_VOLUME_BACKUP_MODE (section 3.1.4.3.1.54) 0x140029a	Enables or disables backup mode on the designated cluster shared volume.<82>
CLUSCTL_RESOURCE_GET_RELATED_RESOURCE_NAMES (section 3.1.4.3.1.55) 0x1001fad	Returns the list of other resources that will also be validated if this resource is validated by the cluster validation process.<83>
CLUSCTL_RESOURCE_POOL_GET_DRIVE_INFO (section 3.1.4.3.1.56) 0x10002b5	Returns the list of drives and information about them that comprise the storage pool.
CLUSCTL_CLOUD_WITNESS_RESOURCE_UPDATE_TOKEN (section 3.1.4.3.1.57) 0x014020e6	Updates the token used by the server to authenticate access to the witness.
CLUSCTL_RESOURCE_NETNAME_CHECK_OU_PERMISSIONS (section 3.1.4.3.1.58) 0x07002121	Determines whether the primary security principal of the cluster has the proper level of authorization to create an alternate computer object on a directory server.
CLUSCTL_RESOURCE_NETNAME_CHECK_AD_STATE (section 3.1.4.3.1.59) 0x07002125	Queries for status information about the alternate computer name associated with the resource.
CLUSCTL_RESOURCE_GET_STATE_CHANGE_TIME (section 3.1.4.3.1.60) 0x01002d5d	Gets the last time the resource changed state.
CLUSCTL_RESOURCE_STORAGE_GET_DISK_INFO_EX2 (section 3.1.4.3.1.61) 0x010001f9	Returns information about a disk.
CLUSCTL_RESOURCE_STORAGE_GET_DISK_NUMBER_INFO (section 3.1.4.3.1.62) 0x010001a1	Returns the disk device number and sector size.
CLUSCTL_RESOURCE_NETNAME_SET_PWD_INFOEX (section 3.1.4.3.1.63) 0x0100031a	Updates information about the security principals of the designated resource. <84>
CLUSCTL_RESOURCE_GET_NODES_IN_FD 0x01002de1	Retrieves the nodes in the fault domain.<85>

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. If a section does not specify the contents of lpInBuffer, then lpInBuffer is not defined for that control code and the server MUST ignore this parameter.

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. The encoding of the value passed in this parameter MUST conform to encoding for comm_status and fault_status, as specified in [C706] Appendix E.

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 that is designated by hResource 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.
0x0000139B ERROR_RESOURCE_ONLINE	The server MUST fail this method using error code ERROR_RESOURCE_ONLINE unless the resource is in ClusterResourceOffline or ClusterResourceFailed state (see section 3.1.4.3).
0x000013A0 ERROR_RESOURCE_PROPERTIES_STORED	See section 3.1.4.3 for when this error can occur.

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.

3.1.4.2.74 ApiResourceControl (Opnum 73)

Additional resources