PHONEBUTTONINFO-Struktur (tapi.h)

Artikel
03/02/2024

Die PHONEBUTTONINFO-Struktur enthält Informationen zu einer Schaltfläche auf einem Telefongerät. Diese Struktur wird von mehreren TAPI- und TSPI-Funktionen verwendet.

Syntax

typedef struct phonebuttoninfo_tag {
  DWORD dwTotalSize;
  DWORD dwNeededSize;
  DWORD dwUsedSize;
  DWORD dwButtonMode;
  DWORD dwButtonFunction;
  DWORD dwButtonTextSize;
  DWORD dwButtonTextOffset;
  DWORD dwDevSpecificSize;
  DWORD dwDevSpecificOffset;
  DWORD dwButtonState;
} PHONEBUTTONINFO, *LPPHONEBUTTONINFO;

Member

dwTotalSize

Dieser Datenstruktur zugeordnete Gesamtgröße in Byte.

dwNeededSize

Größe für diese Datenstruktur, die benötigt wird, um alle zurückgegebenen Informationen in Bytes zu enthalten.

dwUsedSize

Größe des Teils dieser Datenstruktur, der nützliche Informationen in Byte enthält.

dwButtonMode

Modus oder allgemeine Verwendungsklasse der Schaltfläche. Dieser Member verwendet eine der PHONEBUTTONMODE_ Konstanten.

dwButtonFunction

Der Schaltfläche zugewiesene Funktion. Dieser Member verwendet eine der PHONEBUTTONFUNCTION_ Konstanten.

dwButtonTextSize

Größe des beschreibenden Texts für die Schaltfläche in Bytes.

dwButtonTextOffset

Offset vom Anfang dieser Struktur zum variabel dimensionierten Feld, das beschreibenden Text für diese Schaltfläche enthält. Das Format dieser Informationen ist wie im dwStringFormat-Member der Gerätefunktionen des Telefons angegeben. Die Größe des Felds wird von dwButtonTextSize angegeben.

dwDevSpecificSize

Größe des gerätespezifischen Felds in Bytes. Wenn das gerätespezifische Feld ein Zeiger auf eine Zeichenfolge ist, muss die Größe den NULL-Abschlusszeichen enthalten.

dwDevSpecificOffset

Offset vom Anfang der Struktur zum variabel dimensionierten gerätespezifischen Feld. Die Größe des Felds wird von dwDevSpecificSize angegeben.

dwButtonState

Für die phoneGetButtonInfo-Funktion gibt dieses Feld den aktuellen Status der Schaltfläche mithilfe der PHONEBUTTONSTATE_ Konstanten an. Dieses Feld wird von der phoneSetButtonInfo-Funktion ignoriert.

Hinweise

Gerätespezifische Erweiterungen sollten den DevSpecific-Bereich (dwDevSpecificSize und dwDevSpecificOffset) mit unterschiedlicher Größe dieser Datenstruktur verwenden.

Ältere Anwendungen werden ohne dieses Feld in der PHONEBUTTONINFO-Struktur kompiliert und verwenden ein SIZEOF PHONEBUTTONINFO, das kleiner als die neue Größe ist. Die Anwendung übergibt einen dwAPIVersion-Parameter mit der phoneOpen-Funktion , die von TAPI zur Behandlung dieser Situation verwendet werden kann. Wenn die Anwendung eine dwTotalSize übergibt, die kleiner als die Größe des festen Teils der Struktur ist, wie in der angegebenen dwAPIVersion definiert, wird PHONEERR_STRUCTURETOOSMALL zurückgegeben. Wenn von der Anwendung ausreichend Arbeitsspeicher zugewiesen wurde, legt TAPI vor dem Aufrufen der TSPI_phoneGetButtonInfo-Funktion die Elemente dwNeededSize und dwUsedSize auf die feste Größe der Struktur fest, wie sie in der angegebenen API-Version vorhanden war.

Neue Dienstanbieter (die die neue API-Version unterstützen) müssen die übergebene API-Version überprüfen. Wenn die API-Version kleiner als die höchste vom Anbieter unterstützte Version ist, darf der Dienstanbieter keine Felder ausfüllen, die in älteren API-Versionen nicht unterstützt werden, da diese in den variablen Teil der älteren Struktur fallen würden.

Neue Anwendungen müssen die ausgehandelte API-Version kennen und dürfen den Inhalt von Feldern im festen Teil nicht über das ursprüngliche Ende des festen Teils der Struktur für die ausgehandelte API-Version hinaus untersuchen.