3.1.4.2.10 ApiCreateResource (Opnum 9)

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

The server MUST require that the access level associated with the hGroup context handle is "All" (section 3.1.4).

Upon success, the server MUST associate a security access level of "All" with the resource context it has established.

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

hGroup: An HGROUP_RPC context handle that was obtained in a previous ApiOpenGroup, ApiOpenGroupEx, 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.
ERROR_CLUSTER_SINGLETON_RESOURCE 0x00001734	The resource type has indicated via its characteristics that only one resource of its type is permitted in a cluster, and that a resource of that type already exists. ClusAPI Protocol version 2.0 servers do not support this value.
ERROR_CLUSTER_GROUP_SINGLETON_RESOURCE 0x00001735	The resource type has indicated via its characteristics that only one resource of its type is permitted in a group, and a resource of that type already exists in the designated group. ClusAPI Protocol version 2.0 servers do not support this value.
ERROR_CLUSTER_USE_SHARED_VOLUMES_API 0x0000173C	This group or resource cannot be directly manipulated. Use shared volume APIs to perform the requested operation.

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.

rpc_status: A 32-bit integer used to indicate success or failure. The RPC runtime MUST indicate, by writing to this parameter, whether or not it 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 a valid HRES_RPC context handle, as specified in section 2.2.1.4, to indicate success; otherwise, it MUST return NULL.