FaxDevStartJob function (faxdev.h)

Article
10/13/2021

The fax service calls the FaxDevStartJob function to initialize a new fax job. The fax service also calls FaxDevStartJob to signal the beginning of each fax operation to the fax service provider (FSP). Each FSP must export the FaxDevStartJob function.

Syntax

BOOL FaxDevStartJob(
  [in]  HLINE     LineHandle,
  [in]  DWORD     DeviceId,
  [out] PHANDLE   FaxHandle,
  [in]  HANDLE    CompletionPortHandle,
  [in]  ULONG_PTR CompletionKey
);

Parameters

[in] LineHandle

Type: HLINE

Specifies a handle to the open line device associated with the fax job.

[in] DeviceId

Type: DWORD

Specifies the TAPI line device identifier associated with the fax job.

[out] FaxHandle

Type: PHANDLE

Pointer to a variable that receives a fax handle associated with the fax job. The FSP must set this handle to a meaningful value; this handle usually specifies a pointer to a block of memory with job-specific instance data.

[in] CompletionPortHandle

Type: HANDLE

Specifies a handle to an I/O completion port. For more information, see I/O Completion Ports.

[in] CompletionKey

Type: ULONG_PTR

Specifies a completion key value. The fax service provider should pass this opaque value to the PostQueuedCompletionStatus function.

Return value

Type: BOOL

If the function succeeds, the return value is nonzero.

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

Remarks

The FaxDevStartJob function provides an opportunity for the fax service provider to perform call setup.

The fax service calls FaxDevStartJob at the beginning of a new fax job and once for each fax operation. This is because each operation executes in a separate thread. It calls FaxDevStartJob just before the FaxDevSend function call for a fax send operation, and just before the FaxDevReceive function call for a fax receive operation. For more information, see Operating in a Multithreaded Environment.

The FSP should create an I/O completion packet and call the PostQueuedCompletionStatus function when the FSP changes its status. One example of a status change is when the FSP finishes receiving or sending fax transmission pages. The completion packet must be a FAX_DEV_STATUS structure. The FSP must allocate memory for the structure from the heap indicated by the HeapHandle parameter passed to the FaxDevInitialize function. The fax service provider must pass the size of the memory allocated to the dwNumberOfBytesTransferred parameter of the PostQueuedCompletionStatus method. The fax service frees any memory allocated for the completion packet structure.

The FSP should use the CompletionPortHandle and CompletionKey parameters to post completion packets for FSP status changes. This method of status notification optimizes performance because the fax service does not need to poll FSPs to obtain updated status information. For more information, see Creating a Completion Packet.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional, Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	faxdev.h