FaxDevReportStatus

The fax service calls the FaxDevReportStatus function to query a fax service provider for status information about an individual active fax operation, or for status information after a failed fax operation. Each fax service provider must export the FaxDevReportStatus function.

BOOL WINAPI FaxDevReportStatus(
  HANDLE FaxHandle,              // fax handle 
  PFAX_DEV_STATUS FaxStatus,     // pointer to status information structure
  DWORD FaxStatusSize,           // structure buffer size, in bytes
  LPDWORD FaxStatusSizeRequired  // pointer to provider calculation
);

Parameters

FaxHandle

[in] Specifies a fax handle returned by the FaxDevStartJob function that is associated with the fax job.

FaxStatus

[out] Pointer to a FAX_DEV_STATUS structure that receives status and identification information. This parameter can also be a NULL pointer. For more information, see the following Remarks section.

FaxStatusSize

[in] Specifies the size, in bytes, of the buffer pointed to by the FaxStatus parameter.

FaxStatusSizeRequired

[out] Pointer to a variable that receives the calculated size, in bytes, of the buffer required to hold a FAX_DEV_STATUS structure. For more information, see the following Remarks section.

Return Values

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero. To get extended error information, the fax service calls GetLastError.

Remarks

To obtain status information for the operation, the FaxDevReportStatus function is called asynchronously on an execution thread that is independent of the fax operation. It is usually necessary to synchronize access by multiple threads. For more information, see Synchronizing Execution of Multiple Threads.

If the FaxStatusSize parameter is equal to zero, and FaxStatus is a NULL pointer, the fax service provider must calculate the size, in bytes, of the buffer required to hold a FAX_DEV_STATUS structure. The fax service provider must return this value in the FaxStatusSizeRequired parameter. The fax service will then allocate the required memory. It will also return both the memory size in the FaxStatusSize parameter, and a pointer to that memory in the FaxStatus parameter.

The fax service provider must set all of the members of the FAX_DEV_STATUS structure with status information for the active fax operation. The fax service allocates the memory for the strings pointed to by the CSI, CallerId, and RoutingInfo members. The size of the memory the service allocates is equal to sizeof(FAX_DEV_STATUS) + FAXDEVREPORTSTATUS_SIZE. The fax service provider must place the strings in the block of memory that immediately follows the FAX_DEV_STATUS structure. The CSI, CallerId, and RoutingInfo members must point to the location of the strings in the memory block.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Unsupported.
  Header: Declared in faxdev.h.
  Import Library: User-defined.

See Also

Fax Service Provider Application Programming Interface Overview, Fax Service Provider Functions, FAX_DEV_STATUS, FaxDevStartJob