fonction TSPI_providerRemove (tspi.h)

Article
08/26/2023

La fonction TSPI_providerRemove est obsolète. Les fournisseurs de services TAPI version 1.4 ou antérieure peuvent implémenter cette fonction TSPI. TAPI version 2.0 ou ultérieure implémentent TUISPI_providerRemove.

La fonction TSPI_providerRemove demande à l’utilisateur de confirmer l’élimination du fournisseur de services. 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.

Syntaxe

LONG TSPIAPI TSPI_providerRemove(
  HWND  hwndOwner,
  DWORD dwPermanentProviderID
);

Paramètres

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 la section du fournisseur de services et les informations définies en privé pour le fournisseur de services sont supprimées du Registre s’il retourne la réussite. En particulier, la section [FOURNISSEUR<PPID>] dont <le PPID> correspond à dwPermanentProviderID doit être supprimée, y compris ses entrées NumLines et NumPhones . Si la fonction retourne la réussite, il incombe à l’appelant de supprimer les entrées ProviderIDx et ProviderFilenamex correspondantes de la section [Fournisseurs] et de renuméroter les entrées restantes de la section [Fournisseurs] en conséquence.

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.

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 à TSPI_providerInstall. Il incombe à l’appelant de s’en assurer.

L’utilitaire téléphonie Panneau de configuration fourni avec La téléphonie Windows dans les versions 1.4 et antérieures appelle cette fonction (avec les exigences de séquence externe remplies comme décrit ici) lorsque la commande « remove » est appelée.

Il n’existe aucune fonction correspondante au niveau TAPI. À 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. Les applications en cours d’exécution sont informées de la reconfiguration dynamique, y compris la suppression des fournisseurs de services, via la valeur LINEDEVSTATE_REINIT ou PHONESTATE_REINIT dans le message LINE_LINEDEVSTATE ou PHONE_STATE.