Platform SDK: Fax Services

FaxGetPageData

The FaxGetPageData function returns to a fax client application the first page of data for a fax job. The fax job must be an outbound job, but it can be queued or active. The function returns data in the Tagged Image File Format, Class F for facsimile (TIFF 6.0 Class F) format.

BOOL WINAPI FaxGetPageData(
  HANDLE FaxHandle,    // handle to the fax server
  DWORD JobId,         // fax job identifier
  LPBYTE *Buffer,      // buffer to receive first page of data
  LPDWORD BufferSize,  // size of buffer, in bytes
  LPDWORD ImageWidth,  // page image width, in pixels
  LPDWORD ImageHeight  // page image height, in pixels
);

Parameters

FaxHandle
[in] Specifies a fax server handle returned by a call to the FaxConnectFaxServer function.
JobId
[in] Specifies a unique number that identifies the fax job associated with the page of data.
Buffer
[out] Pointer to the address of a buffer to receive the first page of data in the fax document. For information about memory allocation, see the following Remarks section.
BufferSize
[out] Pointer to a DWORD variable to receive the size of the buffer, in bytes, pointed to by the Buffer parameter.
ImageWidth
[out] Pointer to a DWORD variable to receive the width, in pixels, of the fax image.
ImageHeight
[out] Pointer to a DWORD variable to receive the height, in pixels, of the fax image.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError can return one of the following errors.

Error code Description
ERROR_ACCESS_DENIED Access is denied. FAX_JOB_QUERY access is required.
ERROR_INVALID_PARAMETER One or all of the Buffer, BufferSize, ImageWidth, ImageHeight, or FaxHandle parameters are NULL.
ERROR_NOT_ENOUGH_MEMORY An error occurred during memory allocation.
ERROR_INVALID_DATA The fax job identified by the JobId parameter is not an outgoing fax transmission; the job must be specified with the JT_SEND job type.

Remarks

A fax client application can call the FaxGetPageData function for administrative purposes, to display a thumbnail sketch of the fax documents in the fax queue.

The fax service creates fax documents as Tagged Image File Format, Class F for facsimile (TIFF Class F) files based on the TIFF 6.0 specification. The FaxGetPageData function returns a TIFF data stream that has a Modified Modified READ (MMR) two-dimensional encoding data compression format. The calling application must decode the data stream. For more information, see Fax Image Format.

The FaxGetPageData function allocates the memory required for the Buffer parameter. An application must call the FaxFreeBuffer function to deallocate the resources associated with this parameter.

For more information, see Displaying Documents in the Fax Job Queue and Freeing Fax Resources.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable with BackOffice Small Business Server.
  Header: Declared in Winfax.h.
  Library: Included as a resource in Winfax.dll.
  Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Fax Service Client Application Programming Interface Overview, Fax Service Client API Functions, FaxConnectFaxServer, FaxFreeBuffer, FaxStartPrintJob, FaxPrintCoverPage