Función phoneInitialize (tapi.h)

Artículo
03/09/2024

La función phoneInitialize está obsoleta. Sigue exportando Tapi.dll y Tapi32.dll para la compatibilidad con versiones anteriores con aplicaciones que usan las versiones 1.3 y 1.4 de TAPI.

En su lugar, las aplicaciones que usan TAPI versión 2.0 o posterior deben usar phoneInitializeEx .

Para las versiones 1.4 y anteriores de TAPI: La función phoneInitialize inicializa el uso de TAPI de la aplicación para el uso posterior de las funciones telefónicas en la API de telefonía. Registra el mecanismo de notificación especificado de la aplicación y devuelve el número de dispositivos telefónicos que están disponibles para la aplicación.

Sintaxis

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

Parámetros

lphPhoneApp

Puntero a una ubicación que se rellena con el identificador de uso de la aplicación para TAPI.

hInstance

Identificador de instancia de la aplicación cliente o dll.

lpfnCallback

Dirección de una función de devolución de llamada que se invoca para determinar el estado y los eventos en el dispositivo telefónico.

lpszAppName

Puntero a una cadena terminada en null que contiene caracteres que se pueden mostrar. Si este parámetro no es NULL, contiene un nombre proporcionado por la aplicación de la aplicación. Este nombre se proporciona en la estructura PHONESTATUS para indicar, de forma fácil de usar, qué aplicación es el propietario actual del dispositivo telefónico. Esta información puede ser útil para fines de registro e informes de estado. Si lpszAppName es NULL, el nombre de archivo de la aplicación se usa en su lugar.

lpdwNumDevs

Puntero a DWORD. Esta ubicación se carga con el número de dispositivos telefónicos disponibles para la aplicación.

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

Comentarios

La aplicación puede hacer referencia a dispositivos telefónicos individuales mediante identificadores de dispositivo telefónico que van de cero a dwNumDevs menos uno. Una aplicación no debe suponer que estos dispositivos telefónicos son capaces de nada más allá de lo especificado por el subconjunto de telefonía asistida sin consultar primero sus funcionalidades de dispositivo con la función phoneGetDevCaps .

Las aplicaciones no deben invocar phoneInitialize sin abrir posteriormente un teléfono (al menos para la supervisión). Si la aplicación no está supervisando y no usa ningún dispositivo, debe llamar a phoneShutdown para que los recursos de memoria asignados por TAPI se puedan liberar si no son necesarios y TAPI sí se puede descargar de la memoria mientras no es necesario.

Otro motivo para realizar un phoneShutdown es que si un usuario cambia la configuración del dispositivo (agrega o quita una línea o teléfono), no hay forma de que TAPI notifique a una aplicación que tiene abierta una línea o un identificador de teléfono en el momento. Una vez realizada una reconfiguración, lo que provoca que se envíe un mensaje de PHONESTATE_REINIT, ninguna aplicación puede abrir un dispositivo hasta que todas las aplicaciones hayan realizado un phoneShutdown.

Si algún proveedor de servicios no se inicializa correctamente, se produce un error en la función phoneInitialize y devuelve el error indicado por el proveedor de servicios. Si se devuelve el valor de error PHONEERR_INVALPARAM, el parámetro hInstance especificado no es válido.