phoneOpen-Funktion (tapi.h)

Artikel
03/13/2024

Die PhoneOpen-Funktion öffnet das angegebene Telefongerät. Ein Telefongerät kann entweder mit Besitzer- oder Überwachungsberechtigungen geöffnet werden. Eine Anwendung, die das Telefon mit Besitzerberechtigung öffnet, kann die Lampen, die Anzeige, das Klingeln und den Hookswitch oder hookswitches des Telefons steuern. Eine Anwendung, die das Telefongerät mit Überwachungsberechtigung öffnet, wird nur über Ereignisse benachrichtigt, die auf dem Telefon auftreten, z. B. Hookswitch-Änderungen oder Tastendrücke.

Der Besitz eines Telefongeräts ist exklusiv. Mit anderen Worten, nur eine Anwendung kann gleichzeitig ein Telefongerät mit Besitzerberechtigungen geöffnet haben. Das Telefongerät kann jedoch mehrmals mit Überwachungsberechtigung geöffnet werden.

Syntax

LONG phoneOpen(
  HPHONEAPP hPhoneApp,
  DWORD     dwDeviceID,
  LPHPHONE  lphPhone,
  DWORD     dwAPIVersion,
  DWORD     dwExtVersion,
  DWORD_PTR dwCallbackInstance,
  DWORD     dwPrivilege
);

Parameter

hPhoneApp

Verarbeiten sie die Registrierung der Anwendung bei TAPI.

dwDeviceID

Id des zu öffnenden Telefongeräts.

lphPhone

Zeiger auf ein HPHONE-Handle, das das geöffnete Telefongerät identifiziert. Verwenden Sie dieses Handle, um das Gerät beim Aufrufen anderer Telefonsteuerungsfunktionen zu identifizieren.

dwAPIVersion

API-Versionsnummer, unter der die Anwendung und die Telefonie-API ihren Betrieb vereinbart haben. Diese Nummer wird von phoneNegotiateAPIVersion abgerufen.

dwExtVersion

Versionsnummer der Erweiterung, unter der die Anwendung und der Dienstanbieter dem Betrieb zustimmen. Diese Zahl ist null, wenn die Anwendung keine Erweiterungen verwendet. Diese Nummer wird von phoneNegotiateExtVersion abgerufen.

dwCallbackInstance

Benutzer instance Daten, die mit jeder Nachricht an die Anwendung zurückgegeben werden. Dieser Parameter wird nicht von der Telefonie-API interpretiert.

dwPrivilege

Berechtigung angefordert. Dieser Parameter verwendet nur eine der PHONEPRIVILEGE_ Konstanten.

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_ALLOCATED, PHONEERR_NODRIVER, PHONEERR_BADDEVICEID, PHONEERR_NOMEM, PHONEERR_INCOMPATIBLEAPIVERSION, PHONEERR_OPERATIONFAILED, PHONEERR_INCOMPATIBLEEXTVERSION, PHONEERR_OPERATIONUNAVAIL, PHONEERR_INVALAPPHANDLE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPOINTER, PHONEERR_UNINITIALIZED, PHONEERR_INVALPRIVILEGE, PHONEERR_REINIT, PHONEERR_INUSE, PHONEERR_NODEVICE, PHONEERR_INIFILECORRUPT.

Hinweise

Beim Öffnen eines Telefongeräts mit Überwachungsberechtigungen werden der Anwendung Nachrichten gesendet, wenn Ereignisse auftreten, die die status des Telefons ändern. Nachrichten, die an die Anwendung gesendet werden , umfassen PHONE_BUTTON und PHONE_STATE. Letzteres gibt einen Hinweis auf das geänderte status Element des Telefons.

Beim Öffnen eines Telefons mit Besitzerberechtigungen kann das Telefongerät auf eine Weise bearbeitet werden, die sich auf den Zustand des Telefongeräts auswirkt. Eine Anwendung sollte ein Telefon nur mit Besitzerberechtigung öffnen, wenn sie das Telefongerät aktiv bearbeiten möchte, und das Telefongerät sollte geschlossen werden, wenn sie fertig ist, damit andere Anwendungen das Telefon steuern können.

Wenn eine Anwendung ein Telefongerät öffnet, muss sie die ausgehandelte API-Version und, wenn sie die Telefonerweiterungen verwenden möchte, die gerätespezifische Erweiterungsversion des Telefons angeben. Diese Versionsnummer sollte mit den Funktionen phoneNegotiateAPIVersion und phoneNegotiateExtVersion abgerufen worden sein. Die Versionsnummerierung ermöglicht die Kombination und Übereinstimmung verschiedener Anwendungsversionen mit unterschiedlichen API-Versionen und Dienstanbieterversionen.