_BRB_L2CA_OPEN_CHANNEL struttura (bthddi.h)

Articolo
03/08/2023

La struttura _BRB_L2CA_OPEN_CHANNEL descrive un canale L2CAP da aprire a un dispositivo remoto o una risposta dal driver del profilo che accetta o rifiuta una richiesta di connessione L2CAP in ingresso avviata da un dispositivo remoto.

Sintassi

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;
};

Members

Hdr

Struttura BRB_HEADER contenente informazioni sulla BRB corrente.

ChannelHandle

Handle usato per identificare la connessione in caso di connessione riuscita. Quando si invia un BRB_L2CA_OPEN_CHANNEL, questo verrà compilato al termine del BRB. Quando si invia un BRB_L2CA_OPEN_CHANNEL_RESPONSE, questo deve essere compilato dal server prima di inviare il BRB. Il valore assegnato deve essere INDICATION_PARAMETERS::ConnectionHandle passato durante IndicationRemoteConnect.

Response

Usato solo con BRB_L2CA_OPEN_CHANNEL_RESPONSE. Viene usato uno dei valori CONNECT_RSP_RESULT_Xxx.

Se il BRB restituisce uno stato di STATUS_REQUEST_NOT_ACCEPTED, Risposta conterrà la risposta negativa dall'host remoto.

ResponseStatus

Se Response è uguale a CONNECT_RSP_RESULT_PENDING, questo campo è valido. Viene usato uno dei valori CONNECT_RSP_STATUS_XXX.

Psm

Protocollo/Servizio Multiplexer (PSM) usato dal canale per connettersi al dispositivo remoto. Se usato con una richiesta di BRB_L2CA_OPEN_CHANNEL , questo membro viene impostato come campo di input. Se usato con una richiesta di BRB_L2CA_OPEN_CHANNEL_RESPONSE , questo membro viene usato come campo di output.

ChannelFlags

Flag che specificano i requisiti per l'apertura del canale. I valori di flag validi sono elencati nella tabella seguente:

Flag	Descrizione
CF_LINK_AUTHENTICATED	Il collegamento deve essere autenticato.
CF_LINK_ENCRYPTED	Il collegamento deve essere crittografato. L'impostazione di questo flag imposta anche il flag di CF_LINK_AUTHENTICATED.
CF_LINK_SUPPRESS_PIN	Il driver del profilo indica la preferenza che gli utenti non vengano richiesti per un PIN.

BtAddress

Indirizzo Bluetooth del dispositivo per il quale è prevista la connessione.

ConfigOut

Sottostruttura che contiene le impostazioni dei parametri per un BRB_L2CA_OPEN_CHANNEL BRB inviato a un dispositivo remoto.

ConfigOut.Flags

Flag che specificano i requisiti per l'apertura del canale. I valori di flag validi sono elencati nella tabella seguente:

Flag	Descrizione
CF_LINK_AUTHENTICATED	Il collegamento deve essere autenticato.
CF_LINK_ENCRYPTED	Il collegamento deve essere crittografato. L'impostazione di questo flag imposta anche il flag di CF_LINK_AUTHENTICATED.
CF_LINK_SUPPRESS_PIN	Il driver del profilo indica la preferenza che gli utenti non vengano richiesti per un PIN.

ConfigOut.Mtu

Intervallo di unità di trasferimento dei messaggi (MTUS) usate per negoziare le dimensioni della metà del canale in uscita.

ConfigOut.FlushTO

Intervallo di valori possibili da utilizzare per il timeout di scaricamento per la metà in uscita del canale.

ConfigOut.Flow

Riservato per utilizzi futuri. Non usare.

ConfigOut.LinkTO

Timeout del collegamento di Gestione collegamenti.

ConfigOut.NumExtraOptions

Numero di elementi della matrice contenuti nel membro ExtraOptions . Questo valore deve essere zero per la maggior parte dei client.

ConfigOut.ExtraOptions

Numero di elementi della matrice contenuti nel membro ExtraOptions . Questo valore deve essere zero per la maggior parte dei client.

ConfigOut.LocalQos

Riservato per utilizzi futuri. Non usare.

ConfigOut.LocalQos.ServiceType

Riservato per utilizzi futuri. Non usare.

ConfigOut.LocalQos.Latency

Riservato per utilizzi futuri. Non usare.

ConfigIn

Sottostruttura che contiene le impostazioni dei parametri per convalidare le BRB_L2CA_OPEN_CHANNEL_RESPONSE BRB in ingresso inviate da un dispositivo remoto.

ConfigIn.Flags

Flag che specificano i requisiti per l'apertura del canale. I valori di flag validi sono elencati nella tabella seguente:

Flag	Descrizione
CF_LINK_AUTHENTICATED	Il collegamento deve essere autenticato.
CF_LINK_ENCRYPTED	Il collegamento deve essere crittografato. L'impostazione di questo flag imposta anche il flag di CF_LINK_AUTHENTICATED.
CF_LINK_SUPPRESS_PIN	Il driver del profilo indica la preferenza che gli utenti non vengano richiesti per un PIN.

ConfigIn.Mtu

Intervallo di unità di trasferimento dei messaggi (MTUS) usate per negoziare le dimensioni della metà del canale in uscita.

ConfigIn.FlushTO

Intervallo di valori possibili da utilizzare per il timeout di scaricamento per la metà in uscita del canale.

CallbackFlags

Flag che specifica quali eventi devono generare una routine di callback per notificare al driver del profilo che si è verificato l'evento. I valori del flag validi sono contenuti nella tabella seguente.

Flag	Descrizione
CALLBACK_CONFIG_EXTRA_IN	Se impostato, la routine di callback verrà chiamata quando la richiesta di configurazione per il dispositivo remoto contiene opzioni aggiuntive. Se non è impostato, le opzioni di configurazione aggiuntive verranno rifiutate come opzioni sconosciute. Questo flag viene usato con BRB_L2CA_OPEN_CHANNEL_RESPONSE BRBs.
CALLBACK_CONFIG_EXTRA_OUT	Se impostato, la routine di callback verrà chiamata quando il dispositivo remoto rifiuta un'opzione di configurazione aggiuntiva da una richiesta di BRB_L2CA_OPEN_CHANNEL. Se non è impostato e il dispositivo remoto rifiuta la richiesta di configurazione a causa di un'opzione aggiuntiva, la connessione verrà chiusa.
CALLBACK_CONFIG_QOS	Se impostato, la routine di callback verrà chiamata quando un dispositivo remoto invia una richiesta di configurazione contenente un valore QOS. Se questo flag non è impostato e il dispositivo remoto invia parametri QOS in una richiesta di configurazione o rifiuta i parametri QOS richiesti dal driver del profilo, la connessione viene disconnessa.
CALLBACK_DISCONNECT	Se impostata, la routine di callback verrà chiamata quando un dispositivo remoto si disconnette dal canale L2CAP.
CALLBACK_RECV_PACKET	Se impostata, la routine di callback verrà chiamata quando il driver del profilo riceve un pacchetto L2CAP in ingresso.

Callback

La funzione di callback L2CAP implementata dal driver del profilo, che lo stack di driver Bluetooth deve chiamare per notificare al driver del profilo eventuali modifiche apportate alla connessione L2CAP.

CallbackContext

Contesto da passare alla funzione di callback specificata nel membro Callback . Il driver del profilo definisce questo valore.

ReferenceObject

Puntatore a un oggetto da passare a ObReferenceObject e ObDereferenceObject per cui mantenere un numero di riferimenti.

OutResults

Struttura CHANNEL_CONFIG_RESULTS che contiene parametri di configurazione per la richiesta in uscita.

InResults

Struttura CHANNEL_CONFIG_RESULTS che contiene parametri di configurazione per la richiesta in ingresso.

IncomingQueueDepth

Specifica la lunghezza della coda in ingresso nelle unità di trasferimento dei messaggi (MTUS).

Risposta

Questo membro viene usato come parametro di input per una richiesta di BRB_L2CA_OPEN_CHANNEL_RESPONSE e un parametro di output per la richiesta di BRB_L2CA_OPEN_CHANNEL .

Per una richiesta di BRB_L2CA_OPEN_CHANNEL_RESPONSE , questo membro contiene un flag che indica la risposta del driver del profilo al dispositivo remoto. I valori del flag validi sono contenuti nella tabella seguente.

Flag	Descrizione
CONNECT_RSP_RESULT_NO_RESOURCES	Il driver del profilo ha rifiutato la connessione a causa di una mancanza di risorse.
CONNECT_RSP_RESULT_PENDING	Il driver del profilo è attualmente occupato e non può accettare la connessione. Riprovare più tardi.
CONNECT_RSP_RESULT_PSM_NEG	Il driver del profilo ha rifiutato la connessione perché il PSM non è supportato.
CONNECT_RSP_RESULT_SECURITY_BLOCK	Il driver del profilo ha rifiutato la connessione per motivi di sicurezza.
CONNECT_RSP_RESULT_SUCCESS	Il driver del profilo ha accettato la connessione.

Per il BRB_L2CA_OPEN_CHANNEL BRB, questo membro contiene la risposta dal dispositivo remoto a cui il driver del profilo ha tentato di connettersi. I valori del flag validi sono contenuti nella tabella seguente.

Flag	Descrizione
CONNECT_RSP_RESULT_NO_RESOURCES	Il dispositivo remoto ha rifiutato la connessione a causa di una mancanza di risorse.
CONNECT_RSP_RESULT_PSM_NEG	Il dispositivo remoto ha rifiutato la connessione.
CONNECT_RSP_RESULT_SECURITY_BLOCK	Il dispositivo remoto ha rifiutato la connessione per motivi di sicurezza.
CONNECT_RSP_RESULT_SUCCESS	Il dispositivo remoto ha accettato la connessione.

ResponseStatus

Se durante una chiamata al BRB_L2CA_OPEN_CHANNEL_RESPONSE BRB il membro Response è impostato su CONNECT_RSP_RESULT_PENDING, questo membro è valido e contiene uno dei valori seguenti:

CONNECT_RSP_STATUS_AUTHENTICATION_PENDING
CONNECT_RSP_STATUS_AUTHORIZATION_PENDING
CONNECT_RSP_STATUS_NO_INFORMATION

Commenti

Per aprire un canale L2CAP, i driver di profilo devono compilare e inviare una richiesta di BRB_L2CA_OPEN_CHANNEL .

Driver di profilo che fungono da client specificano un indirizzo di destinazione, un PSM e un'ampia gamma di parametri di configurazione.

Se la richiesta di BRB_L2CA_OPEN_CHANNEL viene completata correttamente, sono disponibili diverse informazioni sulla connessione appena creata nei membri OutResults e InResults. OutResults specifica i parametri per la metà in uscita del canale e InResults specifica i parametri per la metà in ingresso del canale.

Diversi parametri di configurazione passati in questa struttura, ad esempio il membro Mtu , vengono usati per la negoziazione con la radio remota. I clienti devono fornire un intervallo più ampio possibile per aumentare le probabilità di una negoziazione del canale riuscita. Se si specifica una dimensione minima MTU maggiore della dimensione minima MTU Bluetooth di base, è consigliabile eseguire solo quando è assolutamente necessario. Se la negoziazione ha esito negativo, la connessione avrà esito negativo.

I driver del profilo devono allocare la memoria per archiviare la matrice archiviata nel membro ExtraOptions e non devono liberare questa memoria fino a quando la funzione di callback definita nel membro callback restituisce con una notifica IndicationFreeExtraOptionsINDICATION_CODE valore passato nel relativo parametro Di indicazione .

Il membro IncomingQueueDepth della struttura _BRB_L2CA_OPEN_CHANNEL specifica il numero massimo di MTUS che lo stack di driver Bluetooth riceverà e accoderà sulla connessione prima di iniziare a eliminarli. L'impostazione di questo valore su un numero molto piccolo aumenta le probabilità di perdita di dati, impostandola su un numero molto elevato può aumentare l'utilizzo della memoria. L'impostazione di questo membro su 10 è una compromissione efficace.

Per accettare o rifiutare una richiesta di connessione L2CAP in ingresso avviata da un dispositivo remoto, i driver del profilo devono compilare e inviare una richiesta di BRB_L2CA_OPEN_CHANNEL_RESPONSE .

Un driver del profilo deve compilare e inviare una richiesta di BRB_L2CA_OPEN_CHANNEL_RESPONSE quando lo stack di driver Bluetooth chiama la funzione di callback L2CAP del driver del profilo e passa Il parametro IndicationRemoteConnect nel parametro Di indicazione della funzione di callback.

In base al valore del membro Response di questa struttura, lo stack di driver Bluetooth accetterà o rifiuterà la richiesta di connessione.

Il driver del profilo specifica se la connessione deve essere accettata archiviando un valore appropriato nel membro Response di questa struttura.

Dopo aver ricevuto la risposta CONNECT_RSP_RESULT_PENDING, il client di connessione deve reimpostare il timer di connessione e attendere un messaggio di risposta di connessione aggiornato. I driver del profilo che chiamano il BRB_L2CA_OPEN_CHANNEL_RESPONSE BRB in cui il membro Response è impostato su CONNECT_RSP_RESULT_PENDING deve generare tempestivamente un BRB_L2CA_OPEN_CHANNEL_RESPONSE BRB aggiuntivo con un valore di connessione aggiornato. Il valore aggiornato può essere uno dei codici di stato descritti nel membro Response , incluso il reinnding di un valore CONNECT_RSP_RESULT_PENDING.

I driver del profilo devono allocare la memoria per archiviare la matrice archiviata nel membro ExtraOptions e non devono liberare questa memoria finché la funzione di callback definita nel membro callback restituisce con una notifica IndicationFreeExtraOptionsINDICATION_CODE valore passato nel relativo parametro Di indicazione .