lineInitializeExA-Funktion (tapi.h)

Artikel
03/02/2024

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

Syntax

LONG lineInitializeExA(
  LPHLINEAPP               lphLineApp,
  HINSTANCE                hInstance,
  LINECALLBACK             lpfnCallback,
  LPCSTR                   lpszFriendlyAppName,
  LPDWORD                  lpdwNumDevs,
  LPDWORD                  lpdwAPIVersion,
  LPLINEINITIALIZEEXPARAMS lpLineInitializeExParams
);

Parameter

lphLineApp

Zeiger auf einen Speicherort, der mit dem Anwendungshandle 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 (zum Identifizieren von Aufrufübergabezielen und Medienmodusprioritäten).

lpfnCallback

Adresse einer Rückruffunktion, die aufgerufen wird, um status und Ereignisse auf dem Leitungsgerät, den Adressen oder Aufrufen zu bestimmen, wenn die Anwendung die Methode "ausgeblendetes Fenster" der Ereignisbenachrichtigung verwendet (weitere Informationen finden Sie unter lineCallbackFunc). Dieser Parameter wird ignoriert und sollte auf NULL festgelegt werden, wenn die Anwendung die Ereignisbenachrichtigungsmechanismen "Ereignishandle" oder "Abschlussport" verwendet.

lpszFriendlyAppName

Zeiger auf eine NULL-endende Textzeichenfolge, die nur anzeigbare 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 LINECALLINFO-Struktur angegeben, um auf benutzerfreundliche Weise anzugeben, welche Anwendung ursprünglich den Anruf angenommen oder angenommen hat. Diese Informationen können für Anrufprotokollierungszwecke nützlich sein. Wenn lpszFriendlyAppNameNULL ist, wird stattdessen der Moduldateiname der Anwendung verwendet (wie von der Funktion GetModuleFileName zurückgegeben).

lpdwNumDevs

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

lpdwAPIVersion

Zeiger auf einen DWORD-Speicherort. Die Anwendung muss dieses DWORD initialisieren, bevor diese Funktion aufgerufen wird, für die höchste API-Version, die sie unterstützen soll (z. B. den gleichen Wert, den sie an den dwAPIHighVersion-Parameter von lineNegotiateAPIVersion ü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 anderen Version von TAPI installiert wurde.

lpLineInitializeExParams

Zeiger auf eine Struktur vom Typ LINEINITIALIZEEXPARAMS mit zusätzlichen Parametern, die verwendet werden, um die Zuordnung zwischen der Anwendung und TAPI (insbesondere den ausgewählten Ereignisbenachrichtigungsmechanismus der Anwendung und die zugehörigen Parameter) herzustellen.

Rückgabewert

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

LINEERR_INVALAPPNAME, LINEERR_OPERATIONFAILED, LINEERR_INIFILECORRUPT, LINEERR_INVALPOINTER, LINEERR_REINIT, LINEERR_NOMEM, LINEERR_INVALPARAM.

Hinweise

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 LINEINITIALIZEEXOPTION_USEHIDDENWINDOW im dwOptions-Element in der LINEINITIALIZEEXPARAMS-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 LineInitializeEx - oder lineInitialize-Funktion (für TAPI-Anwendungen version 1.3 und 1.4) und unterklassigt das Fenster, sodass alle an das Objekt 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 dann die Nachricht an die Anwendung, indem lineCallbackProc aufgerufen wird, ein Zeiger, auf den die Anwendung in ihrem Aufruf von lineInitializeEx (oder lineInitialize) 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 zu vermeiden, dass die Verarbeitung von Telefonieereignissen verzögert wird. Das ausgeblendete Fenster wird von TAPI während der lineShutdown-Funktion zerstört.

Der Ereignishandlemechanismus wird ausgewählt, indem LINEINITIALIZEEXOPTION_USEEVENT im dwOptions-Element in der LINEINITIALIZEEXPARAMS-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 LINEINITIALIZEEXPARAMS zurück. Die Anwendung darf dieses Ereignis in keiner 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, wenn eine Telefonereignisbenachrichtigung für die Anwendung aussteht; Die Anwendung muss lineGetMessage 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 von TAPI während der lineShutdown-Funktion zerstört. Die Anwendung muss nicht auf das erstellte Ereignishandle warten. Die Anwendung könnte stattdessen lineGetMessage aufrufen und blockieren lassen, bis eine Nachricht in die Warteschlange eingereiht wird.

Der Abschlussportmechanismus wird ausgewählt, indem LINEINITIALIZEEXOPTION_USECOMPLETION PORT im dwOptions-Element in der LINEINITIALIZEEXPARAMS-Struktur angegeben wird. In diesem Mechanismus sendet TAPI jedes Mal, wenn ein Telefonieereignis an die Anwendung gesendet werden muss, es mithilfe von PostQueuedCompletionStatus an den Abschlussport, den die Anwendung im hCompletionPort-Member in LINEINITIALIZEEXPARAMS angegeben hat, mit dem Abschlussschlüssel gekennzeichnet, den die Anwendung im dwCompletionKey-Member in LINEINITIALIZEEXPARAMS angegeben hat. Die Anwendung muss zuvor den Abschlussport mithilfe von CreateIoCompletionPort erstellt haben. Die Anwendung ruft Ereignisse mithilfe von GetQueuedCompletionStatus ab. Nach der Rückkehr von GetQueuedCompletionStatus verfügt die Anwendung über den angegebenen dwCompletionKey, der vom lpCompletionKey-Parameter in das DWORD geschrieben wurde, und einen Zeiger auf eine LINEMESSAGE-Struktur, die an die Position zurückgegeben wird, auf die von lpOverlapped verwiesen wird. Nachdem die Anwendung das Ereignis verarbeitet hat, liegt es in der Verantwortung der Anwendung , LocalFree aufzurufen, um den Arbeitsspeicher freizugeben, der für die LINEMESSAGE-Struktur verwendet wird. Da die Anwendung den Abschlussport 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 lineShutdown schließen.

Wenn eine Multithreadanwendung den Ereignishandlemechanismus verwendet und mehr als ein Thread auf das Handle wartet, oder wenn der Vervollständigungsport-Benachrichtigungsmechanismus auf den Port wartet und mehr als ein Thread auf den Port wartet, ist es möglich, dass 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 die Zeitslicing von Threads oder die Ausführung von Threads auf separaten Prozessoren verursacht.

Wenn LINEERR_REINIT zurückgegeben wird und die TAPI-Neuinitialisierung angefordert wurde, z. B. als Ergebnis des Hinzufügens oder Entfernens eines Telefoniedienstanbieters, werden lineInitializeEx-Anforderungen mit diesem Fehler abgelehnt, bis die letzte Anwendung ihre Verwendung der API heruntergefahren hat (mithilfe von lineShutdown), zu dem die neue Konfiguration wirksam wird und Anwendungen erneut lineInitializeEx aufrufen dürfen.

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

Die Anwendung kann mithilfe von Zeilengerätebezeichnern von null bis dwNumDevs minus 1 auf einzelne Leitungsgeräte verweisen. Eine Anwendung sollte nicht davon ausgehen, dass diese Leitungsgeräte eine bestimmte TAPI-Funktion ausführen können, ohne zuvor ihre Gerätefunktionen von lineGetDevCaps und lineGetAddressCaps abfragen zu müssen.

Hinweis

Der tapi.h-Header definiert lineInitializeEx 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.