_BRB_L2CA_OPEN_CHANNEL structure (bthddi.h)

Article
08/07/2023

La structure _BRB_L2CA_OPEN_CHANNEL décrit un canal L2CAP à ouvrir sur un appareil distant, ou une réponse du pilote de profil qui accepte ou rejette une demande de connexion L2CAP entrante initiée par un appareil distant.

Syntaxe

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

Membres

Hdr

Structure BRB_HEADER qui contient des informations sur le BRB actuel.

ChannelHandle

Handle utilisé pour identifier la connexion lors d’une connexion réussie. Lors de l’envoi d’une BRB_L2CA_OPEN_CHANNEL, celle-ci est renseignée lorsque le BRB se termine. Lors de l’envoi d’un BRB_L2CA_OPEN_CHANNEL_RESPONSE, celui-ci doit être renseigné par le serveur avant d’envoyer le BRB. La valeur affectée doit être INDICATION_PARAMETERS::ConnectionHandle celle qui a été passée pendant IndicationRemoteConnect.

Response

Utilisé uniquement avec BRB_L2CA_OPEN_CHANNEL_RESPONSE. L’une des valeurs CONNECT_RSP_RESULT_Xxx est utilisée.

Si le BRB retourne avec une status de STATUS_REQUEST_NOT_ACCEPTED, Response contient la réponse négative de l’hôte distant.

ResponseStatus

Si La réponse est égale à CONNECT_RSP_RESULT_PENDING, ce champ est valide. L’une des valeurs CONNECT_RSP_STATUS_XXX est utilisée.

Psm

Multiplexeur de protocole/service (PSM) que le canal utilise pour se connecter à l’appareil distant. Lorsqu’il est utilisé avec une demande de BRB_L2CA_OPEN_CHANNEL , ce membre est défini en tant que champ d’entrée. Lorsqu’il est utilisé avec une demande de BRB_L2CA_OPEN_CHANNEL_RESPONSE , ce membre est utilisé comme champ de sortie.

ChannelFlags

Indicateurs qui spécifient la configuration requise pour l’ouverture du canal. Les valeurs d’indicateur valides sont répertoriées dans le tableau suivant :

Indicateur	Description
CF_LINK_AUTHENTICATED	Le lien doit être authentifié.
CF_LINK_ENCRYPTED	Le lien doit être chiffré. La définition de cet indicateur définit également l’indicateur CF_LINK_AUTHENTICATED.
CF_LINK_SUPPRESS_PIN	Le pilote de profil indique qu’il préfère que les utilisateurs ne soient pas invités à entrer un code confidentiel.

BtAddress

Adresse Bluetooth de l’appareil pour lequel la connexion est prévue.

ConfigOut

Sous-structure qui contient les paramètres d’un BRB_L2CA_OPEN_CHANNEL BRB envoyé à un appareil distant.

ConfigOut.Flags

Indicateurs qui spécifient la configuration requise pour l’ouverture du canal. Les valeurs d’indicateur valides sont répertoriées dans le tableau suivant :

Indicateur	Description
CF_LINK_AUTHENTICATED	Le lien doit être authentifié.
CF_LINK_ENCRYPTED	Le lien doit être chiffré. La définition de cet indicateur définit également l’indicateur CF_LINK_AUTHENTICATED.
CF_LINK_SUPPRESS_PIN	Le pilote de profil indique qu’il préfère que les utilisateurs ne soient pas invités à entrer un code confidentiel.

ConfigOut.Mtu

Plage d’unités de transfert de messages (MTU) utilisée pour négocier la taille de la moitié sortante du canal.

ConfigOut.FlushTO

Plage de valeurs possibles à utiliser pour le délai d’expiration du vidage pour la moitié sortante du canal.

ConfigOut.Flow

Réservé pour un usage futur. Ne pas utiliser.

ConfigOut.LinkTO

Délai d’expiration du lien du Gestionnaire de liens.

ConfigOut.NumExtraOptions

Nombre d’éléments de tableau contenus dans le membre ExtraOptions . Cette valeur doit être égale à zéro pour la plupart des clients.

ConfigOut.ExtraOptions

Nombre d’éléments de tableau contenus dans le membre ExtraOptions . Cette valeur doit être égale à zéro pour la plupart des clients.

ConfigOut.LocalQos

Réservé pour un usage futur. Ne pas utiliser.

ConfigOut.LocalQos.ServiceType

Réservé pour un usage futur. Ne pas utiliser.

ConfigOut.LocalQos.Latency

Réservé pour un usage futur. Ne pas utiliser.

ConfigIn

Sous-structure qui contient des paramètres pour valider les BRB_L2CA_OPEN_CHANNEL_RESPONSE brbs entrants envoyés à partir d’un appareil distant.

ConfigIn.Flags

Indicateurs qui spécifient la configuration requise pour l’ouverture du canal. Les valeurs d’indicateur valides sont répertoriées dans le tableau suivant :

Indicateur	Description
CF_LINK_AUTHENTICATED	Le lien doit être authentifié.
CF_LINK_ENCRYPTED	Le lien doit être chiffré. La définition de cet indicateur définit également l’indicateur CF_LINK_AUTHENTICATED.
CF_LINK_SUPPRESS_PIN	Le pilote de profil indique qu’il préfère que les utilisateurs ne soient pas invités à entrer un code confidentiel.

ConfigIn.Mtu

Plage d’unités de transfert de messages (MTU) utilisée pour négocier la taille de la moitié sortante du canal.

ConfigIn.FlushTO

Plage de valeurs possibles à utiliser pour le délai d’expiration du vidage pour la moitié sortante du canal.

CallbackFlags

Indicateur qui spécifie les événements qui doivent générer une routine de rappel pour informer le pilote de profil que l’événement s’est produit. Les valeurs d’indicateur valides sont contenues dans le tableau suivant.

Indicateur	Description
CALLBACK_CONFIG_EXTRA_IN	Si elle est définie, la routine de rappel est appelée lorsque la demande de configuration pour l’appareil distant contient des options supplémentaires. Si elles ne sont pas définies, les options de configuration supplémentaires sont rejetées en tant qu’options inconnues. Cet indicateur est utilisé avec BRB_L2CA_OPEN_CHANNEL_RESPONSE brbs.
CALLBACK_CONFIG_EXTRA_OUT	Si elle est définie, la routine de rappel est appelée lorsque l’appareil distant rejette une option de configuration supplémentaire à partir d’une demande de BRB_L2CA_OPEN_CHANNEL. S’il n’est pas défini et que l’appareil distant rejette la demande de configuration en raison d’une option supplémentaire, la connexion est fermée.
CALLBACK_CONFIG_QOS	Si elle est définie, la routine de rappel est appelée lorsqu’un appareil distant envoie une demande de configuration qui contient une valeur QOS. Si cet indicateur n’est pas défini et que l’appareil distant envoie des paramètres QOS dans une demande de configuration ou rejette les paramètres QOS demandés par le pilote de profil, la connexion est déconnectée.
CALLBACK_DISCONNECT	Si elle est définie, la routine de rappel est appelée lorsqu’un appareil distant se déconnecte du canal L2CAP.
CALLBACK_RECV_PACKET	Si elle est définie, la routine de rappel est appelée lorsque le pilote de profil reçoit un paquet L2CAP entrant.

Callback

Fonction de rappel L2CAP implémentée par le pilote de profil, que la pile de pilotes Bluetooth doit appeler pour informer le pilote de profil de toute modification apportée à la connexion L2CAP.

CallbackContext

Contexte à passer à la fonction de rappel spécifiée dans le membre Callback . Le pilote de profil définit cette valeur.

ReferenceObject

Pointeur vers un objet à passer à ObReferenceObject et ObDereferenceObject pour lequel conserver un nombre de références.

OutResults

Structure CHANNEL_CONFIG_RESULTS qui contient des paramètres de configuration pour la requête sortante.

InResults

Structure CHANNEL_CONFIG_RESULTS qui contient des paramètres de configuration pour la requête entrante.

IncomingQueueDepth

Spécifie la longueur de la file d’attente entrante dans les unités de transfert de messages (MTU).

response

Ce membre est utilisé comme paramètre d’entrée pour une demande BRB_L2CA_OPEN_CHANNEL_RESPONSE et comme paramètre de sortie pour la demande BRB_L2CA_OPEN_CHANNEL .

Pour une demande de BRB_L2CA_OPEN_CHANNEL_RESPONSE , ce membre contient un indicateur qui indique la réponse du pilote de profil à l’appareil distant. Les valeurs d’indicateur valides sont contenues dans le tableau suivant.

Indicateur	Description
CONNECT_RSP_RESULT_NO_RESOURCES	Le pilote de profil a refusé la connexion en raison d’un manque de ressources.
CONNECT_RSP_RESULT_PENDING	Le pilote de profil est actuellement occupé et ne peut pas accepter la connexion. Réessayez plus tard.
CONNECT_RSP_RESULT_PSM_NEG	Le pilote de profil a refusé la connexion, car le module PSM n’est pas pris en charge.
CONNECT_RSP_RESULT_SECURITY_BLOCK	Le pilote de profil a refusé la connexion pour des raisons de sécurité.
CONNECT_RSP_RESULT_SUCCESS	Le pilote de profil a accepté la connexion.

Pour le BRB_L2CA_OPEN_CHANNEL BRB, ce membre contient la réponse de l’appareil distant auquel le pilote de profil a tenté de se connecter. Les valeurs d’indicateur valides sont contenues dans le tableau suivant.

Indicateur	Description
CONNECT_RSP_RESULT_NO_RESOURCES	L’appareil distant a refusé la connexion en raison d’un manque de ressources.
CONNECT_RSP_RESULT_PSM_NEG	L’appareil distant a refusé la connexion.
CONNECT_RSP_RESULT_SECURITY_BLOCK	L’appareil distant a refusé la connexion pour des raisons de sécurité.
CONNECT_RSP_RESULT_SUCCESS	L’appareil distant a accepté la connexion.

ResponseStatus

Si, lors d’un appel à l’BRB_L2CA_OPEN_CHANNEL_RESPONSE BRB, le membre Response est défini sur CONNECT_RSP_RESULT_PENDING, ce membre est valide et contient l’une des valeurs suivantes :

CONNECT_RSP_STATUS_AUTHENTICATION_PENDING
CONNECT_RSP_STATUS_AUTHORIZATION_PENDING
CONNECT_RSP_STATUS_NO_INFORMATION

Remarques

Pour ouvrir un canal L2CAP, les pilotes de profil doivent générer et envoyer une demande de BRB_L2CA_OPEN_CHANNEL .

Les pilotes de profil qui agissent en tant que clients spécifient une adresse de destination, un module PSM et divers paramètres de configuration.

Si la demande BRB_L2CA_OPEN_CHANNEL se termine correctement, diverses informations sur la connexion nouvellement créée sont disponibles dans les membres OutResults et InResults . OutResults spécifie les paramètres de la moitié sortante du canal, et InResults spécifie les paramètres de la moitié entrante du canal.

Plusieurs des paramètres de configuration passés dans cette structure, tels que le membre Mtu , sont des plages utilisées pour la négociation avec la radio distante. Les clients doivent fournir une gamme aussi large que possible pour augmenter les chances de réussite de la négociation de canal. La spécification d’une taille MTU minimale supérieure à la taille MTU minimale Bluetooth de base ne doit être effectuée que lorsque cela est absolument nécessaire. Si la négociation échoue, la connexion échoue.

Les pilotes de profil doivent allouer la mémoire pour stocker le tableau stocké dans le membre ExtraOptions et ne doivent pas libérer cette mémoire tant que la fonction de rappel définie dans le membre callback n’est pas retournée avec une notification IndicationFreeExtraOptionsINDICATION_CODE valeur passée dans son paramètre Indication .

Le membre IncomingQueueDepth de la structure _BRB_L2CA_OPEN_CHANNEL spécifie le nombre maximal de MTU que la pile de pilotes Bluetooth recevra et mettra en file d’attente sur la connexion avant qu’elle ne commence à les ignorer. La définition de cette valeur sur un très petit nombre augmente les risques de perte de données, tandis que sa définition sur un très grand nombre peut augmenter l’utilisation de la mémoire. Définir ce membre sur 10 est un compromis efficace.

Pour accepter ou rejeter une demande de connexion L2CAP entrante initiée par un appareil distant, les pilotes de profil doivent générer et envoyer une demande de BRB_L2CA_OPEN_CHANNEL_RESPONSE .

Un pilote de profil doit générer et envoyer une requête BRB_L2CA_OPEN_CHANNEL_RESPONSE lorsque la pile de pilotes Bluetooth appelle la fonction de rappel L2CAP du pilote de profil et transmet IndicationRemoteConnect dans le paramètre Indication de la fonction de rappel.

En fonction de la valeur du membre Response de cette structure, la pile de pilotes Bluetooth accepte ou rejette la demande de connexion.

Le pilote de profil spécifie si la connexion doit être acceptée en stockant une valeur appropriée dans le membre Response de cette structure.

Lors de la réception de la réponse CONNECT_RSP_RESULT_PENDING, le client de connexion doit réinitialiser son minuteur de connexion et attendre un message de réponse de connexion mis à jour. Les pilotes de profil appelant le BRB_L2CA_OPEN_CHANNEL_RESPONSE BRB où le membre Response est défini sur CONNECT_RSP_RESULT_PENDING doivent émettre rapidement une BRB_L2CA_OPEN_CHANNEL_RESPONSE BRB supplémentaire avec une valeur de connexion mise à jour. La valeur mise à jour peut être l’un des codes status décrits dans le membre Response, y compris le renvoi d’une valeur CONNECT_RSP_RESULT_PENDING.

Les pilotes de profil doivent allouer la mémoire pour stocker le tableau stocké dans le membre ExtraOptions et ne doivent pas libérer cette mémoire tant que la fonction de rappel définie dans le membre Callback n’est pas retournée avec une notification IndicationFreeExtraOptionsINDICATION_CODE valeur passée dans son paramètre Indication .