PFAXINITIALIZEEVENTQUEUE-Rückruffunktion (winfax.h)

Artikel
08/27/2023

Die FaxInitializeEventQueue-Funktion erstellt eine Faxereigniswarteschlange für die aufrufende Faxclientanwendung. Die Warteschlange ermöglicht es der Anwendung, Benachrichtigungen über asynchrone Ereignisse vom Faxserver zu empfangen.

Syntax

PFAXINITIALIZEEVENTQUEUE Pfaxinitializeeventqueue;

BOOL Pfaxinitializeeventqueue(
  [in] HANDLE FaxHandle,
  [in] HANDLE CompletionPort,
  [in] ULONG_PTR CompletionKey,
  [in] HWND hWnd,
  [in] UINT MessageStart
)
{...}

Parameter

[in] FaxHandle

Typ: HANDLE

Gibt ein Faxserverhandle an, das von einem Aufruf der FaxConnectFaxServer-Funktion zurückgegeben wird.

[in] CompletionPort

Typ: HANDLE

Gibt ein gültiges Handle für einen E/A-Abschlussport an, der von einem Aufruf der CreateIoCompletionPort-Funktion zurückgegeben wird. Dieser Parameter ist für Benachrichtigungen mithilfe von E/A-Vervollständigungspaketen erforderlich. Dieser Parameter muss NULL sein, wenn Sie Benachrichtigungen angeben.

Informationen zu E/A-Vervollständigungsports finden Sie unter E/A-Abschlussports.

[in] CompletionKey

Typ: ULONG_PTR

Gibt eine Variable an, die einen Vervollständigungsschlüsselwert enthält, den der Faxserver in jedes E/A-Vervollständigungspaket einschließt. Dieser Parameter ist für Benachrichtigungen mithilfe von E/A-Vervollständigungspaketen erforderlich. Dieser Parameter muss NULL sein, wenn Sie Benachrichtigungen angeben. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[in] hWnd

Typ: HWND

Handle für ein Fenster der Faxclientanwendung, um zu benachrichtigen, wenn ein asynchrones Ereignis auftritt. Dieser Parameter ist für Benachrichtigungen erforderlich. Dieser Parameter muss NULL sein, wenn Sie eine Benachrichtigung mithilfe von E/A-Vervollständigungspaketen angeben.

[in] MessageStart

Typ: UINT

Gibt eine ganze Zahl ohne Vorzeichen an, die die Basisfenstermeldung der Anwendung identifiziert. Die Anwendung kann diese Nummer verwenden, um zu bestimmen, ob die Nachricht als Faxserverereignis verarbeitet werden soll. Weitere Informationen finden Sie im Thema FAX_EVENT .

Dieser Parameter ist für Benachrichtigungen erforderlich. Dieser Parameter muss gleich 0 sein, wenn Sie die Benachrichtigung mithilfe von E/A-Vervollständigungspaketen angeben.

Rückgabewert

Typ: BOOL

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf. GetLastError kann einen der folgenden Fehler zurückgeben.

Rückgabecode	Beschreibung
ERROR_INVALID_PARAMETER	Sowohl der hWnd - als auch der CompletionPort-Parameter sind NULL, oder beide Parameter werden angegeben.
ERROR_INVALID_PARAMETER	Der FaxHandle-Parameter ist NULL; oder der hWnd-Parameter wird angegeben, aber der Parameter FaxHandle gibt keine Verbindung mit einem lokalen Faxserver an. oder der MessageStart-Parameter gibt eine Nachricht im Bereich unterhalb WM_USER an.
ERROR_INVALID_DATA	Die Anwendung hat die FaxInitializeEventQueue-Funktion während einer Faxdienstsitzung in Windows 2000 mehrmals aufgerufen. In Windows XP und Windows Server 2003 werden mehrere Aufrufe unterstützt.
ERROR_NOT_ENOUGH_MEMORY	Während der Speicherbelegung ist ein Fehler aufgetreten.

Hinweise

Eine Anwendung kann angeben, wie der Faxserver die Clientanwendung über Ereignisse informieren soll. Die Anwendung kann anfordern, dass die E/A-Vervollständigungspakete des Faxservers an einen E/A-Abschlussport gesendet werden, oder sie kann Benachrichtigungen angeben.

Eine Faxclientanwendung muss die FaxInitializeEventQueue-Funktion aufrufen, bevor GetQueuedCompletionStatus aufgerufen wird, um den wert abzurufen, der im CompletionKey-Parameter angegeben werden soll. Dieser Wert ist nützlich für eine Nachrichtenschleife, die E/A-Vervollständigungspakete von mehreren E/A-Abschlussports mithilfe von Aufrufen der WaitForMultipleObjects-Funktion abruft . Wenn Sie einen anderen Vervollständigungsschlüssel für jeden E/A-Abschlussport angeben, können Sie den Abschlussport identifizieren, der dem Abschlusspaket zugeordnet ist.

Eine Anwendung kann die GetQueuedCompletionStatus-Funktion aufrufen, um das E/A-Abschlusspaket in der Warteschlange für einen abgeschlossenen E/A-Vorgang abzurufen. Ein Aufruf von GetQueuedCompletionStatus gibt auch einen Zeiger auf eine Variable zurück, die die Funktion auf die Adresse einer FAX_EVENT-Struktur festlegt. Die Struktur ist dem E/A-Abschlusspaket von Interesse zugeordnet. Rufen Sie die LocalFree-Funktion auf, um den für die FAX_EVENT-Struktur zugewiesenen Arbeitsspeicher freizugeben.

Nachdem eine Faxclientanwendung die FEI_FAXSVC_ENDED Nachricht empfangen hat, empfängt sie keine Faxereignisse mehr vom Faxdienst. Um den Empfang von Faxereignissen fortzusetzen, muss die Anwendung die FaxInitializeEventQueue-Funktion erneut aufrufen, wenn der Faxdienst neu gestartet wird. Die Anwendung kann mithilfe des Dienststeuerungs-Managers ermitteln, ob der Faxdienst ausgeführt wird. Weitere Informationen finden Sie unter FaxClose und Aktivieren einer Anwendung zum Empfangen von Benachrichtigungen zu Faxereignissen.

Eine Liste der asynchronen Ereignisse, die innerhalb des Faxservers auftreten können, finden Sie im Thema FAX_EVENT .

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winfax.h