phoneInitializeExA-Funktion (tapi.h)

Artikel
11/20/2024

Die phoneInitializeEx--Funktion initialisiert die Verwendung von TAPI für die nachfolgende Verwendung der Telefonstraktion. Er 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 telefonpräfixierten Funktionen 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 eine Position, die 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 Leitungsgerät, adressen oder Aufrufen zu bestimmen, wenn die Anwendung die Methode "ausgeblendetes Fenster" 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 "Abschlussport" verwendet.

lpszFriendlyAppName

Zeiger auf eine null-terminated string that contains only displayable characters. Wenn dieser Parameter nicht NULL-ist, enthält er einen anwendungsspezifischen Namen für die Anwendung. Dieser Name wird in der PHONESTATUS- Struktur angegeben, um auf benutzerfreundliche Weise anzugeben, welche Anwendung über den Besitz des Telefongeräts verfügt. Wenn lpszFriendlyAppNameNULL-ist, wird stattdessen der Moduldateiname der Anwendung verwendet (wie von der Funktion GetModuleFileNamezurü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 diese DWORD-initialisieren, bevor sie diese Funktion aufruft, auf die höchste API-Version, die sie unterstützen soll (z. B. derselbe Wert, der an dwAPIHighVersion Parameter von phoneNegotiateAPIVersionübergeben würde). Künstliche 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, wodurch 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 verwendet werden (insbesondere der ausgewählte Ereignisbenachrichtigungsmechanismus der Anwendung und zugehörige Parameter).

Rückgabewert

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

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

Bemerkungen

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

Der mechanismus Ausgeblendetes Fenster wird ausgewählt, indem PHONEINITIALIZEEXOPTION_USEHIDDENWINDOW im dwOptions-Element im PHONEINITIALIZEEXPARAMS- Struktur angegeben wird. In diesem Mechanismus (der einzige Mechanismus, der für TAPI Version 1 verfügbar ist.x Anwendungen) erstellt TAPI ein Fenster im Kontext der Anwendung während der phoneInitializeEx--Funktion und unterklassen das Fenster, sodass alle darin bereitgestellten Nachrichten von einem WNDPROC in TAPI selbst behandelt werden. Wenn TAPI eine Nachricht enthält, die an die Anwendung gesendet werden soll, sendet TAPI eine Nachricht an das ausgeblendete Fenster. Wenn die Nachricht empfangen wird (was nur passieren kann, wenn die Anwendung die Windows GetMessage--Funktion aufruft), wechselt Windows den Prozesskontext zu der Anwendung und ruft die WNDPROC in TAPI auf. TAPI übermittelt dann die Nachricht an die Anwendung durch Aufrufen der phoneCallbackFunc, einen Zeiger, auf den die Anwendung als Parameter in ihrem Aufruf an phoneInitializeEx (oder phoneInitialize, für TAPI-Version 1.3- und 1.4-Anwendungen bereitgestellt hat). Dieser Mechanismus erfordert, dass die Anwendung über eine Nachrichtenwarteschlange (die für Dienstprozesse nicht wünschenswert ist) und die Warteschlange regelmäßig verarbeiten, um eine Verzögerung der Verarbeitung von Telefonieereignissen zu vermeiden. Das ausgeblendete Fenster wird von TAPI während der phoneShutdown Funktion zerstört.
Der Ereignishandle Mechanismus wird ausgewählt, indem PHONEINITIALIZEEXOPTION_USEEVENT im dwOptions Member im PHONEINITIALIZEEXPARAMS- Struktur angegeben wird. In diesem Mechanismus erstellt TAPI ein Ereignisobjekt im Auftrag der Anwendung und gibt ein Handle an das Objekt im hEvent Member in PHONEINITIALIZEEXPARAMSzurück. Die Anwendung darf dieses Ereignis nicht auf irgendeine Weise bearbeiten (z. B. darf SetEvent, ResetEvent-, CloseHandle-usw.) oder nicht definierte Verhaltensergebnisse nicht aufrufen; die Anwendung kann nur mit Funktionen wie WaitForSingleObject oder MsgWaitForMultipleObjectsauf dieses Ereignis warten. TAPI signalisiert dieses Ereignis, 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, das von TAPI während der phoneShutdown-Funktion zerstört wird. Die Anwendung ist nicht erforderlich, um auf das erstellte Ereignishandle zu warten; Die Anwendung kann stattdessen phoneGetMessage- anrufen und blockieren, bis eine Nachricht in die Warteschlange gestellt wird.
Der mechanismus Abschlussport wird ausgewählt, indem PHONEINITIALIZEEXOPTION_USECOMPLETION PORT im dwOptions Member im PHONEINITIALIZEEXPARAMS Struktur angegeben wird. In diesem Mechanismus muss jedes Mal, wenn ein Telefonieereignis an die Anwendung gesendet werden muss, TAPI sendet die Anwendung mithilfe PostQueuedCompletionStatus- an den Abschlussport, den die Anwendung im hCompletionPort Member in PHONEINITIALIZEEXPARAMSmit dem Abschlussschlüssel markiert hat, den die Anwendung im dwCompletionKey Member in PHONEINITIALIZEEXPARAMSangegeben hat. Die Anwendung muss den Abschlussport zuvor mit CreateIoCompletionPort-erstellt haben. Die Anwendungen rufen Ereignisse mithilfe GetQueuedCompletionStatus-ab. Nach der Rückgabe von GetQueuedCompletionStatushat die Anwendung das angegebene dwCompletionKey in den DWORD- geschrieben, auf den der lpCompletionKey-Parameter verweist, und ein Zeiger auf eine PHONEMESSAGE- Struktur, die an die Position zurückgegeben wurde, auf die durch lpOverlappedverwiesen wird. Nachdem die Anwendung das Ereignis verarbeitet hat, muss die Anwendung LocalFree- aufrufen, um den Speicher freizugeben, der verwendet wird, um die PHONEMESSAGE- Struktur zu enthalten. Da die Anwendung den Abschlussport erstellt hat (wodurch sie für andere Zwecke freigegeben werden kann), muss sie von der Anwendung geschlossen werden; die Anwendung darf den Abschlussport erst schließen, nachdem phoneShutdownaufgerufen wurde.

Wenn eine Multithreadanwendung den Ereignishandle-Mechanismus verwendet und mehr als ein Thread auf das Handle wartet oder der Benachrichtigungsmechanismus für den Abschlussport und mehr als ein Thread auf den Port wartet, ist es möglich, dass Telefonieereignisse außerhalb der Sequenz verarbeitet werden. Dies liegt nicht an der Abfolge der Übermittlung von Ereignissen von TAPI, sondern würde durch das Zeitslicing von Threads oder die Ausführung von Threads auf separaten Prozessoren verursacht.

Wenn PHONEERR_REINIT zurückgegeben wird und tapi reitialisierung angefordert wurde (z. B. aufgrund des Hinzufügens oder Entfernens eines Telefoniedienstanbieters), werden phoneInitializeEx- anforderungen mit diesem Fehler abgelehnt, bis die letzte Anwendung die Verwendung der API heruntergefahren hat (mithilfe phoneShutdown). Zu diesem Zeitpunkt wird die neue Konfiguration wirksam, und Anwendungen dürfen erneut phoneInitializeExanrufen.

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äte-IDs verwenden, die zwischen Null und dwNumDevs minus 1 reichen. Eine Anwendung sollte nicht davon ausgehen, dass diese Telefongeräte in der Lage sind, eine bestimmte TAPI-Funktion auszuführen, ohne zuerst ihre Gerätefunktionen durch phoneGetDevCapsabfragen zu müssen.

Anmerkung

Der header tapi.h 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 Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.