FaxRouteGetFile

A fax routing method calls the FaxRouteGetFile callback function to retrieve the name of a specific file from the fax file list associated with a received fax document.

BOOL WINAPI FaxRouteGetFile(
  DWORD JobId,           // fax job identifier 
  DWORD Index,           // file number of the requested file 
  LPWSTR FileNameBuffer, // pointer to the buffer that contains
                         //   the file name 
  LPDWORD RequiredSize   // pointer to the required buffer
                         //   size, in bytes 
);

Parameters

JobId

[in] Specifies a unique number that identifies the fax job that received the fax document. For information about fax jobs, see Fax Job Overview.

Index

[in] Specifies a unique number that identifies the requested file.

FileNameBuffer

[out] Pointer to a buffer that receives a null-terminated Unicode character string that contains the requested file name. For more information, see the following Remarks section.

RequiredSize

[out] Pointer to an unsigned DWORD variable that receives the required size, in bytes, of the buffer pointed to by the FileNameBuffer parameter. 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, call GetLastError.

Remarks

The fax routing method must call the FaxRouteGetFile function twice. The first time the routing method calls FaxRouteGetFile it must pass a NULL pointer in the FileNameBuffer parameter. The fax service sets the RequiredSize parameter to the size required for the FileNameBuffer. The fax routing method must allocate the memory required for the buffer from the heap specified by the FaxRouteInitialize function, and call FaxRouteGetFile again. The second time the routing method calls FaxRouteGetFile it must pass a valid pointer in the FileNameBuffer parameter.

The fax service passes a pointer to the FaxRouteGetFile callback function when the fax service calls FaxRouteInitialize. The service passes the pointer in a FAX_ROUTE_CALLBACKROUTINES structure.

The PFAXROUTEGETFILE data type is a pointer to a FaxRouteGetFile function.

For more information, see Fax File Lists.

Requirements

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

See Also

Fax Routing Extension Application Programming Interface Overview, Fax Routing Extension Functions, FAX_ROUTE_CALLBACKROUTINES, FaxRouteInitialize