3.2.4.6 Reconnect Procedure

  • Article

msdn link

If certain methods fail, the client SHOULD attempt to reconnect to the cluster and reissue the method. Those methods are noted in their specifications, as specified in section 3.1.4.

Reconnect logic is triggered by specific error codes. For methods that return a context handle rather than an error code, the error code MUST be obtained by the client from the status parameter. Note that the status parameter is set by the server upon completion of such a method. For all other methods, the error code MUST be directly obtained from the return value of the method.

For version 2.0 of the protocol, clients SHOULD<226> reconnect on receipt of the following error codes.

Value

Symbol

6

ERROR_INVALID_HANDLE

1115

ERROR_SHUTDOWN_IN_PROGRESS

1255

ERROR_SERVER_SHUTDOWN_IN_PROGRESS

1702

RPC_S_INVALID_BINDING

1717

RPC_S_UNKNOWN_IF

1722

RPC_S_SERVER_UNAVAILABLE

1723

RPC_S_SERVER_TOO_BUSY

1726

RPC_S_CALL_FAILED

1727

RPC_S_CALL_FAILED_DNE

1747

RPC_S_UNKNOWN_AUTHN_SERVICE

1753

EPT_S_NOT_REGISTERED

1775

RPC_X_SS_IN_NULL_CONTEXT

5072

ERROR_CLUSTER_NODE_NOT_READY

5073

ERROR_CLUSTER_NODE_SHUTTING_DOWN

For version 3.0 of the protocol, clients SHOULD reconnect on the following error codes.

Value

Symbol

1702

RPC_S_INVALID_BINDING

1717

RPC_S_UNKNOWN_IF

1722

RPC_S_SERVER_UNAVAILABLE

1723

RPC_S_SERVER_TOO_BUSY

1726

RPC_S_CALL_FAILED

1727

RPC_S_CALL_FAILED_DNE

1747

RPC_S_UNKNOWN_AUTHN_SERVICE

1753

EPT_S_NOT_REGISTERED

1775

RPC_X_SS_IN_NULL_CONTEXT

1825

RPC_S_SEC_PKG_ERROR

5050

ERROR_CLUSTER_NODE_DOWN

5072

ERROR_CLUSTER_NODE_NOT_READY

5073

ERROR_CLUSTER_NODE_SHUTTING_DOWN

Note that in the previous two tables of error codes, those error codes whose values are in the range of 1702 to 1825 are returned by RPC, as specified in [MS-RPCE].

When the client receives one of the specific error codes from a call to one of the specific methods, the client SHOULD reconnect to the cluster and retry the method according to the following procedure:

  1. The client SHOULD obtain a reconnect candidate name from the list of reconnect candidates that were previously constructed as specified in section 3.2.3.3. If all candidates in the list have already been attempted in this reconnect procedure, reconnect has failed, and the client SHOULD perform the following steps:

    • For each version 1 notification port associated with the cluster, a CLUSTER_CHANGE_CLUSTER_STATE event indication, as specified in section 2.2.2.7, is posted to the client queue of event indications, specifying the cluster name as the name of the object associated with the event.

    • For each version 2 notification port associated with the cluster, a CLUSTER_CHANGE_GROUP_STATE_V2 event indication, as specified in section 2.2.2.13, is posted to the client queue of event indications, specifying the cluster name as the name of the object associated with the event.

    • Return the original error code to the caller.

  2. The client SHOULD determine whether the candidate name matches the computer name of the server that the client was connected to when the reconnect procedure started. That server computer name SHOULD have been obtained as specified in section 3.2.3.3. If the candidate name matches the server name, the client SHOULD proceed to the next candidate in the list of reconnect candidates and go back to step 1. However, if all other candidates in the list have already been attempted, the client SHOULD proceed with the candidate whose name matches the server computer name.

  3. The client SHOULD free any existing RPC binding to a node in the cluster.

  4. The client SHOULD attempt to establish an RPC connection to the reconnect candidate name, as specified in section 3.2.3.2. If RPC connection establishment fails, the client SHOULD proceed to the next node in the enumeration and go back to step 1.

  5. The client SHOULD call ApiGetClusterName (section 3.1.4.1.4 for protocol version 2, or 3.1.4.2.4 for protocol version 3) to obtain the cluster name and the computer name of the server currently connected to. If ApiGetClusterName fails, the client SHOULD proceed to the next candidate in the list of reconnect candidates and go back to step 1. The client SHOULD NOT interpret error codes from ApiGetClusterName for reconnection as specified in this section. If ApiGetClusterName succeeds, the client SHOULD use the returned cluster name and node name to replace the cluster name and the computer name of the server that it is currently connected to. The returned cluster name and node were previously obtained as specified in section 3.2.3.3 or in a previous reconnect attempt.

  6. The client SHOULD free any existing HCLUSTER_RPC context handle, which was obtained as specified in section 3.2.3.3 or in a previous reconnect attempt.

  7. For protocol version 3.0, if the level of access granted for the HCLUSTER_RPC context handle in step 6 was not "All", the client SHOULD<227> call ApiOpenClusterEx (section 3.1.4.2.116, for protocol version 3 only), requesting the same level of access. Otherwise, and for protocol version 2.0, the client SHOULD call ApiOpenCluster (section 3.1.4.1.1 for protocol version 2, or 3.1.4.2.1 for protocol version 3). If this method fails, the client SHOULD proceed to the next candidate in the list of reconnect candidates and go back to step 1.

  8. For each HNODE_RPC context handle that the client has retained from a previous RPC connection or reconnect attempt, the client SHOULD first free that context. Then, for protocol version 3.0, if the level of access granted for the HNODE_RPC context handle was not "All", the client SHOULD call ApiOpenNodeEx (section 3.1.4.2.117, for protocol version 3 only), requesting the same level of access. Otherwise, and for protocol version 2.0, the client SHOULD call ApiOpenNode (section 3.1.4.1.67 for protocol version 2, or 3.1.4.2.67 for protocol version 3) to obtain an HNODE_RPC context handle that has the new RPC binding. If the ApiOpenNode method fails, the client SHOULD proceed to the next candidate in the list of reconnect candidates and go back to step 1. The client SHOULD NOT interpret error codes from ApiOpenNode for reconnection as specified in this section.

  9. The client SHOULD repeat step 8 by using HGROUP_RPC handles instead of HNODE_RPC handles and by using ApiOpenGroupEx (section 3.1.4.2.118, for protocol version 3 only) or ApiOpenGroup (section 3.1.4.1.42 for protocol version 2, or 3.1.4.2.42 for protocol version 3) to open context handles with the new RPC binding.

  10. The client SHOULD repeat step 8; however, this time, the client SHOULD use HRES_RPC handles and ApiOpenResourceEx (section 3.1.4.2.119, for protocol version 3 only) or ApiOpenResource (section 3.1.4.1.9 for protocol version 2, or 3.1.4.2.9 for protocol version 3) to open context handles with the new RPC binding.

  11. The client SHOULD repeat step 8; however, this time, the client SHOULD NOT consider the level of access previously granted, and the client SHOULD use HKEY_RPC handles and ApiGetRootKey (section 3.1.4.1.29 for protocol version 2, or 3.1.4.2.29 for protocol version 3) and ApiOpenKey (section 3.1.4.1.31 for protocol version 2, or 3.1.4.2.31 for protocol version 3) to open context handles with the new RPC binding.

  12. The client SHOULD repeat step 8; however, this time, the client SHOULD use HNETWORK_RPC handles and ApiOpenNetworkEx (section 3.1.4.2.120, for protocol version 3 only) or ApiOpenNetwork (section 3.1.4.1.81 for protocol version 2, or 3.1.4.2.81 for protocol version 3) to open context handles with the new RPC binding.

  13. The client SHOULD repeat step 8; however, this time, the client SHOULD use HNETINTERFACE_RPC handles and ApiOpenNetInterfaceEx (section 3.1.4.2.121, for protocol version 3 only) or ApiOpenNetInterface (section 3.1.4.1.92 for protocol version 2, or 3.1.4.2.92 for protocol version 3) to open context handles with the new RPC binding.

  14. The client SHOULD repeat step 8; however, this time, the client SHOULD NOT consider the level of access previously granted, and the client SHOULD use HNOTIFY_RPC handles associated with version 1 notification ports and ApiCreateNotify (section 3.1.4.1.56 for protocol version 2, or 3.1.4.2.56 for protocol version 3) to open context handles with the new RPC binding.

  15. For each HNOTIFY_RPC context handle that the client re-created in step 14, the client SHOULD re-register the event filters associated with the port by calling the registration method that is appropriate for the type of event filter and queue a local reconnect event indication to the port. If any of the registration methods in the following list fails, the client SHOULD proceed to the next candidate in the list of reconnect candidates and go back to step 1. The client SHOULD NOT interpret any error code from the registration methods for reconnection as specified in this section.

    1. The client SHOULD call the ApiAddNotifyCluster (section 3.1.4.1.58 for protocol version 2, or 3.1.4.2.58 for protocol version 3) method for event filters that were registered with a previous call to ApiAddNotifyCluster.

    2. The client SHOULD call the ApiAddNotifyKey (section 3.1.4.1.62 for protocol version 2, or 3.1.4.2.62 for protocol version 3) method for event filters that were registered with a previous call to ApiAddNotifyKey.

    3. The client SHOULD call the ApiReAddNotifyNode (section 3.1.4.1.63 for protocol version 2, or 3.1.4.2.63 for protocol version 3) method for event filters that were registered with a previous call to ApiAddNotifyNode (section 3.1.4.1.59 for protocol version 2, or 3.1.4.2.59 for protocol version 3).

    4. The client SHOULD call the ApiReAddNotifyGroup (section 3.1.4.1.64 for protocol version 2, or 3.1.4.2.64 for protocol version 3) method for event filters that were registered with a previous call to ApiAddNotifyGroup (section 3.1.4.1.60 for protocol version 2, or 3.1.4.2.60 for protocol version 3).

    5. The client SHOULD call the ApiReAddNotifyResource (section 3.1.4.1.65 for protocol version 2, or 3.1.4.2.65 for protocol version 3) method for event filters that were registered with a previous call to ApiAddNotifyResource (section 3.1.4.1.61 for protocol version 2, or 3.1.4.2.61 for protocol version 3).

    6. The client SHOULD call the ApiReAddNotifyNetwork (section 3.1.4.1.91 for protocol version 2, or 3.1.4.2.91 for protocol version 3) method for event filters that were registered with a previous call to ApiAddNotifyNetwork (section 3.1.4.1.90 for protocol version 2, or 3.1.4.2.90 for protocol version 3).

    7. The client SHOULD call the ApiReAddNotifyNetInterface (section 3.1.4.1.100 for protocol version 2, or 3.1.4.2.100 for protocol version 3) method for event filters that were registered with a previous call to ApiAddNotifyNetInterface (section 3.1.4.1.99 for protocol version 2, or 3.1.4.2.99 for protocol version 3).

    8. The client SHOULD post a CLUSTER_CHANGE_CLUSTER_RECONNECT to the client-side queue of event indications specifying the cluster name as the name of the object associated with the event.

  16. The client SHOULD repeat step 8; however, this time the client SHOULD NOT consider the level of access previously granted, and the client SHOULD use HNOTIFY_RPC handles associated with version 2 notification ports and ApiCreateNotifyV2 (section 3.1.4.2.136) for protocol version 3 to open context handles with the new RPC binding.

  17. For each HNOTIFY_RPC context handle that the client re-created in step 16, the client SHOULD re-register the event filters associated with the port by calling the ApiAddNotifyV2 (section 3.1.4.2.137) method and queue a local reconnect event indication to the port. If any of the registration methods in the following list fails, the client SHOULD proceed to the next candidate in the list of reconnect candidates and go back to step 1. The client SHOULD NOT interpret any error code from the registration methods for reconnection as specified in this section.

    1. The client SHOULD call the ApiAddNotifyV2 for protocol version 3 method for event filters that were registered with a previous call to ApiAddNotifyV2.

    2. The client SHOULD post a CLUSTER_CHANGE_CLUSTER_RECONNECT_V2 to the client-side queue of event indications specifying the cluster name as the name of the object associated with the event.

Reconnect has succeeded. In preparation for a possible future reconnection, the client SHOULD consider all candidates in the list of reconnect candidates as having not yet attempted any connection.

The client SHOULD use the new RPC connection and context handles to reattempt the method whose failure initiated the reconnect procedure.