Función phoneInitializeExA (tapi.h)

Artículo
11/20/2024

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 de teléfono 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 la 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 los mecanismos de notificación de eventos "controlador de eventos" o "puerto de finalización".

lpszFriendlyAppName

Puntero a un cadena terminada en nullque 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 forma fácil de usar, qué aplicación tiene 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 (tal y como devuelve la función GetModuleFileName).

lpdwNumDevs

Puntero a unDWORD de . 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 unDWORD de . La aplicación debe inicializar este 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 a dwAPIHighVersion parámetro de phoneNegotiateAPIVersion). No se deben usar 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 usados 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.

Observaciones

Las aplicaciones deben seleccionar uno de los tres mecanismos mediante los cuales 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 de en la estructura PHONEINITIALIZEEXPARA MS. 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 el función phoneInitializeEx y subclases la ventana para que todos los mensajes publicados en él se controlan mediante un WNDPROC en TAPI. Cuando TAPI tiene un mensaje para entregar a la aplicación, TAPI envía un mensaje a la ventana oculta. Cuando se recibe el mensaje (que solo puede ocurrir cuando la aplicación llama a la función Windows GetMessage), 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 al 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 periódicamente para evitar retrasar el procesamiento de eventos de telefonía. TapI destruye la ventana oculta durante el función phoneShutdown.
El mecanismo controlador de eventos de se selecciona especificando PHONEINITIALIZEEXOPTION_USEEVENT en el miembro dwOptions en la estructura PHONEINITIALIZEEXPARAMS de . En este mecanismo, TAPI crea un objeto de evento en nombre de la aplicación y devuelve un identificador al objeto del miembro hEvent de 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 indica 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 controlador de eventos se cierra y el objeto de evento destruido por TAPI durante la función phoneShutdown . La aplicación no es necesaria para esperar al identificador de eventos que se crea; La aplicación podría elegir en su lugar llamar a phoneGetMessage y hacer que bloquee la espera de que se pone en cola un mensaje.
El mecanismo puerto de finalización de se selecciona especificando PHONEINITIALIZEEXOPTION_USECOMPLETION PUERTO en el miembro dwOptions del PHONEINITIALIZEEXPARAMS. En este mecanismo, siempre que se deba 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 de PHONEINITIALIZEEXPARAMS, etiquetada con la clave de finalización especificada 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 la devolución de GetQueuedCompletionStatus , la aplicación tiene el dwCompletionKey especificado escrito en el DWORD apuntado por 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 controlador 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 la secuencia. Esto no se debe a la secuencia de entrega de eventos de TAPI, pero se debe a la segmentación de tiempo de subprocesos o la ejecución de subprocesos en procesadores independientes.

Si se devuelve PHONEERR_REINIT y se ha solicitado la reinicialización de TAPI (por ejemplo, como resultado de agregar o quitar un proveedor de servicios de telefonía), solicitudes de 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 de dispositivo 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 neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.