3.1.4.3 Processing Notifications Sent from the Server to the Client

The client MAY choose to implement the IDMNotify interface to receive notification from the server of changes to the storage objects on the server. Notifications are sent to the client for storage object creation, deletion, and modification. The client MAY choose to take some other action based on these notifications. The client MAY also choose to ignore notifications from the server.<14>

Notifications related to storage object modification indicate a state change, such as the change of a region's status from REGIONSTATUS_OK to REGIONSTATUS_FAILED, or a change in a volume's length as the result of a call to GrowVolume.

Notifications containing a TASK_INFO structure indicate the status of a method call. Method calls that operate on storage objects return a TASK_INFO structure. This structure contains a status field. The status field of a TASK_INFO structure contains one of the following values: REQ_UNKNOWN, REQ_STARTED, REQ_IN_PROGRESS, REQ_COMPLETED, REQ_ABORTED, or REQ_FAILED. When a method call returns a success code as its HRESULT return code, the client MAY check the TASK_INFO structure's status field to determine the state of the server processing associated with the method call. Only if the TASK_INFO::status field is REQ_STARTED or REQ_IN_PROGRESS will the client receive any further notifications regarding this operation.

If the value of the TASK_INFO::status field is REQ_UNKNOWN, the client MUST assume that the server has encountered a catastrophic error. In this case, the client MUST assume that no further task notifications will be received.

If the value of the TASK_INFO::status field is REQ_COMPLETED, REQ_ABORTED, or REQ_FAILED, the client will not receive any further task notifications. If the value of the status field is REQ_COMPLETED, this indicates that the server processing finished without errors. If the value of the status field is REQ_ABORTED, this indicates that the server processing was interrupted and did not finish successfully. If the value of the status field is REQ_FAILED, this indicates that the server processing failed and did not finish successfully. In this case, the client inspects the TASK_INFO::error field.

If the value of the TASK_INFO::status field is REQ_STARTED or REQ_IN_PROGRESS, the client MUST assume that it will receive a TASK_INFO notification with the status field set to REQ_COMPLETED, REQ_ ABORTED, or REQ_ FAILED when the server has finished its processing for the operation. The client MUST NOT assume the server's processing is finished until a task notification with one of these status values has been received.

If the network connection fails, it MUST be reestablished and all server states MUST be refreshed by the client. In this case, in progress task information is lost to the client.

The client MAY receive one or more task notifications with the TASK_INFO::status value set to REQ_IN_PROGRESS. Notifications with this task status value are sent to indicate server progress while processing an operation request. If the client receives a notification with this TASK_INFO::status value, the client MAY inspect the TASK_INFO::percentComplete field to determine task progress.

The client maps task notifications received to a given method call based on the TASK_INFO::id field. This field is unique per method call.

For a full description of the IDMNotify interface and the ObjectsChanged method, see section 3.1.4.4.1.