Función phoneInitializeExA (tapi.h)

Artículo
08/26/2023

La función phoneInitializeEx inicializa el uso de TAPI de la aplicación para su uso posterior de la abstracción del teléfono. Registra el mecanismo de notificación especificado de la aplicación y devuelve el número de dispositivos telefónicos disponibles para la aplicación. Un dispositivo telefónico es cualquier dispositivo que proporcione una implementación para las funciones con prefijo telefónico en la API de telefonía.

Sintaxis

LONG phoneInitializeExA(
  LPHPHONEAPP               lphPhoneApp,
  HINSTANCE                 hInstance,
  PHONECALLBACK             lpfnCallback,
  LPCSTR                    lpszFriendlyAppName,
  LPDWORD                   lpdwNumDevs,
  LPDWORD                   lpdwAPIVersion,
  LPPHONEINITIALIZEEXPARAMS lpPhoneInitializeExParams
);

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. La aplicación o dll puede pasar NULL para este parámetro, en cuyo caso TAPI usa el identificador de módulo del ejecutable raíz del proceso.

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 de línea, las direcciones o las llamadas, cuando la aplicación usa el método "ventana oculta" de notificación de eventos (para obtener más información, vea phoneCallbackFunc). Este parámetro se omite y debe establecerse en NULL cuando la aplicación elige usar el "identificador de eventos" o los mecanismos de notificación de eventos de "puerto de finalización".

lpszFriendlyAppName

Puntero a una cadena terminada en null que solo contiene caracteres que se pueden mostrar. Si este parámetro no es NULL, contiene un nombre proporcionado por la aplicación para la aplicación. Este nombre se proporciona en la estructura PHONESTATUS para indicar, de una manera fácil de usar, que la aplicación tiene la propiedad del dispositivo telefónico. Si lpszFriendlyAppName es NULL, el nombre de archivo del módulo de la aplicación se usa en su lugar (como devuelve la función GetModuleFileName).

lpdwNumDevs

Puntero a un DWORD. Tras completar correctamente esta solicitud, esta ubicación se rellena con el número de dispositivos telefónicos disponibles para la aplicación.

lpdwAPIVersion

Puntero a un DWORD. La aplicación debe inicializar esta DWORD, antes de llamar a esta función, a la versión de API más alta que está diseñada para admitir (por ejemplo, el mismo valor que pasaría al parámetro dwAPIHighVersion de phoneNegotiateAPIVersion). No se deben utilizar valores artificialmente altos; el valor debe establecerse con precisión. TAPI traduce los mensajes o estructuras más recientes en valores o formatos admitidos por la versión de la aplicación. Tras completar correctamente esta solicitud, esta ubicación se rellena con la versión de API más alta compatible con TAPI, lo que permite a la aplicación detectar y adaptarse a haber sido instalado en un sistema con una versión anterior de TAPI.

lpPhoneInitializeExParams

Puntero a una estructura de tipo PHONEINITIALIZEEXPARAMS que contiene parámetros adicionales utilizados para establecer la asociación entre la aplicación y TAPI (en concreto, el mecanismo de notificación de eventos seleccionado de la aplicación y los parámetros asociados).

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_OPERATIONFAILED, PHONEERR_INIFILECORRUPT, PHONEERR_INVALPOINTER, PHONEERR_REINIT, PHONEERR_NOMEM, PHONEERR_INVALPARAM.

Comentarios

Las aplicaciones deben seleccionar uno de los tres mecanismos por los que TAPI notifica a la aplicación de eventos de telefonía: Ventana oculta, Controlador de eventos o Puerto de finalización.

El mecanismo ventana oculta se selecciona especificando PHONEINITIALIZEEXOPTION_USEHIDDENWINDOW en el miembro dwOptions en la estructura PHONEINITIALIZEEXPARAMS . En este mecanismo (que es el único mecanismo disponible para tapi versión 1.x aplicaciones), TAPI crea una ventana en el contexto de la aplicación durante la función phoneInitializeEx y subclases la ventana para que todos los mensajes publicados en ella se controlan mediante un WNDPROC en tapi. Cuando TAPI tiene un mensaje para entregar a la aplicación, TAPI publica un mensaje en la ventana oculta. Cuando se recibe el mensaje (que solo puede ocurrir cuando la aplicación llama a la función GetMessage de Windows), Windows cambia el contexto de proceso a la de la aplicación e invoca el WNDPROC en TAPI. A continuación, TAPI entrega el mensaje a la aplicación llamando a phoneCallbackFunc, un puntero al que la aplicación proporcionó como parámetro en su llamada a phoneInitializeEx (o phoneInitialize, para las aplicaciones TAPI versión 1.3 y 1.4). Este mecanismo requiere que la aplicación tenga una cola de mensajes (que no es deseable para los procesos de servicio) y para atender a esa cola regularmente para evitar retrasar el procesamiento de eventos de telefonía. TapI destruye la ventana oculta durante la función phoneShutdown .
El mecanismo de identificador de eventos se selecciona especificando PHONEINITIALIZEEXOPTION_USEEVENT en el miembro dwOptions en la estructura PHONEINITIALIZEEXPARAMS . En este mecanismo, TAPI crea un objeto de evento en nombre de la aplicación y devuelve un identificador al objeto del miembro hEvent en PHONEINITIALIZEEXPARAMS. La aplicación no debe manipular este evento de ninguna manera (por ejemplo, no debe llamar a SetEvent, ResetEvent, CloseHandle, etc.) o resultados de comportamiento no definidos; La aplicación solo puede esperar en este evento mediante funciones como WaitForSingleObject o MsgWaitForMultipleObjects. TAPI señala este evento cada vez que una notificación de eventos de telefonía está pendiente para la aplicación; la aplicación debe llamar a phoneGetMessage para capturar el contenido del mensaje. TAPI restablece el evento cuando no hay ningún evento pendiente. El identificador de evento se cierra y el objeto de evento destruido por TAPI durante la función phoneShutdown . La aplicación no es necesaria para esperar en el identificador de eventos que se crea; la aplicación podría elegir en su lugar llamar a phoneGetMessage y hacer que se bloquee esperando a que se pone en cola un mensaje.
El mecanismo puerto de finalización se selecciona especificando PHONEINITIALIZEEXOPTION_USECOMPLETION PUERTO en el miembro dwOptions de la estructura PHONEINITIALIZEEXPARAMS . En este mecanismo, cada vez que es necesario enviar un evento de telefonía a la aplicación, TAPI lo envía a la aplicación mediante PostQueuedCompletionStatus al puerto de finalización que la aplicación especificó en el miembro hCompletionPort en PHONEINITIALIZEEXPARAMS, etiquetada con la clave de finalización que la aplicación especificó en el miembro dwCompletionKey en PHONEINITIALIZEEXPARAMS. La aplicación debe haber creado previamente el puerto de finalización mediante CreateIoCompletionPort. Las aplicaciones recuperan eventos mediante GetQueuedCompletionStatus. Tras volver desde GetQueuedCompletionStatus, la aplicación tiene el dwCompletionKey especificado escrito en el DWORD al que apunta el parámetro lpCompletionKey y un puntero a una estructura PHONEMESSAGE devuelta a la ubicación a la que apunta lpOverlapped. Una vez que la aplicación haya procesado el evento, la aplicación debe llamar a LocalFree para liberar la memoria usada para contener la estructura PHONEMESSAGE . Dado que la aplicación creó el puerto de finalización (lo que le permite compartirse con otros fines), la aplicación debe cerrarla; la aplicación no debe cerrar el puerto de finalización hasta después de llamar a phoneShutdown.

Cuando una aplicación multiproceso usa el mecanismo de identificador de eventos y más de un subproceso está esperando el identificador, o el mecanismo de notificación del puerto de finalización y más de un subproceso está esperando en el puerto, es posible que los eventos de telefonía se procesen fuera de secuencia. Esto no se debe a la secuencia de entrega de eventos de TAPI, pero se debe a la segmentación de tiempo de los subprocesos o la ejecución de subprocesos en procesadores independientes.

Si se devuelve PHONEERR_REINIT y se ha solicitado la reinicialización tapi (por ejemplo, como resultado de agregar o quitar un proveedor de servicios de telefonía), las solicitudes phoneInitializeEx se rechazan con este error hasta que la última aplicación cierra su uso de la API (mediante phoneShutdown). En ese momento, la nueva configuración se hace efectiva y las aplicaciones se vuelven a permitir que las aplicaciones llamen a phoneInitializeEx.

Si se devuelve el valor de error PHONEERR_INVALPARAM, el parámetro hInstance especificado no es válido.

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 cualquier función TAPI determinada sin consultar primero sus funcionalidades del dispositivo por phoneGetDevCaps.

Nota

El encabezado tapi.h define phoneInitializeEx como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.