Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Die lineInitializeEx-Funktion initialisiert die Verwendung von TAPI der Anwendung für die nachfolgende Verwendung der Zeilenstraktion. Er registriert den angegebenen Benachrichtigungsmechanismus der Anwendung und gibt die Anzahl der zeilenspezifischen Geräte zurück, die für die Anwendung verfügbar sind. Ein Leitungsgerät ist jedes Gerät, das eine Implementierung für die linepräfixierten Funktionen in der Telefonie-API bereitstellt.
Syntax
LONG lineInitializeExW(
LPHLINEAPP lphLineApp,
HINSTANCE hInstance,
LINECALLBACK lpfnCallback,
LPCWSTR lpszFriendlyAppName,
LPDWORD lpdwNumDevs,
LPDWORD lpdwAPIVersion,
LPLINEINITIALIZEEXPARAMS lpLineInitializeExParams
);
Parameter
lphLineApp
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 (zum Identifizieren von Anrufübergabezielen und Medienmodusprioritäten).
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 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-terminated text 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 LINECALLINFO- Struktur angegeben, um auf benutzerfreundliche Weise anzugeben, welche Anwendung stammt oder 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 GetModuleFileNamezurückgegeben).
lpdwNumDevs
Zeiger auf eine DWORD--Größe. Nach erfolgreichem Abschluss dieser Anforderung wird dieser Standort mit der Anzahl der Zeilengeräte gefüllt, die der Anwendung zur Verfügung stehen.
lpdwAPIVersion
Zeiger auf eine DWORD--Größe. Die Anwendung muss diese DWORD-initialisieren, bevor sie diese Funktion auf die höchste API-Version aufruft, die sie unterstützt (z. B. derselbe Wert, der an dwAPIHighVersion Parameter von lineNegotiateAPIVersionü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 anderen Version von TAPI installiert wurde.
lpLineInitializeExParams
Zeiger auf eine Struktur vom Typ LINEINITIALIZEEXPARAMS 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:
LINEERR_INVALAPPNAME, LINEERR_OPERATIONFAILED, LINEERR_INIFILECORRUPT, LINEERR_INVALPOINTER, LINEERR_REINIT, LINEERR_NOMEM, LINEERR_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 LINEINITIALIZEEXOPTION_USEHIDDENWINDOW im dwOptions Member im 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 (für TAPI-Version 1.3- und 1.4-Anwendungen) 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, indem die lineCallbackProc-aufgerufen wird, ein Zeiger, auf den die Anwendung als Parameter im Aufruf von lineInitializeEx (oder lineInitialize) bereitgestellt wurde. 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 lineShutdown--Funktion zerstört.
Der Ereignishandle-Mechanismus wird ausgewählt, indem LINEINITIALIZEEXOPTION_USEEVENT im dwOptions Member im LINEINITIALIZEEXPARAMS- 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 LINEINITIALIZEEXPARAMSzurü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 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, das von TAPI während der lineShutdown--Funktion zerstört wird. Die Anwendung ist nicht erforderlich, um auf das erstellte Ereignishandle zu warten; die Anwendung kann stattdessen lineGetMessage- aufrufen und blockieren, bis eine Nachricht in die Warteschlange gestellt wird.
Der Vervollständigungsportmechanismus wird ausgewählt, indem LINEINITIALIZEEXOPTION_USECOMPLETION PORT im dwOptions Member im LINEINITIALIZEEXPARAMS- Struktur angegeben wird. In diesem Mechanismus muss jedes Mal, wenn ein Telefonieereignis an die Anwendung gesendet werden muss, TAPI sendet sie mithilfe PostQueuedCompletionStatus- an den Abschlussport, den die Anwendung im hCompletionPort Member in LINEINITIALIZEEXPARAMSmit dem Abschlussschlüssel markiert hat, den die Anwendung im dwCompletionKey Member in LINEINITIALIZEEXPARAMSangegeben hat. Die Anwendung muss den Abschlussport zuvor mit CreateIoCompletionPort-erstellt haben. Die Anwendung ruft Ereignisse mithilfe GetQueuedCompletionStatus-ab. Wenn sie von GetQueuedCompletionStatus-zurückgegeben wird, hat die Anwendung das angegebene dwCompletionKey- in die DWORD- geschrieben, auf die der lpCompletionKey-Parameter verweist, und ein Zeiger auf eine LINEMESSAGE- Struktur, die an die Position zurückgegeben wurde, die von lpOverlappedzurückgegeben wurde. Nachdem die Anwendung das Ereignis verarbeitet hat, liegt es in der Verantwortung der Anwendung, LocalFree- aufzurufen, um den Speicher freizugeben, der verwendet wird, um die LINEMESSAGE- 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 lineShutdownaufgerufen 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 LINEERR_REINIT zurückgegeben wird und TAPI-Erneutitialisierung angefordert wurde, Beispielsweise werden lineInitializeEx- Anforderungen durch Hinzufügen oder Entfernen eines Telefoniedienstanbieters mit diesem Fehler abgelehnt, bis die letzte Anwendung die Verwendung der API beendet (mit lineShutdown), zu dem die neue Konfiguration wirksam wird und Anwendungen erneut lineInitializeExaufrufen dürfen.
Wenn der LINEERR_INVALPARAM Fehlerwert zurückgegeben wird, ist der angegebene hInstance Parameter ungültig.
Die Anwendung kann auf einzelne Zeilengeräte verweisen, indem Sie Zeilengeräte-IDs verwenden, die zwischen Null und dwNumDevs minus 1 reichen. Eine Anwendung sollte nicht davon ausgehen, dass diese Leitungsgeräte in der Lage sind, eine bestimmte TAPI-Funktion auszuführen, ohne zuerst ihre Gerätefunktionen durch lineGetDevCaps und lineGetAddressCapszu abfragen.
Anmerkung
Der header tapi.h 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.
Anforderungen
| Anforderung | Wert |
|---|---|
| Zielplattform- | Fenster |
| Header- | tapi.h |
| Library | Tapi32.lib |
| DLL- | Tapi32.dll |