TSPI_lineGetDevConfig-Funktion (tspi.h)
Die TSPI_lineGetDevConfig-Funktion gibt ein Datenstrukturobjekt zurück, dessen Inhalt für die Leitung (Dienstanbieter) und die Geräteklasse spezifisch ist, sodass die aktuelle Konfiguration eines Geräts, das dem Zeilengerät zugeordnet ist, 1:1-spezifisch ist.
Syntax
LONG TSPIAPI TSPI_lineGetDevConfig(
DWORD dwDeviceID,
LPVARSTRING lpDeviceConfig,
LPCWSTR lpszDeviceClass
);
Parameter
dwDeviceID
Das zu konfigurierende Leitungsgerät.
lpDeviceConfig
Ein Zeiger auf eine Datenstruktur vom Typ VARSTRING , in der die Gerätekonfigurationsstruktur des zugeordneten Geräts zurückgegeben wird. Nach erfolgreichem Abschluss der Anforderung füllt der Dienstanbieter diese Datenstruktur mit der Gerätekonfiguration aus. Das dwStringFormat-Element in der VARSTRING-Struktur muss auf STRINGFORMAT_BINARY festgelegt werden. Wenn das dwTotalSize-Element der VARSTRING-Struktur , auf die vom lpDeviceConfig-Parameter verwiesen wird, größer oder gleich der Größe des festen Teils der Struktur ist, legt der Dienstanbieter den dwNeededSize-Member auf die erforderliche Größe fest und gibt Null zurück.
lpszDeviceClass
Ein Zeiger auf eine mit Null beendete Unicode-Zeichenfolge, die die Geräteklasse des Geräts angibt, dessen Konfiguration angefordert wird. Gültige Geräteklassenzeichenfolgen sind identisch mit denen, die für die TSPI_lineGetID-Funktion angegeben werden, wenn sie auf ein Zeilengerät angewendet wird (dwSelect hat den Wert LINECALLSELECT_LINE).
Rückgabewert
Gibt null zurück, wenn die Funktion erfolgreich ist, oder eine Fehlernummer, wenn ein Fehler auftritt. Mögliche Rückgabewerte sind wie folgt:
LINEERR_INVALDEVICECLASS, LINEERR_NOMEM, LINEERR_INVALPOINTER, LINEERR_OPERATIONUNAVAIL, LINEERR_STRUCTURETOOSMALL, LINEERR_OPERATIONFAILED, LINEERR_NODRIVER, LINEERR_RESOURCEUNAVAIL.
Hinweise
Der Anrufstatus ist gerätespezifisch.
Diese Funktion kann verwendet werden, um eine Datenstruktur vom Dienstanbieter abzurufen, die die Konfiguration eines Geräts angibt, das dem Zeilengerät 1:1 zugeordnet ist. Der lpszDeviceClass-Parameter wählt aus, welche der möglicherweise verschiedenen Geräteklassen die Konfiguration abrufen 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 sollte in der Regel die tapi/line-Geräteklasse unter dieser Funktion zulassen. Es würde Parameter mit "Zeilenbereich" abrufen, z. B. die Liste der Adressen in dieser Zeile, die Liste der physischen Hardwaregeräte wie COMM-Ports, die den Adressen entsprechen, die maximale Anzahl gleichzeitiger Aufrufe (falls konfigurierbar) usw.
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, wäre 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 vorgenommen werden, wenn Klassenkonfigurationsinformationen vorhanden sind, die für den gesamten Zeilengerätebereich gelten, z. B. anfängliche Standardwerte usw.
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/Mehrfachanrufen mehrdeutig sein können, unterstützt sie nur eine Teilmenge von Dienstanbietern. Anwendungen 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 eher zum "instance" Bereich anstelle des "Klassenbereichs". Die allgemeine Medien-API muss ihre eigenen 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_lineSetDevConfig abgerufen oder festgelegt 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 von dieser Funktion zurückgegebenen Struktur enthalten sind, ist spezifisch für die Zeilen- und Geräteklassen-API, ist nicht dokumentiert und nicht definiert. Auf die von dieser Funktion zurückgegebene Struktur kann nicht direkt von der Anwendung zugegriffen oder bearbeitet werden, sondern nur intakt gespeichert und später in TSPI_lineSetDevConfig zum Wiederherstellen 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 Elemente in die Datenstruktur einfügen, damit sie auf Konsistenz überprüft werden kann, um sich vor Fehlern zu schützen, die darauf zurückzuführen sind, dass eine Clientanwendung inkompatible Informationen übergibt.
Anforderungen
| Zielplattform | Windows |
| Kopfzeile | tspi.h |