3.1.4.1.10 ApiCreateResource (Opnum 9)

(Protocol Version 2) The ApiCreateResource method adds a resource of the specified type to the nonvolatile cluster state and establishes context on the server about the interaction of a client with the new resource by using the current RPC connection. The method returns a context handle so that the client can refer to the resource in subsequent method calls.

The server MUST initialize the resource's persistent state to ClusterResourceOffline, as described in section 3.1.1.1.1, and initialize the set of nodes that are capable of hosting the resource to all configured nodes.

A resource MUST maintain a state sequence number. The sequence number MUST be initialized to zero when the resource is created.

The resource ID MUST be assigned by the cluster at resource creation and MUST remain constant until the resource is deleted. The value that the cluster assigns for the resource ID is implementation-specific but MUST comply with the requirements specified in section 3.1.1.1.1. The cluster SHOULD assign the resource ID with a GUIDString.

The resource MUST initialize an empty set when the resource is created.

The server MUST configure the new resource with the default health detection and recovery actions as defined by its resource type.

The server MUST allow the creation of a resource even when the server implementation-specific object for its resource type is not present on any or all configured nodes in the cluster.

The server MUST initialize ResourceSharedVolumes to FALSE.

The server MUST accept an ApiCreateResource request only if its protocol server state is read/write, as specified in section 3.1.1.

 HRES_RPC ApiCreateResource(
   [in] HGROUP_RPC hGroup,
   [in, string] LPCWSTR lpszResourceName,
   [in, string] LPCWSTR lpszResourceType,
   [in] DWORD dwFlags,
   [out] error_status_t *Status
 );

hGroup: An HGROUP_RPC context handle that was obtained in a previous ApiOpenGroup or ApiCreateGroup method call.

lpszResourceName: A Unicode string that is the name to be associated with the new resource.

lpszResourceType: A Unicode string that contains the name of the type of resource to be created.

dwFlags: Identifies whether the resource instance is hosted in the default or its own resource monitor process. The dwFlags member MUST be set to one of the following values.

Value	Meaning
CLUSTER_RESOURCE_DEFAULT_MONITOR 0x00000000	The resource is co-located with other resources.
CLUSTER_RESOURCE_SEPARATE_MONITOR 0x00000001	The resource is hosted separately from other resources.

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_INVALID_HANDLE 0x00000006	The hGroup parameter does not represent a valid HGROUP_RPC context handle.
ERROR_INVALID_PARAMETER 0x00000057	One or more flags in the dwFlags parameter are not valid.
ERROR_OBJECT_ALREADY_EXISTS 0x00001392	The resource name is not unique. The resource name matches either the name or the ID of a different resource.
ERROR_GROUP_NOT_AVAILABLE 0x00001394	The group represented by the hGroup parameter is in the act of being deleted but still remains in the cluster state.
ERROR_GROUP_NOT_FOUND 0x00001395	The group represented by the hGroup parameter no longer exists in the nonvolatile cluster state.

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.

Return Values: The method MUST return a valid HRES_RPC context handle, as specified in section 2.2.1.4, to indicate success; otherwise, it MUST return NULL.