TSPI_lineSetDevConfig-Funktion (tspi.h)
Die TSPI_lineSetDevConfig-Funktion stellt die Konfiguration eines Geräts, das dem Leitungsgerät zugeordnet ist, aus einer Datenstruktur wieder her, die zuvor mit TSPI_lineGetDevConfig abgerufen wurde. Der Inhalt dieser Datenstruktur ist spezifisch für die Zeile [Dienstanbieter] und die Geräteklasse.
Syntax
LONG TSPIAPI TSPI_lineSetDevConfig(
DWORD dwDeviceID,
LPVOID const lpDeviceConfig,
DWORD dwSize,
LPCWSTR lpszDeviceClass
);
Parameter
dwDeviceID
Das zu konfigurierende Leitungsgerät.
lpDeviceConfig
Ein Zeiger auf die Konfigurationsdatenstruktur, die im Variablenteil der VARSTRING-Struktur von TSPI_lineGetDevConfig zurückgegeben wird.
dwSize
Die Anzahl der Bytes in der Struktur, auf die von lpDeviceConfig verwiesen wird. Dieser Wert wird im dwStringSize-Member in der VARSTRING-Struktur zurückgegeben, die von TSPI_lineGetDevConfig zurückgegeben wird.
lpszDeviceClass
Ein Zeiger auf eine Unicode-Zeichenfolge mit Null-Beendigung, die die Geräteklasse des Geräts angibt, dessen Konfiguration wiederhergestellt werden soll. Gültige Geräteklassenzeichenfolgen sind identisch mit denen, die für die TSPI_lineGetID-Funktion angegeben werden, wenn sie auf ein "line"-Gerät angewendet wird (d. a. wenn dwSelect den Wert LINECALLSELECT_LINE hat).
Rückgabewert
Gibt null zurück, wenn die Funktion erfolgreich ist, oder eine Fehlernummer, wenn ein Fehler auftritt. Mögliche Rückgabewerte sind:
LINEERR_INVALDEVICECLASS, LINEERR_NOMEM, LINEERR_INVALPOINTER, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALPARAM, LINEERR_OPERATIONFAILED, LINEERR_INVALLINESTATE, LINEERR_RESOURCEUNAVAIL, LINEERR_NODRIVER.
Hinweise
Der Anrufstatus ist gerätespezifisch.
Der Dienstanbieter gibt LINEERR_INVALPARAM zurück, wenn die Informationen in der Struktur, auf die von lpDeviceConfig verwiesen wird, für dieses Gerät ungültig sind.
Der Dienstanbieter gibt LINEERR_INVALLINESTATE zurück, wenn die Gerätekonfiguration im aktuellen Zeilenzustand nicht geändert werden kann. Die Zeile kann von einer anderen Anwendung verwendet werden.
Diese Funktion kann verwendet werden, um die Konfiguration eines Geräts, das dem Leitungsgerät 1:1 zugeordnet ist, aus einer Datenstruktur wiederherzustellen, die zuvor mithilfe der TSPI_lineGetDevConfig-Funktion vom Dienstanbieter abgerufen wurde. Der lpszDeviceClass-Parameter wählt aus, für welche der möglicherweise verschiedenen Geräteklassen die Konfiguration wiederhergestellt werden soll. Der Satz der unterstützten Klassen ist auf diejenigen beschränkt, deren Geräte eins zu 1 mit dem Leitungsgerät übereinstimmen. Weitere Informationen zu gängigen Geräteklassen finden Sie unter TSPI-Geräteklassen.
Ein Dienstanbieter lässt in der Regel die Tapi/line-Geräteklasse unter dieser Funktion zu. Es stellt Parameter mit "Line"-Bereich wie die Liste der Adressen in dieser Zeile und die Liste der physischen Hardwaregeräte wie COMM-Ports, die den Adressen entsprechen, oder die maximale Anzahl gleichzeitiger Aufrufe (sofern konfigurierbar) wiederhergestellt.
Im Allgemeinen lässt diese Funktion keine medienbezogenen Geräteklassen wie mci waveaudio, Low Level Wave oder Datamodem-Geräteklassen zu, da diese in der Regel für einen bestimmten Aufruf oder eine bestimmte Adresse gelten. Da es mehrere dieser Geräte pro Zeilengerät geben kann, ist die Identifizierung des jeweiligen Aufrufs oder der jeweiligen Adresse einfach durch den Zeilengerätebezeichnerparameter in dieser Funktion mehrdeutig. Eine Ausnahme kann für anrufspezifische oder adressspezifische Geräteklassen in Fällen vorgenommen werden, in denen Klassenkonfigurationsinformationen vorhanden sind, die für den gesamten Zeilengerätebereich gelten, z. B. anfängliche Standardwerte.
Es gibt mehrere Gründe, warum die außergewöhnliche Unterstützung für anrufspezifische und adressspezifische Geräteklassen unter dieser Funktion nur von begrenztem Wert ist. Erstens, da diese Klassen bei Dienstanbietern mit mehreren Adressen mehrdeutig sein können, unterstützt sie nur eine Teilmenge von Dienstanbietern. Anwendungsprogramme fügen wahrscheinlich keine gerätespezifische Abhängigkeit von der Aufnahme dieser Klassen in diese Funktion hinzu. Zweitens, da höhere Medienklassen entstehen, die allgemeine Protokolle wie den Einwahldateisystemzugriff in Bezug auf Transport-APIs auf niedriger Ebene implementieren, tendiert die Konfiguration für diese Klassen dazu, instance Bereich anstelle des Klassenbereichs zu verwenden. Die allgemeine Medien-API muss eigene Funktionen bereitstellen, um aufrufspezifische oder adressspezifische Instanzen zu konfigurieren.
Unabhängig davon, welche Art von Geräten und Geräteklassen diese Funktion unterstützt, kann sie sich möglicherweise auf zwei Arten von Konfigurationsinformationen auswirken: permanent und temporär. Permanente Informationen bestehen über verschiedene "Eröffnungen" der Linie hinweg und sogar über verschiedene "Inits" des Dienstanbieters selbst. Temporäre Informationen bleiben nur innerhalb eines eindeutigen "offenen" der Zeile erhalten. Wenn die Zeile geschlossen wird, können alle temporären Informationen, die über TSPI_lineGetDevConfig festgelegt oder abgerufen wurden, auf Standard- oder nicht definierte Werte rückgängig machen. Der Aufrufer kann jede temporäre Konfiguration zuverlässig nur durch eine Sequenz wie TSPI_lineOpen, TSPI_lineConfigDialog, TSPI_lineGetDevConfig abrufen. Der Aufrufer kann temporäre Konfigurationsinformationen, die von einer solchen Sequenz abgerufen werden, zuverlässig über eine Sequenz wie TSPI_lineOpen, TSPI_lineSetDevConfig festlegen. Der temporäre Teil der Konfiguration bleibt nur bis zum nächsten TSPI_lineConfigDialog, TSPI_lineSetDevConfig oder TSPI_lineClose stabil. Der Dienstanbieter muss jeden dauerhaften Teil der Konfiguration speichern, in der Regel in einer .ini-Datei, und es bei jeder Initialisierung des Dienstanbieters neu zu laden.
Das genaue Format der Daten, die in der Struktur enthalten sind, die an diese Funktion übergeben werden, ist spezifisch für die Zeilen- und Geräteklassen-API, ist nicht dokumentiert und nicht definiert. Auf die an diese Funktion übergebene Struktur kann nicht direkt von der Anwendung zugegriffen oder bearbeitet werden, sondern nur intakt gespeichert und später von einem vorherigen TSPI_lineGetDevConfig zum Abrufen der Einstellungen verwendet werden. Die Struktur kann auch nicht unbedingt an andere Geräte übergeben werden, auch nicht an dieselbe Geräteklasse (obwohl dies in einigen Fällen funktionieren kann, ist dies nicht garantiert). Ein Dienstanbieter sollte diese Datenstruktur auf Konsistenz überprüfen, um sich vor Fehlern zu schützen, die darauf zurückzuführen sind, dass eine Clientanwendung inkompatible Informationen übergibt.
Anforderungen
| Anforderung | Wert |
|---|---|
| Zielplattform | Windows |
| Kopfzeile | tspi.h |