3.2.4.2.34.17 WaitForCompletion (Opnum 27)

The WaitForCompletion method blocks the caller for the specified time period or until the associated running report task (section 3.2.1.12.1) if any, completes, whichever occurs first.

 [id(FSRM_DISPID_REPORT_JOB | 0x04)] HRESULT WaitForCompletion(
   [in] long waitSeconds,
   [out, retval] VARIANT_BOOL* completed
 );

waitSeconds: Contains the maximum number of seconds the call will block before returning.

completed: Pointer to a VARIANT_BOOL variable that upon completion contains an indication of whether the report job has completed.

Return Values: The method MUST return zero on success, or a nonzero error code on failure.

Return value/code

Description

0x80070057

E_INVALIDARG

The waitSeconds parameter is not a valid value; the number of seconds to wait must be in the range of -1 through 2,147,483.

Upon receiving this message, the server MUST validate parameters:

  • Verify that waitSeconds is greater than "-2".

  • If there is no associated Running Report Job (section 3.2.1.5.1.3) in the Running Report Jobs Queue, the server SHOULD set completed to VARIANT_TRUE and return zero.

If any validation fails, the server MUST terminate processing and return a nonzero error code.

If there is an associated Running Report Job in the Running Report Jobs Queue, the server MUST monitor the instance's Running status element for a maximum of waitSeconds if waitSeconds is greater than -1, forever if waitSeconds equals -1, or until Running status is FsrmReportRunningStatus_NotRunning, whichever is sooner, or return a nonzero error code.

  • If this instance's Running status changes to FsrmReportRunningStatus_NotRunning before waitSeconds, the server MUST set completed to VARIANT_TRUE.

  • If this instance's Running status does not change to FsrmReportRunningStatus_NotRunning before waitSeconds, the server MUST set completed to VARIANT_FALSE.

To implement the timeout behaviour driven by the waitSeconds parameter, a compliant implementation of this routine can simply poll for the task completion for a maximum period of time, or use an internal timer, or mix polling with a timer driven architecture.