3.1.4.2.109 ApiSetResourceDependencyExpression (Opnum 109)

(Protocol Version 3) The ApiSetResourceDependencyExpression method instructs the server to set the dependency relationship for the resource that is identified by hResource to the complex dependency, as specified in section 3.1.1.1.2, using dependency expression represented by lpszDependencyExpression. For successful completion of the method, the server MUST add the dependency information to the nonvolatile cluster state.

Servers MUST maintain complex resource dependencies as nonvolatile configuration data in their cluster state.

The server MUST limit the depth of a resource's dependency tree to 100.

Dependency expressions are "ANDs of Ors" such as (a or b) and (c or d), and so on. The client MUST provide an input lpszDependencyExpression that conforms to the following grammar:

 expression:
       or_expression
     | "(" or_expression ")"
     | "(" or_expression ")" "and" and_or_expression
  
 or_expression:
       resource
     | resource "or" or_expression
  
 and_or_expression:
       "(" or_expression ")"
     | "(" or_expression ")" "and" and_or_expression
     | resource
     | resource "and" and_or_expression
  
 resource:
       "[" resourceID "]"
     | "[" resourceName "]"

In this grammar, "resourceID" represents the ID of a resource, as returned by CLUSCTL_RESOURCE_GET_ID (3.1.4.3.1.8), and "resourceName" represents the name of a resource, as returned by CLUSCTL_RESOURCE_GET_NAME (3.1.4.3.1.6).

For example, the following expression indicates that hResource will remain online as long as a resource from each of the parenthesized expressions remains online.

  (
   [a904e1b7-95dd-47f0-9b2e-f1007d92699b]
   or
   [ae6fcf48-c42f-4960-a61a-7f1044067668]
  )
 and
  (
   [c471abc6-e454-482e-8be4-fae084cf799b]
   or
   [de976488-82cb-4950-8ce0-1b45e868e058]
  )
  

The server MUST fail this method using ERROR_INVALID_PARAMETER if the dependency expression does not conform to this grammar.

The server MUST clear the dependency relationship for hResource if the null Unicode string (0x0000) is specified.

The server MUST fail this method by using one of the following errors for any of the error's associated conditions described as follows:

• ERROR_INVALID_PARAMETER

  • hResource's resource ID is present in the dependency expression.

  • One or more of the resources in the dependency expression are not in the same group as the resource represented by hResource.

• ERROR_DEPENDENCY_ALREADY_EXISTS

  • The same resource ID is specified more than once in the dependency expression.

  • A dependency between hResource and a resource in the dependency expression already exists.

• ERROR_CIRCULAR_DEPENDENCY

  • A resource in the dependency expression is dependent on the resource represented by hResource. That is, circular dependencies are not permitted.

• ERROR_RESOURCE_ONLINE

  • hResource is in the ClusterResourceOnlinePending state.

  • hResource is in the ClusterResourceOnline state and none of the resources in the dependency expression are in the ClusterResourceOnline state.

The server MUST accept an ApiSetResourceDependencyExpression 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 hResource context handle is "All" (section 3.1.4).

 error_status_t ApiSetResourceDependencyExpression(
   [in] HRES_RPC hResource,
   [in, string, unique] LPCWSTR lpszDependencyExpression,
   [out] error_status_t *rpc_status
 );

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

lpszDependencyExpression: A pointer to a null-terminated Unicode string buffer containing a valid dependency expression.

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. The encoding of the value passed in this parameter MUST conform to encoding for comm_status and fault_status, as specified in Appendix E of [C706].

Return Values: The method MUST return the following error codes for the specified conditions.

Return value/code	Description
0x00000000 ERROR_SUCCESS	Success.
0x00000006 ERROR_INVALID_HANDLE	The data that is pointed to by the hResource parameter does not represent a valid HRES_RPC context handle.
0x00000057 ERROR_INVALID_PARAMETER	See the preceding text for details of when this error can occur.
0x00000423 ERROR_CIRCULAR_DEPENDENCY	See the preceding text for details of when this error can occur.
0x0000138B ERROR_DEPENDENCY_ALREADY_EXISTS	See the preceding text for details of when this error can occur.
0x0000139B ERROR_RESOURCE_ONLINE	See the preceding text for details of when this error can occur.
0x000013CD ERROR_DEPENDENCY_NOT_ALLOWED	Cannot depend on quorum resource.

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.