lineInitialize-Funktion (tapi.h)

Artikel
08/26/2023

Die lineInitialize-Funktion ist veraltet. Sie wird weiterhin von Tapi.dll exportiert und Tapi32.dll, um die Abwärtskompatibilität mit Anwendungen zu gewährleisten, die die API-Versionen 1.3 und 1.4 verwenden.

Anwendungen mit API-Version 2.0 oder höher müssen stattdessen lineInitializeEx verwenden.

Für TAPI-Versionen 1.4 und früher: Die lineInitialize-Funktion initialisiert die Verwendung von Tapi.dll der Anwendung für die spätere Verwendung der Zeilenstraktion. Die Funktion 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 TAPI bereitstellt.

Syntax

LONG lineInitialize(
  LPHLINEAPP   lphLineApp,
  HINSTANCE    hInstance,
  LINECALLBACK lpfnCallback,
  LPCSTR       lpszAppName,
  LPDWORD      lpdwNumDevs
);

Parameter

lphLineApp

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

hInstance

Instanzhandle der Clientanwendung oder DLL.

lpfnCallback

Adresse einer Rückruffunktion, die aufgerufen wird, um status und Ereignisse auf dem Leitungsgerät, adressen oder Aufrufen zu bestimmen. Weitere Informationen finden Sie unter lineCallbackFunc.

lpszAppName

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 Die Anrufprotokollierung nützlich sein. Wenn lpszAppNameNULL ist, wird stattdessen der Dateiname der Anwendung verwendet.

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.

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_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_REINIT, LINEERR_NODRIVER, LINEERR_NODEVICE, LINEERR_NOMEM, LINEERR_NOMULTIPLEINSTANCE.

Hinweise

Wenn LINEERR_REINIT zurückgegeben wird und eine TAPI-Neuinitialisierung angefordert wurde (z. B. als Ergebnis des Hinzufügens oder Entfernens eines Telefoniedienstanbieters), werden lineInitialize-Anforderungen mit diesem Fehler abgelehnt, bis die letzte Anwendung ihre Verwendung der API heruntergefahren hat (mithilfe von lineShutdown). Zu diesem Zeitpunkt wird die neue Konfiguration wirksam, und Anwendungen dürfen erneut lineInitialize aufrufen. 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 in der Lage sind, etwas über das in der Telefonie-Teilmenge "Basic" angegebene Maß hinaus zu verwenden, ohne zuvor ihre Gerätefunktionen mithilfe von lineGetDevCaps und lineGetAddressCaps abfragen zu müssen.

Anwendungen sollten lineInitialize nicht aufrufen, ohne anschließend eine Zeile zu öffnen (zumindest zur Überwachung). Wenn die Anwendung keine Geräte überwacht und keine Geräte verwendet, sollte lineShutdown aufgerufen werden, damit von Tapi.dll zugeordnete Arbeitsspeicherressourcen freigegeben werden können, wenn sie nicht benötigt werden, und Tapi.dll selbst aus dem Arbeitsspeicher entladen werden kann, wenn sie nicht benötigt werden.

Ein weiterer Grund für die Durchführung eines lineShutdowns ist, dass, wenn ein Benutzer die Gerätekonfiguration ändert (eine Leitung oder ein Telefon hinzufügt oder entfernt), keine Möglichkeit für TAPI gibt, eine Anwendung zu benachrichtigen, die zu diesem Zeitpunkt ein Leitungs- oder Telefonhandle geöffnet hat. Nachdem eine Neukonfiguration erfolgt ist und eine LINEDEVSTATE_REINIT Nachricht gesendet wird, können keine Anwendungen ein Gerät öffnen, bis alle Anwendungen einen lineShutdown durchgeführt haben. Wenn ein Dienstanbieter nicht ordnungsgemäß initialisiert werden kann, schlägt diese Funktion fehl und gibt den vom Dienstanbieter angegebenen Fehler zurück.

Auf allen TAPI-Plattformen ist lineInitialize mit der Option LINEINITIALIZEEXOPTION_USEHIDDENWINDOW gleichbedeutend mit lineInitializeEx .