External Agent COM API Reference Guide › API Interfaces: Applying Policy and Generating CA DataMinder Events › COM Object: WGNRDILib::WgnActiveImportConnector › Interface IWgnImportConnectorCallback › Method OnUpdate

Method OnUpdate

The External Agent calls this method to notify the caller that it has finished processing an e‑mail.

HRESULT OnUpdate(
    [in,unique]  LPVOID                     contextTag,
    [in]         long                       hrStatus,
    [in,unique]  IWgnImportConnectorResult  *results,
    [in,unique]  IWgnImportConnectorDeferredCompletion *deferredCompletion
  );

Where:

contextTag

Is the value supplied to either the ImportObjectAsync() or CommitAsync() methods. It allows the client to match the callback to the message passed to the External Agent.

hrStatus

Can be:

S_OK

The message was processed successfully and there is no pending CA DataMinder event. In this situation, the deferredCompletion parameter should be NULL.

WGN_S_ACTIVEIMPORT_AWAITING_COMPLETION

The message has been successfully analyzed, but no data has been saved. The client must now ROLLBACK or COMMIT the transaction by obtaining the IWgnImportConnectorDeferredCompletion interface. This enables the client to set additional data on the captured event depending on the values of smart tags. In this situation, the deferredCompletion parameter should not be NULL.

Error code

Any return value that fails the SUCCEEDED() macro, indicating that the message failed to be fully processed. In this situation, the deferredCompletion parameter should be NULL.

results

An interface allowing onUpdate() to retrieve the results of analyzing the message along with any Smart Tags. This interface can be used to obtain the IWgnSmartTag interface by calling GetInterface().

deferredCompletion

If the client supplied TRUE to the allowDeferredCompletion parameter of the ImportObjectAsync() method and CA DataMinder has an event pending being saved in its database, this interface will be populated and the implementer of the callback object must either Commit() or Rollback() the transaction. This need not be performed inline. It is permissable to AddRef() the deferredCompletion interface and invoke it after this method has returned.

Important!  CA DataMinder cannot progress the event until this occurs, which can lead to degraded performance if events are not committed or rolled back promptly.

When this method is invoked after a Commit() operation, the deferredCompletion parameter will be NULL, indicating that no further action is necessary.

Return values for onUpdate method

The implementer of the callback object should return S_OK from this method.