| Platform SDK: Fax Services |
The FaxInitializeEventQueue function creates a fax event queue for the calling fax client application. The queue enables the application to receive notifications of asynchronous events from the fax server. An application can specify how the fax server should inform the client application of events. The application can request that the fax server queue I/O completion packets to an I/O completion port, or it can specify notification messages.
BOOL WINAPI FaxInitializeEventQueue( HANDLE FaxHandle, // handle to the fax server HANDLE CompletionPort, // handle to an I/O completion port ULONG_PTR CompletionKey, // completion key value HWND hWnd, // handle to the notification window UINT MessageStart // window message base event number );
For information about I/O completion ports, see I/O Completion Ports.
This parameter is required for notification messages. This parameter must be equal to zero if you specify notification using I/O completion packets.
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_INVALID_PARAMETER | Both the hWnd and CompletionPort parameters are NULL, or both parameters are specified. |
| ERROR_INVALID_PARAMETER | The FaxHandle parameter is NULL; or the hWnd parameter is specified but the FaxHandle parameter does not specify a connection with a local fax server; or the MessageStart parameter specifies a message in the range below WM_USER. |
| ERROR_INVALID_DATA | The application called the FaxInitializeEventQueue function more than once during a fax service session. |
| ERROR_NOT_ENOUGH_MEMORY | An error occurred during memory allocation. |
A fax client application must call the FaxInitializeEventQueue function before calling GetQueuedCompletionStatus to retrieve the value to specify in the CompletionKey parameter. This value is useful to a message loop that retrieves I/O completion packets from multiple I/O completion ports, using calls to the WaitForMultipleObjects function. If you specify a different completion key for each I/O completion port, you can identify the completion port associated with the completion packet.
An application can call the GetQueuedCompletionStatus function to retrieve the queued I/O completion packet for a completed I/O operation. A call to GetQueuedCompletionStatus also returns a pointer to a variable that the function sets to the address of a FAX_EVENT structure. The structure is associated with the I/O completion packet of interest. Call the LocalFree function to free the memory allocated for the FAX_EVENT structure.
After a fax client application receives the FEI_FAXSVC_ENDED message, it will no longer receive fax events from the fax service. To resume receiving fax events, the application must call the FaxInitializeEventQueue function again when the fax service restarts. The application can determine if the fax service is running by using the service control manager. For more information, see FaxClose and Enabling an Application to Receive Notifications of Fax Events.
For a list of the asynchronous events that can occur within the fax server, see the FAX_EVENT topic.
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.
Fax Service Client Application Programming Interface Overview, Fax Service Client API Functions, FaxConnectFaxServer, FaxOpenPort, FaxClose, CreateIOCompletionPort, GetQueuedCompletionStatus, WaitForMultipleObjects, FAX_EVENT, LocalFree