fonction TUISPI_providerRemove (tspi.h)

Article
08/26/2023

La fonction TUISPI_providerRemove demande à l’utilisateur de confirmer l’élimination du fournisseur de services. Cette fonction rend la fonction TSPI_providerRemove obsolète dans les versions 2.0 et ultérieures (prises en charge dans les versions 1.4 et antérieures).

Il incombe au fournisseur de services de supprimer toutes les entrées de Registre ajoutées par le fournisseur de services au moment de addProvider , ainsi que tous les autres modules et fichiers qui ne sont plus nécessaires.

L’implémentation est facultative.

Syntaxe

LONG TSPIAPI TUISPI_providerRemove(
  TUISPIDLLCALLBACK lpfnUIDLLCallback,
  HWND              hwndOwner,
  DWORD             dwPermanentProviderID
);

Paramètres

lpfnUIDLLCallback

Pointeur vers une fonction que la DLL d’interface utilisateur peut appeler pour communiquer avec la DLL du fournisseur de services afin d’obtenir les informations nécessaires à l’affichage de la boîte de dialogue.

hwndOwner

Handle de la fenêtre parente dans laquelle la fonction peut créer toutes les fenêtres de boîte de dialogue requises pendant la suppression.

dwPermanentProviderID

Identificateur de fournisseur permanent du fournisseur de services.

Valeur retournée

Retourne zéro si la fonction réussit ou un numéro d’erreur si une erreur se produit. Les valeurs de retour possibles sont les suivantes :

LINEERR_OPERATIONFAILED, LINEERR_INIFILECORRUPT, LINEERR_NOMEM, LINEERR_INVALPARAM.

Remarques

Cette fonction doit garantir que les informations de définition privée de tout fournisseur de services sont supprimées du Registre si elles retournent la réussite.

Cette procédure doit laisser le système dans un état cohérent. Il doit s’exécuter jusqu’à la fin, ce qui ne permet pas à l’utilisateur d’abandonner la suppression lorsqu’elle est en partie terminée. Si la suppression échoue, il incombe au fournisseur de « reculer » ce qui a été fait et de retourner une erreur. Cela peut impliquer une analyse préalable pour vérifier qu’une suppression complète est possible, avant le début de la suppression.

Cette fonction peut être appelée pendant l’utilisation du fournisseur de services (c’est-à-dire entre TSPI_providerInit et TSPI_providerShutdown). Dans ce cas, le fournisseur de services doit effectuer une combinaison appropriée d’affichage d’une boîte de dialogue utilisateur pour annoncer tout conflit et confirmer la suppression, en limitant les options de suppression à celles qui peuvent être effectuées de manière transparente, ou en émettant des messages LINE_CLOSE et PHONE_CLOSE pour informer TAPI et les applications que les appareils concernés ont été fermés de force pour suppression. Dans tous les cas, toutes les modifications qui affectent le comportement visible via TSPI ne doivent prendre effet que lorsque le fournisseur de services est arrêté au TSPI_providerShutdown suivant.

Note Cette fonction ne doit pas retourner LINEERR_INUSE ou d’autres erreurs qui peuvent se produire parce que le fournisseur est utilisé par une application ; au lieu de cela, le fournisseur doit s’entretenir directement avec l’utilisateur au sujet de ce problème, puis retourner LINEERR_OPERATIONFAILED si l’utilisateur décide d’abandonner l’opération.

Cette procédure n’est appelée qu’une seule fois, au moment de la suppression du fournisseur de services, jusqu’à ce qu’il y ait un appel à TUISPI_providerInstall.

La fonction correspondante au niveau TAPI est lineRemoveProvider. À ce niveau, les applications s’attendent à avoir des fournisseurs de services déjà installés ; sinon, leurs lignes et téléphones n’apparaissent pas dans la séquence disponible d’identificateurs d’appareil. Le message LINE_CREATE informe les applications qui s’exécutent sur la reconfiguration dynamique.