220.127.116.11.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 18.104.22.168.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 22.214.171.124.1. The cluster SHOULD assign the resource ID a Unicode string representation of a GUID in the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
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 );
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.
The resource is co-located with other resources.
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.
The hGroup parameter does not represent a valid HGROUP_RPC context handle.
One or more flags in the dwFlags parameter are not valid.
The resource name is not unique. The resource name matches either the name or the ID of a different resource.
The group represented by the hGroup parameter is in the act of being deleted but still remains in the cluster state.
The group represented by the hGroup parameter no longer exists in the nonvolatile cluster state.
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.
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.
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 126.96.36.199.
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 188.8.131.52.
Return Values: The method MUST return a valid HRES_RPC context handle, as specified in section 184.108.40.206, to indicate success; otherwise, it MUST return NULL.