Función lineInitialize (tapi.h)

Artículo
08/26/2023

La función lineInitialize 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 la API.

Las aplicaciones que usan la API versión 2.0 o posterior deben usar lineInitializeEx en su lugar.

Para las versiones 1.4 y anteriores de TAPI: La función lineInitialize inicializa el uso de Tapi.dll de la aplicación para el uso posterior de la abstracción de línea. La función 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 TAPI.

Sintaxis

LONG lineInitialize(
  LPHLINEAPP   lphLineApp,
  HINSTANCE    hInstance,
  LINECALLBACK lpfnCallback,
  LPCSTR       lpszAppName,
  LPDWORD      lpdwNumDevs
);

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.

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. Para obtener más información, vea lineCallbackFunc.

lpszAppName

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 lpszAppName es NULL, se usa el nombre de archivo de la aplicación en su lugar.

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.

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_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_REINIT, LINEERR_NODRIVER, LINEERR_NODEVICE, LINEERR_NOMEM, LINEERR_NOMULTIPLEINSTANCE.

Comentarios

Si se devuelve LINEERR_REINIT y se ha solicitado reinicialización de TAPI (por ejemplo, como resultado de agregar o quitar un proveedor de servicios de telefonía), las solicitudes lineInitialize se rechazan con este error hasta que la última aplicación cierra su uso de la API (mediante lineShutdown). En ese momento, la nueva configuración se hace efectiva y las aplicaciones se vuelven a permitir que las aplicaciones llamen a lineInitialize. 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 nada más allá de lo especificado por el subconjunto de telefonía básica sin consultar primero sus funcionalidades de dispositivo mediante lineGetDevCaps y lineGetAddressCaps.

Las aplicaciones no deben invocar lineInitialize sin abrir posteriormente una línea (al menos para la supervisión). Si la aplicación no está supervisando y no usa ningún dispositivo, debe llamar a lineShutdown para que los recursos de memoria asignados por Tapi.dll se puedan liberar si no son necesarios y Tapi.dll sí mismo se pueden descargar de la memoria, aunque no sea necesario.

Otra razón para realizar una lineShutdown es que si un usuario cambia la configuración del dispositivo (agrega o quita una línea o teléfono), no hay ninguna manera 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 LINEDEVSTATE_REINIT, ninguna aplicación puede abrir un dispositivo hasta que todas las aplicaciones hayan realizado una lineShutdown. Si algún proveedor de servicios no se inicializa correctamente, se produce un error en esta función y devuelve el error indicado por el proveedor de servicios.

En todas las plataformas TAPI, lineInitialize es equivalente a lineInitializeEx mediante la opción LINEINITIALIZEEXOPTION_USEHIDDENWINDOW.