Función phoneOpen (tapi.h)

Artículo
08/26/2023

La función phoneOpen abre el dispositivo telefónico especificado. Se puede abrir un dispositivo de teléfono mediante privilegios de propietario o privilegios de supervisión. Una aplicación que abre el teléfono con privilegios de propietario puede controlar las lámparas del teléfono, la pantalla, el timbre y los ganchoswitch o hookswitches. Una aplicación que abre el dispositivo telefónico con privilegios de monitor solo se notifica sobre los eventos que se producen en el teléfono, como los cambios de hookswitch o las pulsaciones de botón.

La propiedad de un dispositivo telefónico es exclusiva. En otras palabras, solo una aplicación puede tener un dispositivo telefónico abierto con privilegios de propietario a la vez. Sin embargo, el dispositivo telefónico se puede abrir varias veces con privilegios de monitor.

Sintaxis

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

Parámetros

hPhoneApp

Controle el registro de la aplicación con TAPI.

dwDeviceID

Identificador del dispositivo telefónico que se va a abrir.

lphPhone

Puntero a un controlador HPHONE que identifica el dispositivo de teléfono abierto. Use este identificador para identificar el dispositivo al invocar otras funciones de control telefónico.

dwAPIVersion

Número de versión de la API en el que la aplicación y la API de telefonía han acordado operar. Este número se obtiene de phoneNegotiateAPIVersion.

dwExtVersion

Número de versión de la extensión en el que la aplicación y el proveedor de servicios aceptan operar. Este número es cero si la aplicación no usa ninguna extensión. Este número se obtiene de phoneNegotiateExtVersion.

dwCallbackInstance

Datos de instancia de usuario pasados a la aplicación con cada mensaje. La API de telefonía no interpreta este parámetro.

dwPrivilege

Privilegio solicitado. Este parámetro usa una y solo una de las constantes de PHONEPRIVILEGE_.

Valor devuelto

Devuelve cero si la solicitud se realiza correctamente o un número de error negativo si se produce un error. Los valores devueltos posibles son:

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.

Comentarios

Al abrir un dispositivo telefónico con privilegios de monitor, la aplicación se envía mensajes cuando se producen eventos que cambian el estado del teléfono. Los mensajes enviados a la aplicación incluyen PHONE_BUTTON y PHONE_STATE. Este último proporciona una indicación del elemento de estado del teléfono que ha cambiado.

Al abrir un teléfono con privilegios de propietario, el dispositivo telefónico se puede manipular de maneras que afectan al estado del dispositivo telefónico. Una aplicación solo debe abrir un teléfono con privilegios de propietario si quiere manipular activamente el dispositivo telefónico y debe cerrar el dispositivo telefónico cuando termine para permitir que otras aplicaciones controlen el teléfono.

Cuando una aplicación abre un dispositivo telefónico, debe especificar la versión negociada de la API y, si quiere usar las extensiones del teléfono, la versión de extensión específica del dispositivo del teléfono. Este número de versión debe haberse obtenido con las funciones phoneNegotiateAPIVersion y phoneNegotiateExtVersion . La numeración de versiones permite la combinación y coincidencia de diferentes versiones de aplicación con diferentes versiones de API y versiones del proveedor de servicios.