_BRB_L2CA_OPEN_CHANNEL-Struktur (bthddi.h)

Artikel
02/26/2024

Die _BRB_L2CA_OPEN_CHANNEL-Struktur beschreibt einen L2CAP-Kanal, der für ein Remotegerät geöffnet werden soll, oder eine Antwort des Profiltreibers, die eine von einem Remotegerät initiierte eingehende L2CAP-Verbindungsanforderung akzeptiert oder ablehnt.

Syntax

struct _BRB_L2CA_OPEN_CHANNEL {
  BRB_HEADER                     Hdr;
  L2CAP_CHANNEL_HANDLE           ChannelHandle;
  union {
    struct {
      USHORT Response;
      USHORT ResponseStatus;
    };
    USHORT Psm;
  };
  ULONG                          ChannelFlags;
  BTH_ADDR                       BtAddress;
  struct {
    ULONG                    Flags;
    L2CAP_CONFIG_VALUE_RANGE Mtu;
    L2CAP_CONFIG_VALUE_RANGE FlushTO;
    L2CAP_FLOWSPEC           Flow;
    USHORT                   LinkTO;
    ULONG                    NumExtraOptions;
    PL2CAP_CONFIG_OPTION     ExtraOptions;
    struct {
      UCHAR ServiceType;
      ULONG Latency;
    } LocalQos;
  } ConfigOut;
  struct {
    ULONG                    Flags;
    L2CAP_CONFIG_VALUE_RANGE Mtu;
    L2CAP_CONFIG_RANGE       FlushTO;
  } ConfigIn;
  ULONG                          CallbackFlags;
  PFNBTHPORT_INDICATION_CALLBACK Callback;
  PVOID                          CallbackContext;
  PVOID                          ReferenceObject;
  CHANNEL_CONFIG_RESULTS         OutResults;
  CHANNEL_CONFIG_RESULTS         InResults;
  UCHAR                          IncomingQueueDepth;
};

Member

Hdr

Eine BRB_HEADER-Struktur , die Informationen zum aktuellen BRB enthält.

ChannelHandle

Handle, das verwendet wird, um die Verbindung bei einer erfolgreichen Verbindung zu identifizieren. Wenn Sie eine BRB_L2CA_OPEN_CHANNEL senden, wird diese ausgefüllt, wenn der BRB abgeschlossen ist. Beim Senden einer BRB_L2CA_OPEN_CHANNEL_RESPONSE muss dieser vom Server ausgefüllt werden, bevor der BRB gesendet wird. Der zugewiesene Wert sollte sein INDICATION_PARAMETERS::ConnectionHandle , der während der IndicationRemoteConnect übergeben wurde.

Response

Wird nur mit BRB_L2CA_OPEN_CHANNEL_RESPONSE verwendet. Einer der CONNECT_RSP_RESULT_Xxx-Werte wird verwendet.

Wenn der BRB mit einer status von STATUS_REQUEST_NOT_ACCEPTED zurückgibt, enthält Response die negative Antwort vom Remotehost.

ResponseStatus

Wenn Antwort gleich CONNECT_RSP_RESULT_PENDING ist, ist dieses Feld gültig. Einer der CONNECT_RSP_STATUS_XXX-Werte wird verwendet.

Psm

Der Protokoll-/Dienstmultixer (PSM), den der Kanal zum Herstellen einer Verbindung mit dem Remotegerät verwendet. Bei Verwendung mit einer BRB_L2CA_OPEN_CHANNEL-Anforderung wird dieses Element als Eingabefeld festgelegt. Bei Verwendung mit einer BRB_L2CA_OPEN_CHANNEL_RESPONSE-Anforderung wird dieser Member als Ausgabefeld verwendet.

ChannelFlags

Flags, die die Anforderungen für den zu öffnenden Kanal angeben. Gültige Flagwerte sind in der folgenden Tabelle aufgeführt:

Flag	Beschreibung
CF_LINK_AUTHENTICATED	Der Link muss authentifiziert werden.
CF_LINK_ENCRYPTED	Der Link muss verschlüsselt sein. Durch Festlegen dieses Flags wird auch das flag CF_LINK_AUTHENTICATED festgelegt.
CF_LINK_SUPPRESS_PIN	Der Profiltreiber gibt an, dass Benutzer nicht zur Eingabe einer PIN aufgefordert werden.

BtAddress

Die Bluetooth-Adresse des Geräts, für das die Verbindung vorgesehen ist.

ConfigOut

Die Unterstruktur, die Parametereinstellungen für eine BRB_L2CA_OPEN_CHANNEL an ein Remotegerät gesendeten BRB enthält.

ConfigOut.Flags

Flags, die die Anforderungen für den zu öffnenden Kanal angeben. Gültige Flagwerte sind in der folgenden Tabelle aufgeführt:

Flag	Beschreibung
CF_LINK_AUTHENTICATED	Der Link muss authentifiziert werden.
CF_LINK_ENCRYPTED	Der Link muss verschlüsselt sein. Durch Festlegen dieses Flags wird auch das flag CF_LINK_AUTHENTICATED festgelegt.
CF_LINK_SUPPRESS_PIN	Der Profiltreiber gibt an, dass Benutzer nicht zur Eingabe einer PIN aufgefordert werden.

ConfigOut.Mtu

Der Bereich der Nachrichtenübertragungseinheiten (Message Transfer Units, MTUs), der verwendet wird, um die Größe der ausgehenden Hälfte des Kanals auszuhandeln.

ConfigOut.FlushTO

Der Bereich der möglichen Werte, die für das Leerungstimeout für die ausgehende Hälfte des Kanals verwendet werden sollen.

ConfigOut.Flow

Für die zukünftige Verwendung reserviert. Nicht verwenden.

ConfigOut.LinkTO

Das Link-Manager-Linktimeout.

ConfigOut.NumExtraOptions

Die Anzahl der Arrayelemente, die im ExtraOptions-Member enthalten sind. Dieser Wert sollte für die meisten Clients null sein.

ConfigOut.ExtraOptions

Die Anzahl der Arrayelemente, die im ExtraOptions-Member enthalten sind. Dieser Wert sollte für die meisten Clients null sein.

ConfigOut.LocalQos

Für die zukünftige Verwendung reserviert. Nicht verwenden.

ConfigOut.LocalQos.ServiceType

Für die zukünftige Verwendung reserviert. Nicht verwenden.

ConfigOut.LocalQos.Latency

Für die zukünftige Verwendung reserviert. Nicht verwenden.

ConfigIn

Die Unterstruktur, die Parametereinstellungen zum Überprüfen eingehender BRB_L2CA_OPEN_CHANNEL_RESPONSE BRBs enthält, die von einem Remotegerät gesendet werden.

ConfigIn.Flags

Flags, die die Anforderungen für den zu öffnenden Kanal angeben. Gültige Flagwerte sind in der folgenden Tabelle aufgeführt:

Flag	Beschreibung
CF_LINK_AUTHENTICATED	Der Link muss authentifiziert werden.
CF_LINK_ENCRYPTED	Der Link muss verschlüsselt sein. Durch Festlegen dieses Flags wird auch das flag CF_LINK_AUTHENTICATED festgelegt.
CF_LINK_SUPPRESS_PIN	Der Profiltreiber gibt an, dass Benutzer nicht zur Eingabe einer PIN aufgefordert werden.

ConfigIn.Mtu

Der Bereich der Nachrichtenübertragungseinheiten (Message Transfer Units, MTUs), der verwendet wird, um die Größe der ausgehenden Hälfte des Kanals auszuhandeln.

ConfigIn.FlushTO

Der Bereich der möglichen Werte, die für das Leerungstimeout für die ausgehende Hälfte des Kanals verwendet werden sollen.

CallbackFlags

Ein Flag, das angibt, welche Ereignisse eine Rückrufroutine generieren sollen, um den Profiltreiber zu benachrichtigen, dass das Ereignis aufgetreten ist. Gültige Flagwerte sind in der folgenden Tabelle enthalten.

Flag	Beschreibung
CALLBACK_CONFIG_EXTRA_IN	Falls festgelegt, wird die Rückrufroutine aufgerufen, wenn die Konfigurationsanforderung für das Remotegerät zusätzliche Optionen enthält. Wenn sie nicht festgelegt sind, werden die zusätzlichen Konfigurationsoptionen als unbekannte Optionen abgelehnt. Dieses Flag wird mit BRB_L2CA_OPEN_CHANNEL_RESPONSE BRBs verwendet.
CALLBACK_CONFIG_EXTRA_OUT	Wenn diese Option festgelegt ist, wird die Rückrufroutine aufgerufen, wenn das Remotegerät eine zusätzliche Konfigurationsoption aus einer BRB_L2CA_OPEN_CHANNEL-Anforderung ablehnt. Wenn sie nicht festgelegt ist und das Remotegerät die Konfigurationsanforderung aufgrund einer zusätzlichen Option ablehnt, wird die Verbindung geschlossen.
CALLBACK_CONFIG_QOS	Falls festgelegt, wird die Rückrufroutine aufgerufen, wenn ein Remotegerät eine Konfigurationsanforderung sendet, die einen QOS-Wert enthält. Wenn dieses Flag nicht festgelegt ist und das Remotegerät entweder QOS-Parameter in einer Konfigurationsanforderung sendet oder die vom Profiltreiber angeforderten QOS-Parameter ablehnt, wird die Verbindung getrennt.
CALLBACK_DISCONNECT	Wenn festgelegt, wird die Rückrufroutine aufgerufen, wenn ein Remotegerät die Verbindung mit dem L2CAP-Kanal trennt.
CALLBACK_RECV_PACKET	Falls festgelegt, wird die Rückrufroutine aufgerufen, wenn der Profiltreiber ein eingehendes L2CAP-Paket empfängt.

Callback

Die vom Profiltreiber implementierte L2CAP-Rückruffunktion , die der Bluetooth-Treiberstapel aufrufen soll, um den Profiltreiber über Änderungen an der L2CAP-Verbindung zu informieren.

CallbackContext

Der Kontext, der an die Rückruffunktion übergeben werden soll, die im Rückrufelement angegeben ist. Der Profiltreiber definiert diesen Wert.

ReferenceObject

Ein Zeiger auf ein Objekt, das an ObReferenceObject und ObDereferenceObject übergeben werden soll , für die eine Verweisanzahl von beibehalten werden soll.

OutResults

Eine CHANNEL_CONFIG_RESULTS-Struktur , die Konfigurationsparameter für die ausgehende Anforderung enthält.

InResults

Eine CHANNEL_CONFIG_RESULTS-Struktur, die Konfigurationsparameter für die eingehende Anforderung enthält.

IncomingQueueDepth

Gibt die Länge der eingehenden Warteschlange in Nachrichtenübertragungseinheiten (Message Transfer Units, MTUs) an.

Antwort

Dieser Member wird als Eingabeparameter für eine BRB_L2CA_OPEN_CHANNEL_RESPONSE-Anforderung und als Ausgabeparameter für die BRB_L2CA_OPEN_CHANNEL-Anforderung verwendet.

Für eine BRB_L2CA_OPEN_CHANNEL_RESPONSE Anforderung enthält dieses Mitglied ein Flag, das die Antwort des Profiltreibers an das Remotegerät angibt. Gültige Flagwerte sind in der folgenden Tabelle enthalten.

Flag	Beschreibung
CONNECT_RSP_RESULT_NO_RESOURCES	Der Profiltreiber hat die Verbindung aufgrund fehlender Ressourcen abgelehnt.
CONNECT_RSP_RESULT_PENDING	Der Profiltreiber ist derzeit ausgelastet und kann die Verbindung nicht akzeptieren. Versuchen Sie es später noch einmal.
CONNECT_RSP_RESULT_PSM_NEG	Der Profiltreiber hat die Verbindung abgelehnt, weil der PSM nicht unterstützt wird.
CONNECT_RSP_RESULT_SECURITY_BLOCK	Der Profiltreiber lehnte die Verbindung aus Sicherheitsgründen ab.
CONNECT_RSP_RESULT_SUCCESS	Der Profiltreiber hat die Verbindung akzeptiert.

Für die BRB_L2CA_OPEN_CHANNEL BRB enthält dieses Element die Antwort des Remotegeräts, mit dem der Profiltreiber versucht hat, eine Verbindung herzustellen. Gültige Flagwerte sind in der folgenden Tabelle enthalten.

Flag	Beschreibung
CONNECT_RSP_RESULT_NO_RESOURCES	Das Remotegerät lehnte die Verbindung aufgrund fehlender Ressourcen ab.
CONNECT_RSP_RESULT_PSM_NEG	Das Remotegerät hat die Verbindung verweigert.
CONNECT_RSP_RESULT_SECURITY_BLOCK	Das Remotegerät lehnte die Verbindung aus Sicherheitsgründen ab.
CONNECT_RSP_RESULT_SUCCESS	Das Remotegerät hat die Verbindung akzeptiert.

ResponseStatus

Wenn während eines Aufrufs des BRB_L2CA_OPEN_CHANNEL_RESPONSE BRB der Member Response auf CONNECT_RSP_RESULT_PENDINGfestgelegt ist, ist dieser Member gültig und enthält einen der folgenden Werte:

CONNECT_RSP_STATUS_AUTHENTICATION_PENDING
CONNECT_RSP_STATUS_AUTHORIZATION_PENDING
CONNECT_RSP_STATUS_NO_INFORMATION

Hinweise

Um einen L2CAP-Kanal zu öffnen, sollten Profiltreiber eine BRB_L2CA_OPEN_CHANNEL-Anforderung erstellen und senden.

Profiltreiber, die als Clients fungieren, geben eine Zieladresse, ein PSM und eine Vielzahl von Konfigurationsparametern an.

Wenn die BRB_L2CA_OPEN_CHANNEL Anforderung erfolgreich abgeschlossen wird, stehen in den Membern OutResults und InResults eine Vielzahl von Informationen zur neu erstellten Verbindung zur Verfügung. OutResults gibt die Parameter für die ausgehende Hälfte des Kanals an, und InResults gibt die Parameter für die eingehende Hälfte des Kanals an.

Einige der Konfigurationsparameter, die in dieser Struktur übergeben werden, z. B. der Mtu-Member , sind Bereiche, die für die Aushandlung mit dem Remotefunk verwendet werden. Clients sollten ein möglichst breites Spektrum bereitstellen, um die Chancen auf eine erfolgreiche Kanalverhandlung zu erhöhen. Die Angabe einer MTU-Mindestgröße, die größer als die grundlegende MINDEST-MTU-Größe von Bluetooth ist, sollte nur dann erfolgen, wenn dies unbedingt erforderlich ist. Wenn die Aushandlung fehlschlägt, schlägt die Verbindung fehl.

Profiltreiber müssen den Speicher zum Speichern des Arrays zuordnen, das im ExtraOptions-Member gespeichert ist, und sollten diesen Speicher erst freigeben, wenn die rückruffunktion, die im Rückrufelement definiert ist, mit einer IndicationFreeExtraOptions-BenachrichtigungINDICATION_CODE wert zurückgegeben wird, der im Indication-Parameter übergeben wurde.

Das IncomingQueueDepth-Element der _BRB_L2CA_OPEN_CHANNEL-Struktur gibt die maximale Anzahl von MTUs an, die der Bluetooth-Treiberstapel empfängt und die Verbindung in die Warteschlange stellt, bevor sie verworfen werden. Wenn Sie diesen Wert auf eine sehr kleine Zahl festlegen, erhöht sich die Wahrscheinlichkeit eines Datenverlusts, während das Festlegen auf eine sehr große Zahl die Speicherauslastung erhöhen kann. Das Festlegen dieses Elements auf 10 ist eine effektive Kompromittierung.

Um eine von einem Remotegerät initiierte eingehende L2CAP-Verbindungsanforderung zu akzeptieren oder abzulehnen, sollten Profiltreiber eine BRB_L2CA_OPEN_CHANNEL_RESPONSE-Anforderung erstellen und senden.

Ein Profiltreiber sollte eine BRB_L2CA_OPEN_CHANNEL_RESPONSE-Anforderung erstellen und senden, wenn der Bluetooth-Treiberstapel die L2CAP-Rückruffunktion des Profiltreibers aufruft und IndicationRemoteConnect im Indication-Parameter der Rückruffunktion übergibt.

Basierend auf dem Wert des Response-Elements dieser Struktur akzeptiert oder lehnt der Bluetooth-Treiberstapel dann die Verbindungsanforderung ab.

Der Profiltreiber gibt an, ob die Verbindung akzeptiert werden soll, indem ein entsprechender Wert im Response-Member dieser Struktur gespeichert wird.

Nach Dem Empfang der CONNECT_RSP_RESULT_PENDING Antwort sollte der Verbindungsclient seinen Verbindungstimer zurücksetzen und auf eine aktualisierte Verbindungsantwortnachricht warten. Profiltreiber, die den BRB_L2CA_OPEN_CHANNEL_RESPONSE BRB aufrufen, bei dem das Response-Element auf CONNECT_RSP_RESULT_PENDING festgelegt ist, sollten umgehend einen zusätzlichen BRB_L2CA_OPEN_CHANNEL_RESPONSE BRB mit einem aktualisierten Verbindungswert ausgeben. Der aktualisierte Wert kann jeder der im Response-Member beschriebenen status Codes sein, einschließlich des erneuten Sendens eines CONNECT_RSP_RESULT_PENDING-Werts.

Profiltreiber müssen den Speicher zum Speichern des Arrays zuordnen, das im ExtraOptions-Member gespeichert ist, und sollten diesen Arbeitsspeicher erst freigeben, wenn die Rückruffunktion, die im Rückrufelement definiert ist, mit einer IndicationFreeExtraOptions-BenachrichtigungINDICATION_CODE wert zurückgegeben wird, der im Indication-Parameter übergeben wird.