phoneInitializeExA-Funktion (tapi.h)

Artikel
08/26/2023

Die phoneInitializeEx-Funktion initialisiert die Verwendung von TAPI für die spätere Verwendung der Telefonabstraktion durch die Anwendung. Es registriert den angegebenen Benachrichtigungsmechanismus der Anwendung und gibt die Anzahl der für die Anwendung verfügbaren Telefongeräte zurück. Ein Telefongerät ist jedes Gerät, das eine Implementierung für die Funktionen mit Telefonpräfix in der Telefonie-API bereitstellt.

Syntax

LONG phoneInitializeExA(
  LPHPHONEAPP               lphPhoneApp,
  HINSTANCE                 hInstance,
  PHONECALLBACK             lpfnCallback,
  LPCSTR                    lpszFriendlyAppName,
  LPDWORD                   lpdwNumDevs,
  LPDWORD                   lpdwAPIVersion,
  LPPHONEINITIALIZEEXPARAMS lpPhoneInitializeExParams
);

Parameter

lphPhoneApp

Zeiger auf einen Speicherort, der mit dem Verwendungshandle der Anwendung für TAPI gefüllt ist.

hInstance

Instanzhandle der Clientanwendung oder DLL. Die Anwendung oder DLL kann NULL für diesen Parameter übergeben. In diesem Fall verwendet TAPI das Modulhandle der ausführbaren Stammdatei des Prozesses.

lpfnCallback

Adresse einer Rückruffunktion, die aufgerufen wird, um status und Ereignisse auf dem Zeilengerät, adressen oder Aufrufen zu bestimmen, wenn die Anwendung die Methode "Hidden Window" der Ereignisbenachrichtigung verwendet (weitere Informationen finden Sie unter phoneCallbackFunc). Dieser Parameter wird ignoriert und sollte auf NULL festgelegt werden, wenn die Anwendung die Ereignisbenachrichtigungsmechanismen "Ereignishandle" oder "Vervollständigungsport" verwendet.

lpszFriendlyAppName

Zeiger auf eine NULL-Zeichenfolge, die nur anzeigebare Zeichen enthält. Wenn dieser Parameter nicht NULL ist, enthält er einen von der Anwendung bereitgestellten Namen für die Anwendung. Dieser Name wird in der PHONESTATUS-Struktur angegeben, um auf benutzerfreundliche Weise anzugeben, welche Anwendung den Besitz des Telefongeräts hat. Wenn lpszFriendlyAppNameNULL ist, wird stattdessen der Moduldateiname der Anwendung verwendet (wie von der Funktion GetModuleFileName zurückgegeben).

lpdwNumDevs

Zeiger auf ein DWORD. Nach erfolgreichem Abschluss dieser Anforderung wird dieser Standort mit der Anzahl der für die Anwendung verfügbaren Telefongeräte gefüllt.

lpdwAPIVersion

Zeiger auf ein DWORD. Die Anwendung muss dieses DWORD initialisieren, bevor sie diese Funktion aufruft, in der höchsten API-Version, die sie unterstützen soll (z. B. denselben Wert, den sie an den dwAPIHighVersion-Parameter von phoneNegotiateAPIVersion übergeben würde). Künstlich hohe Werte dürfen nicht verwendet werden; der Wert muss genau festgelegt werden. TAPI übersetzt alle neueren Nachrichten oder Strukturen in Werte oder Formate, die von der Version der Anwendung unterstützt werden. Nach erfolgreichem Abschluss dieser Anforderung wird dieser Speicherort mit der höchsten API-Version gefüllt, die von TAPI unterstützt wird, sodass die Anwendung erkennen und anpassen kann, dass sie auf einem System mit einer älteren Version von TAPI installiert wurde.

lpPhoneInitializeExParams

Zeiger auf eine Struktur vom Typ PHONEINITIALIZEEXPARAMS mit zusätzlichen Parametern, die zum Herstellen der Zuordnung zwischen der Anwendung und TAPI (insbesondere des ausgewählten Ereignisbenachrichtigungsmechanismus der Anwendung und der zugeordneten Parameter) verwendet werden.

Rückgabewert

Gibt null zurück, wenn die Anforderung erfolgreich ist, oder eine negative Fehlernummer, wenn ein Fehler auftritt. Mögliche Rückgabewerte sind:

PHONEERR_INVALAPPNAME, PHONEERR_OPERATIONFAILED, PHONEERR_INIFILECORRUPT, PHONEERR_INVALPOINTER, PHONEERR_REINIT, PHONEERR_NOMEM, PHONEERR_INVALPARAM.

Hinweise

Anwendungen müssen einen von drei Mechanismen auswählen, mit denen TAPI die Anwendung von Telefonieereignissen benachrichtigt: Ausgeblendetes Fenster, Ereignishandle oder Vervollständigungsport.

Der Mechanismus Für ausgeblendetes Fenster wird ausgewählt, indem PHONEINITIALIZEEXOPTION_USEHIDDENWINDOW im dwOptions-Element in der PHONEINITIALIZEEXPARAMS-Struktur angegeben wird. In diesem Mechanismus (der einzige Mechanismus, der für TAPI Version 1 verfügbar ist.x Anwendungen) erstellt TAPI während der phoneInitializeEx-Funktion ein Fenster im Kontext der Anwendung und unterklassigt das Fenster, sodass alle an ihn gesendeten Nachrichten von einem WNDPROC in TAPI selbst verarbeitet werden. Wenn TAPI eine Nachricht an die Anwendung zu übermitteln hat, sendet TAPI eine Nachricht an das ausgeblendete Fenster. Wenn die Nachricht empfangen wird (was nur auftreten kann, wenn die Anwendung die Windows GetMessage-Funktion aufruft), wechselt Windows den Prozesskontext in den der Anwendung und ruft den WNDPROC in TAPI auf. TAPI übermittelt die Nachricht dann an die Anwendung, indem sie phoneCallbackFunc aufruft, einen Zeiger, auf den die Anwendung in ihrem Aufruf von phoneInitializeEx (oder phoneInitialize für TAPI-Anwendungen der Versionen 1.3 und 1.4) als Parameter bereitgestellt hat. Dieser Mechanismus erfordert, dass die Anwendung über eine Nachrichtenwarteschlange verfügt (was für Dienstprozesse nicht wünschenswert ist) und diese Warteschlange regelmäßig zu warten, um eine Verzögerung der Verarbeitung von Telefonieereignissen zu vermeiden. Das ausgeblendete Fenster wird während der phoneShutdown-Funktion von TAPI zerstört.
Der Ereignishandlemechanismus wird ausgewählt, indem PHONEINITIALIZEEXOPTION_USEEVENT im dwOptions-Member in der PHONEINITIALIZEEXPARAMS-Struktur angegeben wird. In diesem Mechanismus erstellt TAPI ein Ereignisobjekt im Namen der Anwendung und gibt ein Handle an das Objekt im hEvent-Member in PHONEINITIALIZEEXPARAMS zurück. Die Anwendung darf dieses Ereignis nicht in irgendeiner Weise bearbeiten (z. B. darf nicht SetEvent, ResetEvent, CloseHandle usw.) oder nicht definierte Verhaltensergebnisse aufrufen. Die Anwendung kann nur mit Funktionen wie WaitForSingleObject oder MsgWaitForMultipleObjects auf dieses Ereignis warten. TAPI signalisiert dieses Ereignis immer dann, wenn eine Telefonieereignisbenachrichtigung für die Anwendung aussteht. Die Anwendung muss phoneGetMessage aufrufen, um den Inhalt der Nachricht abzurufen. Das Ereignis wird von TAPI zurückgesetzt, wenn keine Ereignisse ausstehen. Das Ereignishandle wird geschlossen, und das Ereignisobjekt wird während der phoneShutdown-Funktion von TAPI zerstört. Die Anwendung muss nicht auf das erstellte Ereignishandle warten. Die Anwendung könnte stattdessen phoneGetMessage aufrufen und blockieren, bis eine Nachricht in die Warteschlange eingereiht wird.
Der Vervollständigungsportmechanismus wird ausgewählt, indem PHONEINITIALIZEEXOPTION_USECOMPLETION PORT im dwOptions-Element in der PHONEINITIALIZEEXPARAMS-Struktur angegeben wird. Bei diesem Mechanismus sendet TAPI jedes Mal, wenn ein Telefonieereignis an die Anwendung gesendet werden muss, es mithilfe von PostQueuedCompletionStatus an den Vervollständigungsport, den die Anwendung im hCompletionPort-Member in PHONEINITIALIZEEXPARAMS angegeben hat, und wird mit dem Vervollständigungsschlüssel markiert, den die Anwendung im dwCompletionKey-Member in PHONEINITIALIZEEXPARAMS angegeben hat. Die Anwendung muss zuvor den Vervollständigungsport mithilfe von CreateIoCompletionPort erstellt haben. Die Anwendungen rufen Ereignisse mithilfe von GetQueuedCompletionStatus ab. Nach der Rückgabe von GetQueuedCompletionStatus verfügt die Anwendung über den angegebenen dwCompletionKey-Wert , der in den DWORD-Parameter geschrieben wird, auf den der lpCompletionKey-Parameter verweist, und ein Zeiger auf eine PHONEMESSAGE-Struktur , die an die Position zurückgegeben wird, auf die von lpOverlapped verwiesen wird. Nachdem die Anwendung das Ereignis verarbeitet hat, muss die Anwendung LocalFree aufrufen, um den Arbeitsspeicher freizugeben, der zum Enthalten der PHONEMESSAGE-Struktur verwendet wird. Da die Anwendung den Vervollständigungsport erstellt hat (wodurch er für andere Zwecke freigegeben werden kann), muss die Anwendung ihn schließen. die Anwendung darf den Abschlussport erst nach dem Aufruf von phoneShutdown schließen.

Wenn eine Multithreadanwendung den Ereignishandlemechanismus verwendet und mehr als ein Thread auf das Handle oder den Vervollständigungsportbenachrichtigungsmechanismus wartet und mehr als ein Thread auf den Port wartet, können Telefonieereignisse außerhalb der Sequenz verarbeitet werden. Dies ist nicht auf die Abfolge der Übermittlung von Ereignissen von TAPI zurückzuführen, sondern wird durch das Zeitslicing von Threads oder die Ausführung von Threads auf separaten Prozessoren verursacht.

Wenn PHONEERR_REINIT zurückgegeben wird und die TAPI-Neuinitialisierung angefordert wurde (z. B. durch Hinzufügen oder Entfernen eines Telefoniedienstanbieters), werden phoneInitializeEx-Anforderungen mit diesem Fehler abgelehnt, bis die letzte Anwendung die Verwendung der API heruntergefahren hat (mit phoneShutdown). Zu diesem Zeitpunkt wird die neue Konfiguration wirksam, und Anwendungen dürfen erneut phoneInitializeEx aufrufen.

Wenn der PHONEERR_INVALPARAM Fehlerwert zurückgegeben wird, ist der angegebene hInstance-Parameter ungültig.

Die Anwendung kann auf einzelne Telefongeräte verweisen, indem sie Telefongerätebezeichner verwendet, die von null bis dwNumDevs minus 1 liegen. Eine Anwendung sollte nicht davon ausgehen, dass diese Telefongeräte eine bestimmte TAPI-Funktion ausführen können, ohne zuvor ihre Gerätefunktionen per phoneGetDevCaps abfragen zu müssen.

Hinweis

Der tapi.h-Header definiert phoneInitializeEx als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.