Función lineInitializeExA (tapi.h)

Artículo
11/20/2024

La función lineInitializeEx inicializa el uso de TAPI de la aplicación para su uso posterior de la abstracción de líneas. Registra el mecanismo de notificación especificado de la aplicación y devuelve el número de dispositivos de línea disponibles para la aplicación. Un dispositivo de línea es cualquier dispositivo que proporciona una implementación para las funciones con prefijo de línea en la API de telefonía.

Sintaxis

LONG lineInitializeExA(
  LPHLINEAPP               lphLineApp,
  HINSTANCE                hInstance,
  LINECALLBACK             lpfnCallback,
  LPCSTR                   lpszFriendlyAppName,
  LPDWORD                  lpdwNumDevs,
  LPDWORD                  lpdwAPIVersion,
  LPLINEINITIALIZEEXPARAMS lpLineInitializeExParams
);

Parámetros

lphLineApp

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 archivo ejecutable raíz del proceso (con fines de identificación de destinos de entrega de llamadas y prioridades de modo multimedia).

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 lineCallbackFunc). 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 de texto terminadanull 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 LINECALLINFO para indicar, de forma fácil de usar, qué aplicación se originó o aceptó originalmente o respondió a la llamada. Esta información puede ser útil para fines de registro de llamadas. Si lpszFriendlyAppName es NULL, el nombre de archivo del módulo de la aplicación se usa en su lugar (tal como lo devuelve la función GetModuleFileName).

lpdwNumDevs

Puntero a una DWORDubicación de tamaño. Tras completar correctamente esta solicitud, esta ubicación se rellena con el número de dispositivos de línea disponibles para la aplicación.

lpdwAPIVersion

Puntero a una DWORDubicación de tamaño. 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 lineNegotiateAPIVersion). 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 diferente de TAPI.

lpLineInitializeExParams

Puntero a una estructura de tipo LINEINITIALIZEEXPARAMS que contienen 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:

LINEERR_INVALAPPNAME, LINEERR_OPERATIONFAILED, LINEERR_INIFILECORRUPT, LINEERR_INVALPOINTER, LINEERR_REINIT, LINEERR_NOMEM, LINEERR_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 LINEINITIALIZEEXOPTION_USEHIDDENWINDOW en el miembro dwOptions de la estructura LINEINITIALIZEEXPARA 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 la lineInitializeEx o lineInitialize (para las aplicaciones TAPI versión 1.3 y 1.4) y subclases la ventana para que todos los mensajes publicados en él se controlan mediante un WNDPROC en sí mismo. 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 allineCallbackProc , un puntero al que la aplicación proporcionó como parámetro en su llamada a lineInitializeEx (o lineInitialize). 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 la función lineShutdown.

El mecanismo controlador de eventos se selecciona especificando LINEINITIALIZEEXOPTION_USEEVENT en el miembro dwOptions en la estructura LINEINITIALIZEEXPARAMS . 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 LINEINITIALIZEEXPARAMS. 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 lineGetMessage 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 lineShutdown. La aplicación no es necesaria para esperar al identificador de eventos que se crea; La aplicación podría optar por llamar a lineGetMessage y hacer que bloquee la espera de que se en cola un mensaje.

El mecanismo puerto de finalización se selecciona especificando LINEINITIALIZEEXOPTION_USECOMPLETION PUERTO en el miembro dwOptions en la estructura LINEINITIALIZEEXPARAMS . En este mecanismo, siempre que se deba enviar un evento de telefonía a la aplicación, TAPI lo envía mediante postQueuedCompletionStatus al puerto de finalización que la aplicación especificó en el miembro hCompletionPort en LINEINITIALIZEEXPARAMS, etiquetado con la clave de finalización que la aplicación especificó en el miembro dwCompletionKey en LINEINITIALIZEEXPARAMS. La aplicación debe haber creado previamente el puerto de finalización mediante CreateIoCompletionPort. La aplicación recupera eventos mediante GetQueuedCompletionStatus. Tras la devolución de getQueuedCompletionStatus, la aplicación tiene el dwCompletionKey especificado escrito en el DWORD de apuntado por el parámetro lpCompletionKey y un puntero a una estructura LINEMESSAGE devuelta a la ubicación a la que apunta lpOverlapped. Una vez que la aplicación ha procesado el evento, es responsabilidad de la aplicación llamar a LocalFree para liberar la memoria usada para contener la estructura LINEMESSAGE . 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 lineShutdown.

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 LINEERR_REINIT y se ha solicitado la reinicialización TAPI, por ejemplo, como resultado de agregar o quitar un proveedor de servicios de telefonía, solicitudes de lineInitializeEx se rechazan con este error hasta que la última aplicación cierra su uso de la API (mediante lineShutdown), en cuyo momento la nueva configuración se vuelve efectiva y las aplicaciones se vuelven a permitir que las aplicaciones llamen a lineInitializeEx.

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

La aplicación puede hacer referencia a dispositivos de línea individuales mediante identificadores de dispositivo de línea que van de cero a dwNumDevs menos uno. Una aplicación no debe suponer que estos dispositivos de línea son capaces de ninguna función TAPI determinada sin consultar primero sus funcionalidades de dispositivo lineGetDevCaps y lineGetAddressCaps.

Nota

El encabezado tapi.h define lineInitializeEx 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.