Función lineInitializeExA (tapi.h)

Artículo
03/02/2024

La función lineInitializeEx inicializa el uso de TAPI de la aplicación para su uso posterior de la abstracción de línea. 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 ejecutable raíz del proceso (para identificar los destinos de entrega de llamadas y las prioridades del 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 "identificador de eventos" o "puerto de finalización".

lpszFriendlyAppName

Puntero a una cadena de texto 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 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 y como devuelve la función GetModuleFileName).

lpdwNumDevs

Puntero a una ubicación de tamaño DWORD. Una vez completada 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 ubicación de tamaño 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 lineNegotiateAPIVersion). 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. Una vez completada 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 contiene parámetros adicionales que se usan 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.

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, Identificador de eventos o Puerto de finalización.

El mecanismo Ventana oculta se selecciona especificando LINEINITIALIZEEXOPTION_USEHIDDENWINDOW en el miembro dwOptions de la estructura LINEINITIALIZEEXPARAMS . 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 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 controle 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 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 mediante una llamada a lineCallbackProc, 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 el servicio que se pone en cola regularmente 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 de 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 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 lineGetMessage para capturar el contenido del mensaje. TAPI restablece el evento cuando no hay ningún evento pendiente. El identificador de eventos se cierra y el objeto de evento destruido por TAPI durante la función lineShutdown . No es necesario que la aplicación espere en el identificador de eventos que se crea; la aplicación podría elegir en su lugar llamar a lineGetMessage y hacer que bloquee la espera de que se pone en cola un mensaje.

El mecanismo puerto de finalización se selecciona especificando LINEINITIALIZEEXOPTION_USECOMPLETION PUERTO en el miembro dwOptions de la estructura LINEINITIALIZEEXPARAMS . En este mecanismo, cada vez que se necesita 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, etiquetada 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 al que apunta 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 cerrarlo; 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 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 LINEERR_REINIT y se ha solicitado reinicialización TAPI, por ejemplo, como resultado de agregar o quitar un proveedor de servicios de telefonía, las solicitudes 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 cualquier función TAPI determinada sin consultar primero sus funcionalidades de dispositivo por 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 Convenciones para prototipos de función.