phoneInitialize-Funktion (tapi.h)

Artikel
08/26/2023

Die phoneInitialize-Funktion ist veraltet. Es wird weiterhin von Tapi.dll exportiert und Tapi32.dll zur Abwärtskompatibilität mit Anwendungen mit TAPI-Versionen 1.3 und 1.4.

Anwendungen, die TAPI Version 2.0 oder höher verwenden, müssen stattdessen phoneInitializeEx verwenden.

Für TAPI-Versionen 1.4 und früher: Die phoneInitialize-Funktion initialisiert die Verwendung von TAPI durch die Anwendung für die spätere Verwendung der Telefonfunktionen in der Telefonie-API. Es registriert den angegebenen Benachrichtigungsmechanismus der Anwendung und gibt die Anzahl der Telefongeräte zurück, die für die Anwendung verfügbar sind.

Syntax

LONG phoneInitialize(
  LPHPHONEAPP   lphPhoneApp,
  HINSTANCE     hInstance,
  PHONECALLBACK lpfnCallback,
  LPCSTR        lpszAppName,
  LPDWORD       lpdwNumDevs
);

Parameter

lphPhoneApp

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 Telefongerät zu bestimmen.

lpszAppName

Zeiger auf eine NULL-endende Zeichenfolge, die anzeigbare Zeichen enthält. Wenn dieser Parameter nicht NULL ist, enthält er einen von der Anwendung bereitgestellten Namen der Anwendung. Dieser Name wird in der PHONESTATUS-Struktur angegeben, um auf benutzerfreundliche Weise anzugeben, welche Anwendung der aktuelle Besitzer des Telefongeräts ist. Diese Informationen können für Protokollierungs- und status Berichtszwecke nützlich sein. Wenn lpszAppNameNULL ist, wird stattdessen der Dateiname der Anwendung verwendet.

lpdwNumDevs

Zeiger auf DWORD. Dieser Speicherort wird mit der Anzahl der für die Anwendung verfügbaren Telefongeräte geladen.

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_INIFILECORRUPT, PHONEERR_INVALPOINTER, PHONEERR_NOMEM, PHONEERR_OPERATIONFAILED, PHONEERR_REINIT, PHONEERR_RESOURCEUNAVAIL, PHONEERR_NODEVICE, PHONEERR_NODRIVER, PHONEERR_INVALPARAM

Hinweise

Die Anwendung kann mithilfe von Bezeichnern von Telefongeräten von null bis dwNumDevs minus 1 auf einzelne Telefongeräte verweisen. Eine Anwendung sollte nicht davon ausgehen, dass diese Telefongeräte in der Lage sind, etwas über das in der Teilmenge der unterstützten Telefonie angegebene Menge hinaus auszuführen, ohne zuvor ihre Gerätefunktionen mit der phoneGetDevCaps-Funktion abfragen zu müssen.

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

Ein weiterer Grund für die Durchführung eines phoneShutdowns ist, dass es für TAPI keine Möglichkeit gibt, eine Anwendung zu benachrichtigen, die zu diesem Zeitpunkt ein Leitungs- oder Telefonhandle geöffnet hat, wenn ein Benutzer die Gerätekonfiguration ändert (indem eine Leitung oder ein Telefon hinzugefügt oder entfernt wird). Nachdem eine Neukonfiguration erfolgt ist und eine PHONESTATE_REINIT Nachricht gesendet wird, können keine Anwendungen ein Gerät öffnen, bis alle Anwendungen einen phoneShutdown ausgeführt haben.

Wenn ein Dienstanbieter nicht ordnungsgemäß initialisiert werden kann, schlägt die phoneInitialize-Funktion fehl und gibt den vom Dienstanbieter angegebenen Fehler zurück. Wenn der PHONEERR_INVALPARAM Fehlerwert zurückgegeben wird, ist der angegebene hInstance-Parameter ungültig.