PFAXINITIALIZEEVENTQUEUE callback function (winfax.h)
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.
Syntax
PFAXINITIALIZEEVENTQUEUE Pfaxinitializeeventqueue;
BOOL Pfaxinitializeeventqueue(
[in] HANDLE FaxHandle,
[in] HANDLE CompletionPort,
[in] ULONG_PTR CompletionKey,
[in] HWND hWnd,
[in] UINT MessageStart
)
{...}
Parameters
[in] FaxHandle
Type: HANDLE
Specifies a fax server handle returned by a call to the FaxConnectFaxServer function.
[in] CompletionPort
Type: HANDLE
Specifies a valid handle to an I/O completion port returned by a call to the CreateIoCompletionPort function. This parameter is required for notification using I/O completion packets. This parameter must be NULL if you specify notification messages.
For information about I/O completion ports, see I/O Completion Ports.
[in] CompletionKey
Type: ULONG_PTR
Specifies a variable that contains a completion key value the fax server includes in each I/O completion packet. This parameter is required for notification using I/O completion packets. This parameter must be NULL if you specify notification messages. For more information, see the following Remarks section.
[in] hWnd
Type: HWND
Handle to a window of the fax client application to notify when an asynchronous event occurs. This parameter is required for notification messages. This parameter must be NULL if you specify notification using I/O completion packets.
[in] MessageStart
Type: UINT
Specifies an unsigned integer that identifies the application's base window message. The application can use this number to determine whether to process the message as a fax server event. For more information, see the FAX_EVENT topic.
This parameter is required for notification messages. This parameter must be equal to zero if you specify notification using I/O completion packets.
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, call GetLastError. GetLastError can return one of the following errors.
| Return code | Description |
|---|---|
|
Both the hWnd and CompletionPort parameters are NULL, or both parameters are specified. |
|
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. |
|
The application called the FaxInitializeEventQueue function more than once during a fax service session in Windows 2000. More than one call is supported in Windows XP and Windows Server 2003. |
|
An error occurred during memory allocation. |
Remarks
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.
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.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 2000 Professional [desktop apps only] |
| Minimum supported server | Windows 2000 Server [desktop apps only] |
| Target Platform | Windows |
| Header | winfax.h |
See also
Fax Service Client API Functions