FaxDevStartJob

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. Each fax service provider must export the FaxDevStartJob function.

BOOL WINAPI FaxDevStartJob(
  HLINE LineHandle,             // handle to the open line device
  DWORD DeviceId,               // TAPI line device identifier
  PHANDLE FaxHandle,            // pointer to fax handle
  HANDLE CompletionPortHandle,  // handle to an I/O completion port
  ULONG_PTR CompletionKey       // completion key value
);

Parameters

LineHandle

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

DeviceId

[in] Specifies the TAPI line device identifier associated with the fax job.

FaxHandle

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

CompletionPortHandle

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

CompletionKey

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

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

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

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

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, PostQueuedCompletionStatus, FaxDevEndJob, FaxDevSend, FaxDevReceive, FaxDevInitialize, FAX_DEV_STATUS