TSPI_providerInit función (tspi.h)

Artículo
03/08/2023

La función TSPI_providerInit inicializa el proveedor de servicios y le proporciona los parámetros necesarios para las operaciones posteriores.

Sintaxis

LONG TSPIAPI TSPI_providerInit(
  DWORD            dwTSPIVersion,
  DWORD            dwPermanentProviderID,
  DWORD            dwLineDeviceIDBase,
  DWORD            dwPhoneDeviceIDBase,
  DWORD_PTR        dwNumLines,
  DWORD_PTR        dwNumPhones,
  ASYNC_COMPLETION lpfnCompletionProc,
  LPDWORD          lpdwTSPIOptions
);

Parámetros

dwTSPIVersion

La versión de la definición de TSPI con la que debe funcionar esta función. El autor de la llamada puede usar TSPI_lineNegotiateTSPIVersion con el INITIALIZE_NEGOTIATIONdwDeviceID especial para negociar una versión que se garantiza que sea aceptable para el proveedor de servicios.

dwPermanentProviderID

Identificador permanente, único dentro de los proveedores de servicios de este sistema, del proveedor de servicios que se inicializa.

dwLineDeviceIDBase

El identificador de dispositivo más bajo para los dispositivos de línea admitidos por este proveedor de servicios.

dwPhoneDeviceIDBase

El identificador de dispositivo más bajo para los dispositivos telefónicos compatibles con este proveedor de servicios.

dwNumLines

Número de dispositivos de línea que admite este proveedor de servicios. El valor devuelto es el número de dispositivos de línea notificados en TSPI_providerEnumDevices.

dwNumPhones

El número de dispositivos telefónicos que admite este proveedor de servicios. El valor devuelto es el número de dispositivos telefónicos notificados en TSPI_providerEnumDevices.

lpfnCompletionProc

Procedimiento al que llama el proveedor de servicios para notificar la finalización de todos los procedimientos operativos asincrónicamente en dispositivos de línea y teléfono.

lpdwTSPIOptions

Puntero a una ubicación de memoria de tamaño DWORD en la que el proveedor de servicios puede escribir un valor que especifique LINETSPIOPTIONS_ valores. Este parámetro permite al proveedor de servicios devolver bits que indican comportamientos opcionales deseados de TAPI. TAPI establece las opciones DWORD en 0 antes de llamar a TSPI_providerInit, por lo que si el proveedor de servicios no desea ninguna de estas opciones, simplemente puede dejar el DWORD establecido en 0.

En este momento, solo se define un bit para que se devuelva a través de este puntero: LINETSPIOPTION_NONREENTRANT. El proveedor de servicios establece este bit si no está diseñado para la operación multiproceso, multiproceso, multiproceso, multiprocesador (por ejemplo, la actualización de datos globales protegidos por exclusiones mutuas). Cuando se establece este bit, TAPI solo realiza una llamada a la vez al proveedor de servicios; no llama a ningún otro punto de entrada, ni a ese punto de entrada de nuevo, hasta que el proveedor de servicios vuelva de la llamada de función original. Sin este conjunto de bits, TAPI puede llamar a varios puntos de entrada del proveedor de servicios, incluidas varias veces al mismo punto de entrada, simultáneamente (en realidad simultáneamente en un sistema multiprocesador).

NotaImportante: Debe destacarse que establecer este bit degrada el rendimiento. Se recomienda encarecidamente que se use solo para el desarrollo, pero no para un proveedor de servicios de producción enviado.

TAPI no serializa el acceso a funciones TSPI que muestran un cuadro de diálogo ( TUISPI_lineConfigDialog, TUISPI_lineConfigDialogEdit, TUISPI_phoneConfigDialog, TUISPI_providerConfig, TUISPI_providerInstall, TUISPI_providerRemove) para que no bloqueen que se llame a otras funciones de TSPI; El proveedor de servicios debe incluir protección interna en estas funciones.

Valor devuelto

Devuelve cero si la función se realiza correctamente o si se produce un error. Los valores devueltos posibles son los siguientes:

LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_INIFILECORRUPT, LINEERR_NOMULTIPLEINSTANCE.

Comentarios

Se garantiza que se llame a esta función antes de que cualquiera de las otras funciones tenga el prefijo TSPI_line o TSPI_phone excepto TSPI_lineNegotiateTSPIVersion. Se empareja estrictamente con una llamada posterior a TSPI_providerShutdown Estos pares pueden superponerse, por ejemplo, cuando la utilidad de telefonía Panel de control proporcionada con telefonía de Windows en las versiones 1.4 y anteriores se usa mientras las operaciones de telefonía están en curso. La llamada a esta función debe omitirse (devolviendo correctamente) si ya hay un par pendiente.

Un proveedor de servicios debe realizar tantas comprobaciones de coherencia como sea práctico en el momento. se llama a TSPI_providerInit para asegurarse de que está listo para ejecutarse. Sin embargo, no se pueden detectar algunos errores de coherencia o instalación hasta que se intente la operación. El error LINEERR_NODRIVER se puede usar para notificar estos errores no específicos en el momento en que se detectan.

No hay ninguna función correspondiente directamente en el nivel TAPI. En ese nivel, se pueden pendientes varias instancias de uso diferentes, con un "identificador de aplicación" devuelto para identificar la instancia en operaciones posteriores. En el nivel de TSPI, la arquitectura de interfaz solo admite una única instancia de uso para cada proveedor de servicios distinto.