función TSPI_providerRemove (tspi.h)

Artículo
08/26/2023

La función TSPI_providerRemove está obsoleta. Los proveedores de servicios TAPI versión 1.4 o anteriores pueden implementar esta función TSPI. Los TSP de TAPI versión 2.0 o posterior implementan TUISPI_providerRemove.

La función TSPI_providerRemove pide al usuario que confirme la eliminación del proveedor de servicios. Es responsabilidad del proveedor de servicios quitar las entradas del Registro que el proveedor de servicios agregó en el momento de addProvider , así como cualquier otro módulo y archivo que ya no sean necesarios.

Sintaxis

LONG TSPIAPI TSPI_providerRemove(
  HWND  hwndOwner,
  DWORD dwPermanentProviderID
);

Parámetros

hwndOwner

Identificador de la ventana primaria en la que la función puede crear las ventanas de cuadro de diálogo necesarias durante la eliminación.

dwPermanentProviderID

Identificador de proveedor permanente del proveedor de servicios.

Valor devuelto

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

LINEERR_OPERATIONFAILED, LINEERR_INIFILECORRUPT, LINEERR_NOMEM LINEERR_INVALPARAM.

Comentarios

Esta función debe garantizar que la sección del proveedor de servicios y la información definida de forma privada para el proveedor de servicios se quite del registro si devuelve el éxito. En concreto, se debe quitar la sección [PpID> del proveedor<] cuyo <PPID> coincide con dwPermanentProviderID, incluidas sus entradas NumLines y NumPhones. Si la función devuelve éxito, es responsabilidad del autor de la llamada quitar las entradas ProviderIDx y ProviderFilenamex coincidentes de la sección [Providers] y volver a numerar las entradas restantes de la sección [Proveedores] en consecuencia.

Este procedimiento debe dejar el sistema en un estado coherente. Debe ejecutarse hasta completarse, no permitir que el usuario anule la eliminación cuando se complete parcialmente. Si se produce un error en la eliminación, es responsabilidad del proveedor "volver a salir" lo que se ha hecho y devolver un error. Esto puede implicar el análisis previo para comprobar que es posible eliminar una eliminación completa antes de que comience la eliminación.

Se puede llamar a esta función mientras el proveedor de servicios está en uso (es decir, entre TSPI_providerInit y TSPI_providerShutdown). Si esto sucede, el proveedor de servicios debe realizar una combinación adecuada de mostrar un cuadro de diálogo de usuario para anunciar cualquier conflicto y confirmar la eliminación, restringir las opciones de eliminación a las que se pueden realizar de forma transparente, o emitir LINE_CLOSE y PHONE_CLOSE mensajes para informar a TAPI y las aplicaciones de que los dispositivos afectados se han cerrado forzosamente para su eliminación. En cualquier caso, los cambios que afecten al comportamiento visible a través de TSPI solo deben surtir efecto cuando el proveedor de servicios se apague en el siguiente TSPI_providerShutdown.

Esta función no debe devolver LINEERR_INUSE u otros errores que puedan producirse porque el proveedor está en uso por una aplicación; en su lugar, el proveedor debe conferir al usuario directamente sobre este problema y, a continuación, devolver LINEERR_OPERATIONFAILED si el usuario decide anular la operación.

Este procedimiento se llama solo una vez, en el momento de la eliminación del proveedor de servicios, hasta que haya una llamada a TSPI_providerInstall. Es responsabilidad del autor de la llamada garantizar esto.

La utilidad de telefonía Panel de control proporcionada con telefonía de Windows en las versiones 1.4 y anteriores llama a esta función (con requisitos de secuencia externos cumplidos como se describe aquí) cuando se invoca el comando "remove".

No hay ninguna función correspondiente en el nivel TAPI. En ese nivel, las aplicaciones esperan tener ya instalados proveedores de servicios; de lo contrario, sus líneas y teléfonos no aparecen dentro de la secuencia disponible de identificadores de dispositivo. Las aplicaciones en ejecución se informan sobre la reconfiguración dinámica, incluida la eliminación de proveedores de servicios, a través del valor de LINEDEVSTATE_REINIT o PHONESTATE_REINIT en el mensaje LINE_LINEDEVSTATE o PHONE_STATE.