3.1.4.1.74 ApiResourceControl (Opnum 73)

Article
04/27/2022

(Protocol Version 2) 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.

 error_status_t ApiResourceControl(
   [in] HRES_RPC hResource,
   [in] unsigned long dwControlCode,
   [in, unique, size_is(nInBufferSize)] unsigned char *lpInBuffer,
   [in] unsigned long nInBufferSize,
   [out, size_is(nOutBufferSize),  
     length_is (*lpBytesReturned)] unsigned char *lpOutBuffer,
   [in] unsigned long nOutBufferSize,
   [out] unsigned long *lpBytesReturned,
   [out] unsigned long *lpcbRequired
 );

hResource: An HRES_RPC context handle that is obtained in a previous ApiOpenResource or ApiCreateResource method call.

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

Value	Meaning
CLUSCTL_RESOURCE_UNKNOWN 0x1000000	Verifies that control codes for the resource are being processed.
CLUSCTL_RESOURCE_GET_CHARACTERISTICS 0x1000005	Retrieves the intrinsic characteristics associated with the resource.
CLUSCTL_RESOURCE_GET_FLAGS 0x1000009	Retrieves the flags that are set for a resource.
CLUSCTL_RESOURCE_GET_CLASS_INFO 0x100000D	Retrieves info about the class to which the designated resource belongs.
CLUSCTL_RESOURCE_GET_REQUIRED_DEPENDENCIES 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 0x1000029	Retrieves the name of the resource.
CLUSCTL_RESOURCE_GET_RESOURCE_TYPE 0x100002D	Retrieves the resource type of the designated resource.
CLUSCTL_RESOURCE_GET_ID 0x1000039	Retrieves the unique ID for the resource.
CLUSCTL_RESOURCE_ENUM_COMMON_PROPERTIES 0x1000051	Retrieves a list of the common property names for the designated resource.
CLUSCTL_RESOURCE_GET_RO_COMMON_PROPERTIES 0x1000055	Retrieves the read-only common property values for the designated resource.
CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES 0x1000059	Retrieves all common property values for the designated resource.
CLUSCTL_RESOURCE_SET_COMMON_PROPERTIES 0x140005E	Sets the common property values for the designated resource.
CLUSCTL_RESOURCE_VALIDATE_COMMON_PROPERTIES 0x1000061	Validates that the values supplied for the common properties are acceptable for the designated resource.
CLUSCTL_RESOURCE_GET_COMMON_PROPERTY_FMTS 0x1000065	Retrieves a list of the common properties formats for the designated resource.
CLUSCTL_RESOURCE_ENUM_PRIVATE_PROPERTIES 0x1000079	Retrieves a list of the private property names for the designated resource.
CLUSCTL_RESOURCE_GET_RO_PRIVATE_PROPERTIES 0x100007D	Retrieves the read-only private property values for the designated resource.
CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES 0x1000081	Retrieves all private property values for the designated resource.
CLUSCTL_RESOURCE_SET_PRIVATE_PROPERTIES 0x1400086	Sets the private property values for the designated resource.
CLUSCTL_RESOURCE_VALIDATE_PRIVATE_PROPERTIES 0x1000089	Validates that the values supplied for the private properties are acceptable for the designated resource.
CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTY_FMTS 0x100008D	Retrieves a list of the private property formats for the designated resource.
CLUSCTL_RESOURCE_ADD_REGISTRY_CHECKPOINT 0x14000A2	Adds a registry checkpoint to the designated resource.
CLUSCTL_RESOURCE_DELETE_REGISTRY_CHECKPOINT 0x14000A6	Removes a registry checkpoint from the designated resource.
CLUSCTL_RESOURCE_GET_REGISTRY_CHECKPOINTS 0x10000A9	Retrieves a list of registry checkpoints associated with the designated resource.
CLUSCTL_RESOURCE_ADD_CRYPTO_CHECKPOINT 0x14000AE	Associates a cryptographic container checkpoint with the designated resource.
CLUSCTL_RESOURCE_DELETE_CRYPTO_CHECKPOINT 0x14000B2	Removes the cryptographic container checkpoint from the designated resource.
CLUSCTL_RESOURCE_GET_CRYPTO_CHECKPOINTS 0x010000B5	Retrieves a list of cryptographic container checkpoints associated with the designated resource.
CLUSCTL_RESOURCE_UPGRADE_DLL 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 0x14000BE	Add a registry checkpoint to the designated resource.
CLUSCTL_RESOURCE_ADD_REGISTRY_CHECKPOINT_32BIT 0x14000C2	Add a registry checkpoint to the designated resource.
CLUSCTL_RESOURCE_GET_NETWORK_NAME 0x1000169	Queries the NetBIOS name of the designated resource.
CLUSCTL_RESOURCE_NETNAME_REGISTER_DNS_RECORDS 0x1000172	Instructs the server to register the Domain Name System (DNS) records associated with the designated resource.
CLUSCTL_RESOURCE_GET_DNS_NAME 0x1000175	Queries the DNS of the designated resource.
CLUSCTL_RESOURCE_NETNAME_SET_PWD_INFO 0x100017A	Updates information about the security principal of the designated resource.
CLUSCTL_RESOURCE_NETNAME_DELETE_CO 0x100017E	Deletes the security principal of the designated resource.
CLUSCTL_RESOURCE_NETNAME_VALIDATE_VCO 0x1000181	Confirms whether the security principal of the designated resource can be managed by the cluster.
CLUSCTL_RESOURCE_NETNAME_RESET_VCO 0x1000185	Resets the password for the designated alternate computer name's associated security principal.
CLUSCTL_RESOURCE_NETNAME_CREDS_UPDATED 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 0x1000199	Confirms that the path exists on the designated resource.
CLUSCTL_RESOURCE_IPADDRESS_RENEW_LEASE 0x14001BE	Acquires or renews the IP address associated with the designated resource.
CLUSCTL_RESOURCE_IPADDRESS_RELEASE_LEASE 0x14001C2	Releases the IP address associated with the designated resource.
CLUSCTL_RESOURCE_QUERY_MAINTENANCE_MODE 0x10001E1	Queries the maintenance state of the designated storage-class resource.
CLUSCTL_RESOURCE_SET_MAINTENANCE_MODE 0x14001E6	Places the designated storage-class resource into maintenance.
CLUSCTL_RESOURCE_STORAGE_SET_DRIVELETTER 0x14001EA	Modifies the drive letter associated with the designated storage-class resource.
CLUSCTL_RESOURCE_STORAGE_GET_DISK_INFO_EX 0x10001F1	Retrieves data about the disk that the designated storage-class resource represents.
CLUSCTL_RESOURCE_STORAGE_GET_DIRTY 0x1000219	Retrieves a list of dirty volumes on the disk.
CLUSCTL_RESOURCE_STORAGE_GET_MOUNTPOINTS 0x1000211	Retrieves a list of volume path names for a partition on the disk.
CLUSCTL_RESOURCE_STORAGE_GET_SHARED_VOLUME_INFO 0x1000225	Retrieves information about a cluster shared volume.
CLUSCTL_RESOURCE_VM_START_MIGRATION 0x1600004	Indicates to the VM resource that it needs to migrate to the specified cluster node.
CLUSCTL_RESOURCE_VM_CANCEL_MIGRATION 0x1600008	Indicates to the VM resource that it needs to cancel any pending migration.
CLUSCTL_RESOURCE_SET_CSV_MAINTENANCE_MODE 0x1400296	Enables or disables volume maintenance mode on the designated cluster shared volume.
CLUSCTL_RESOURCE_ENABLE_SHARED_VOLUME_DIRECTIO 0x140028a	Disables redirected mode on the designated cluster shared volume.
CLUSCTL_RESOURCE_DISABLE_SHARED_VOLUME_DIRECTIO 0x140028e	Enables redirected mode on the designated cluster shared volume.
CLUSCTL_RESOURCE_SET_SHARED_VOLUME_BACKUP_MODE 0x140029a	Enables or disables backup mode on the designated cluster shared volume.

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.

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.

Share via

3.1.4.1.74 ApiResourceControl (Opnum 73)

Additional resources