TSPI_providerRemove-Funktion (tspi.h)

Artikel
08/26/2023

Die funktion TSPI_providerRemove ist veraltet. TAPI Version 1.4 oder frühere Dienstanbieter können diese TSPI-Funktion implementieren. TAPI Version 2.0 oder höher implementieren TSPs TUISPI_providerRemove.

Die funktion TSPI_providerRemove fordert den Benutzer auf, die Löschung des Dienstanbieters zu bestätigen. 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.

Syntax

LONG TSPIAPI TSPI_providerRemove(
  HWND  hwndOwner,
  DWORD dwPermanentProviderID
);

Parameter

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 sicherstellen, dass der Abschnitt und die privat definierten Informationen des Dienstanbieters aus der Registrierung entfernt werden, wenn sie erfolgreich zurückgibt. Insbesondere der Abschnitt [Anbieter-PPID<>], dessen <PPID>mit dwPermanentProviderID übereinstimmt, muss entfernt werden, einschließlich seiner NumLines- und NumPhones-Einträge. Wenn die Funktion erfolgreich zurückgibt, liegt es in der Verantwortung des Aufrufers, die übereinstimmenden Einträge ProviderIDx und ProviderFilenamex aus dem Abschnitt [Providers] zu entfernen und die verbleibenden Einträge im Abschnitt [Anbieter] entsprechend neu zu nummerieren.

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.

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.

Dieses Verfahren wird zum Zeitpunkt der Entfernung des Dienstanbieters nur einmal aufgerufen, bis ein Aufruf von TSPI_providerInstall erfolgt. Es liegt in der Verantwortung des Aufrufers, dies sicherzustellen.

Das Telefonie-Systemsteuerung-Hilfsprogramm, das mit Windows-Telefonie in Version 1.4 und früher bereitgestellt wird, ruft diese Funktion auf (wobei die anforderungen an externe Sequenzen erfüllt sind, wie hier beschrieben), wenn der Befehl "remove" aufgerufen wird.

Es gibt keine entsprechende Funktion auf TAPI-Ebene. 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. Ausgeführte Anwendungen werden über die dynamische Neukonfiguration, einschließlich der Entfernung von Dienstanbietern, über den LINEDEVSTATE_REINIT- oder PHONESTATE_REINIT-Wert in der LINE_LINEDEVSTATE- oder PHONE_STATE-Nachricht informiert.