TUISPI_providerRemove-Funktion (tspi.h)

Artikel
08/26/2023

Die funktion TUISPI_providerRemove fordert den Benutzer auf, die Löschung des Dienstanbieters zu bestätigen. Diese Funktion macht die funktion TSPI_providerRemove in Version 2.0 und höher veraltet (unterstützt in Version 1.4 und früher).

Es liegt in der Verantwortung des Dienstanbieters, alle Registrierungseinträge zu entfernen, die der Dienstanbieter zum Zeitpunkt von addProvider hinzugefügt hat, sowie alle anderen Module und Dateien, die nicht mehr benötigt werden.

Die Implementierung ist optional.

Syntax

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

Parameter

lpfnUIDLLCallback

Zeiger auf eine Funktion, die die UI-DLL aufrufen kann, um mit der Dienstanbieter-DLL zu kommunizieren, um informationen abzurufen, die zum Anzeigen des Dialogfelds erforderlich sind.

hwndOwner

Das Handle des übergeordneten Fensters, in dem die Funktion alle Während des Entfernens erforderlichen Dialogfeldfenster erstellen kann.

dwPermanentProviderID

Der permanente Anbieterbezeichner des Dienstanbieters.

Rückgabewert

Gibt null zurück, wenn die Funktion erfolgreich ist, oder eine Fehlernummer, wenn ein Fehler auftritt. Mögliche Rückgabewerte sind:

LINEERR_OPERATIONFAILED, LINEERR_INIFILECORRUPT, LINEERR_NOMEM, LINEERR_INVALPARAM.

Hinweise

Diese Funktion muss garantieren, dass die privat definierten Informationen eines Dienstanbieters aus der Registrierung entfernt werden, wenn sie erfolgreich zurückgibt.

Diese Prozedur muss das System in einem konsistenten Zustand belassen. Es sollte bis zum Abschluss ausgeführt werden, sodass der Benutzer die Entfernung nicht abbrechen kann, wenn es teilweise abgeschlossen ist. Wenn bei der Entfernung ein Fehler auftritt, liegt es in der Verantwortung des Anbieters, die durchgeführten Aktionen zu "zurückstellen" und einen Fehler zurückzugeben. Dies kann eine Vorabüberprüfung beinhalten, um zu überprüfen, ob eine vollständige Entfernung möglich ist, bevor die Entfernung beginnt.

Diese Funktion kann aufgerufen werden, während der Dienstanbieter verwendet wird (also zwischen TSPI_providerInit und TSPI_providerShutdown). In diesem Fall sollte der Dienstanbieter eine geeignete Kombination aus der Anzeige eines Benutzerdialogfelds durchführen, um konflikte anzukündigen und die Entfernung zu bestätigen, die Entfernungsoptionen auf diejenigen zu beschränken, die transparent durchgeführt werden können, oder das Ausgeben von LINE_CLOSE und PHONE_CLOSE Nachrichten, um TAPI und Anwendungen darüber zu informieren, dass die betroffenen Geräte zum Entfernen erzwungen geschlossen wurden. In jedem Fall sollten alle Änderungen, die sich auf das über TSPI sichtbare Verhalten auswirken, nur wirksam werden, wenn der Dienstanbieter beim nächsten TSPI_providerShutdown heruntergefahren wird.

Hinweis Diese Funktion sollte keine LINEERR_INUSE oder andere Fehler zurückgeben, die auftreten können, weil der Anbieter von einer Anwendung verwendet wird. Stattdessen sollte der Anbieter dem Benutzer dieses Problem direkt mitteilen und dann LINEERR_OPERATIONFAILED zurückgeben, wenn der Benutzer entscheidet, den Vorgang abzubrechen.

Diese Prozedur wird zum Zeitpunkt der Entfernung des Dienstanbieters nur einmal aufgerufen, bis ein Aufruf von TUISPI_providerInstall erfolgt.

Die entsprechende Funktion auf TAPI-Ebene ist lineRemoveProvider. Auf dieser Ebene erwarten Anwendungen, dass Dienstanbieter bereits installiert sind. Andernfalls werden ihre Leitungen und Telefone nicht innerhalb der verfügbaren Sequenz von Gerätebezeichnern angezeigt. Die LINE_CREATE Meldung informiert Anwendungen, die ausgeführt werden, über die dynamische Neukonfiguration.