3.1.4.2.27 ApiCreateResourceType (Opnum 26)

(Protocol Version 3) The ApiCreateResourceType method adds the designated resource type to the nonvolatile cluster state. The nonvolatile cluster state is updated.

The server MUST fail the method if the resource type name is not unique. The server MUST return ERROR_ALREADY_EXISTS or ERROR_OBJECT_ALREADY_EXISTS.

A server MUST allow a resource type to be added to the nonvolatile cluster state without requiring the presence of the server implementation specific object that codifies the resource's functionality on any configured node. The server MUST NOT allow the resource to be hosted on a node where the object is not present except when all of the active nodes are missing the object; then the cluster MUST host the resource on an active node but it MUST NOT attempt to bring the resource to the Online state. For more information on resource type objects, see section 3.1.1.1.3.

The dwLooksAlive and dwIsAlive parameters specify periodic time intervals. These time intervals SHOULD be used to determine when the health of a resource of this type is checked. The resource MUST inherit the current values for these parameters when it is created.

The server MUST accept an ApiCreateResourceType request for processing only if it is in the read/write state, as specified in section 3.1.1.

The server MUST require that the client have a security access level of "All" (section 3.1.4).

 error_status_t ApiCreateResourceType(
   [in, string] LPCWSTR lpszTypeName,
   [in, string] LPCWSTR lpszDisplayName,
   [in, string] LPCWSTR lpszDllName,
   [in] DWORD dwLooksAlive,
   [in] DWORD dwIsAlive,
   [out] error_status_t *rpc_status
 );

lpszTypeName: A pointer to a Unicode string buffer that uniquely specifies the name of the new resource type.

lpszDisplayName: A pointer to a Unicode string buffer that specifies the display name of the new resource type. The display name SHOULD be used to provide a localized, friendly name suitable for display in cluster management tools.

lpszDllName: A pointer to a Unicode string buffer that specifies a server implementation-specific object that codifies the methods for controlling, configuring, and monitoring the health of a resource based on this type.

dwLooksAlive: The periodic interval of time, in milliseconds, when the cluster SHOULD instruct the server to perform a low-cost check of the health of a resource of this type. The server SHOULD use this value to configure the LooksAlive timer for any resource subsequently created with this resource type. How the server implements this low-cost health-check, how the server uses the timer to schedule the health-check, and how the server reacts to the result of the health-check are all implementation-specific.

dwIsAlive: The periodic interval of time, in milliseconds, when the cluster SHOULD instruct the server to perform a more in-depth check of the health of a resource of this type. The server uses this value to configure the IsAlive timer for any resource subsequently created with this resource type. How the server implements this more in-depth health-check, how the server uses the timer to schedule the health-check, and how the server reacts to the result of the health-check are all implementation-specific.

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. A value of 0x00000000 indicates that the method call was successfully transported to the server, executed with no faults with control returned 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 the following error codes for the specified conditions.

Return value/code	Description
0x00000000 ERROR_SUCCESS	Success.
0x000000B7 ERROR_ALREADY_EXISTS	See the preceding text for when this error can occur.
0x00001392 ERROR_OBJECT_ALREADY_EXISTS	See the preceding text for when this error can occur.

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.