estructura _BRB_L2CA_OPEN_CHANNEL (bthddi.h)

Artículo
03/08/2023

La estructura de _BRB_L2CA_OPEN_CHANNEL describe un canal L2CAP para abrirlo a un dispositivo remoto o una respuesta del controlador de perfil que acepta o rechaza una solicitud de conexión L2CAP entrante iniciada por un dispositivo remoto.

Sintaxis

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

Miembros

Hdr

Estructura BRB_HEADER que contiene información sobre el BRB actual.

ChannelHandle

Identificador usado para identificar la conexión tras una conexión correcta. Al enviar un BRB_L2CA_OPEN_CHANNEL, se rellenará cuando se complete el BRB. Al enviar un BRB_L2CA_OPEN_CHANNEL_RESPONSE, el servidor debe rellenarlo antes de enviar el BRB. El valor asignado debe ser INDICATION_PARAMETERS::ConnectionHandle el que se pasó durante IndicationRemoteConnect.

Response

Solo se usa con BRB_L2CA_OPEN_CHANNEL_RESPONSE. Se usa uno de los valores de CONNECT_RSP_RESULT_Xxx.

Si el BRB devuelve con un estado de STATUS_REQUEST_NOT_ACCEPTED, Response contendrá la respuesta negativa del host remoto.

ResponseStatus

Si Response es igual a CONNECT_RSP_RESULT_PENDING, este campo es válido. Se usa uno de los valores de CONNECT_RSP_STATUS_XXX.

Psm

Multiplexador de protocolo/servicio (PSM) que usa el canal para conectarse al dispositivo remoto. Cuando se usa con una solicitud de BRB_L2CA_OPEN_CHANNEL , este miembro se establece como un campo de entrada. Cuando se usa con una solicitud de BRB_L2CA_OPEN_CHANNEL_RESPONSE , este miembro se usa como campo de salida.

ChannelFlags

Marcas que especifican los requisitos para que se abra el canal. Los valores de marca válidos se enumeran en la tabla siguiente:

Marca	Descripción
CF_LINK_AUTHENTICATED	El vínculo debe autenticarse.
CF_LINK_ENCRYPTED	El vínculo debe cifrarse. Al establecer esta marca también se establece la marca CF_LINK_AUTHENTICATED.
CF_LINK_SUPPRESS_PIN	El controlador de perfil indica su preferencia de que no se pida a los usuarios un PIN.

BtAddress

La dirección Bluetooth del dispositivo para el que está pensada la conexión.

ConfigOut

Subestructura que contiene la configuración de parámetros de un BRB_L2CA_OPEN_CHANNEL BRB enviado a un dispositivo remoto.

ConfigOut.Flags

Marcas que especifican los requisitos para que se abra el canal. Los valores de marca válidos se enumeran en la tabla siguiente:

Marca	Descripción
CF_LINK_AUTHENTICATED	El vínculo debe autenticarse.
CF_LINK_ENCRYPTED	El vínculo debe cifrarse. Al establecer esta marca también se establece la marca CF_LINK_AUTHENTICATED.
CF_LINK_SUPPRESS_PIN	El controlador de perfil indica su preferencia de que no se pida a los usuarios un PIN.

ConfigOut.Mtu

Intervalo de unidades de transferencia de mensajes (MTU) que se usan para negociar el tamaño de la mitad de salida del canal.

ConfigOut.FlushTO

Intervalo de valores posibles que se usarán para el tiempo de espera de vaciado de la mitad de salida del canal.

ConfigOut.Flow

Reservado para uso futuro. No debe usarse.

ConfigOut.LinkTO

Tiempo de espera del vínculo del Administrador de vínculos.

ConfigOut.NumExtraOptions

Número de elementos de matriz contenidos en el miembro ExtraOptions . Este valor debe ser cero para la mayoría de los clientes.

ConfigOut.ExtraOptions

Número de elementos de matriz contenidos en el miembro ExtraOptions . Este valor debe ser cero para la mayoría de los clientes.

ConfigOut.LocalQos

Reservado para uso futuro. No debe usarse.

ConfigOut.LocalQos.ServiceType

Reservado para uso futuro. No debe usarse.

ConfigOut.LocalQos.Latency

Reservado para uso futuro. No debe usarse.

ConfigIn

Subestructura que contiene la configuración de parámetros para validar los BRB entrantes BRB_L2CA_OPEN_CHANNEL_RESPONSE que se envían desde un dispositivo remoto.

ConfigIn.Flags

Marcas que especifican los requisitos para que se abra el canal. Los valores de marca válidos se enumeran en la tabla siguiente:

Marca	Descripción
CF_LINK_AUTHENTICATED	El vínculo debe autenticarse.
CF_LINK_ENCRYPTED	El vínculo debe cifrarse. Al establecer esta marca también se establece la marca CF_LINK_AUTHENTICATED.
CF_LINK_SUPPRESS_PIN	El controlador de perfil indica su preferencia de que no se pida a los usuarios un PIN.

ConfigIn.Mtu

Intervalo de unidades de transferencia de mensajes (MTU) que se usan para negociar el tamaño de la mitad de salida del canal.

ConfigIn.FlushTO

Intervalo de valores posibles que se usarán para el tiempo de espera de vaciado de la mitad de salida del canal.

CallbackFlags

Marca que especifica qué eventos deben generar una rutina de devolución de llamada para notificar al controlador de perfil que se ha producido el evento. Los valores de marca válidos se encuentran en la tabla siguiente.

Marca	Descripción
CALLBACK_CONFIG_EXTRA_IN	Si se establece, se llamará a la rutina de devolución de llamada cuando la solicitud de configuración del dispositivo remoto contenga opciones adicionales. Si no se establece, las opciones de configuración adicionales se rechazarán como opciones desconocidas. Esta marca se usa con BRB_L2CA_OPEN_CHANNEL_RESPONSE BRB.
CALLBACK_CONFIG_EXTRA_OUT	Si se establece, se llamará a la rutina de devolución de llamada cuando el dispositivo remoto rechace una opción de configuración adicional de una solicitud de BRB_L2CA_OPEN_CHANNEL. Si no se establece y el dispositivo remoto rechaza la solicitud de configuración debido a una opción adicional, se cerrará la conexión.
CALLBACK_CONFIG_QOS	Si se establece, se llamará a la rutina de devolución de llamada cuando un dispositivo remoto envíe una solicitud de configuración que contenga un valor de QOS. Si no se establece esta marca y el dispositivo remoto envía parámetros QOS en una solicitud de configuración o rechaza los parámetros de QOS solicitados del controlador de perfil, la conexión se desconecta.
CALLBACK_DISCONNECT	Si se establece, se llamará a la rutina de devolución de llamada cuando un dispositivo remoto se desconecte del canal L2CAP.
CALLBACK_RECV_PACKET	Si se establece, se llamará a la rutina de devolución de llamada cuando el controlador de perfil reciba un paquete L2CAP entrante.

Callback

La función de devolución de llamada L2CAP implementada por el controlador de perfil, que la pila del controlador Bluetooth debe llamar para notificar al controlador de perfil los cambios realizados en la conexión L2CAP.

CallbackContext

Contexto que se va a pasar a la función de devolución de llamada especificada en el miembro Devolución de llamada. El controlador de perfil define este valor.

ReferenceObject

Puntero a un objeto que se va a pasar a ObReferenceObject y ObDereferenceObject para el que se debe mantener un recuento de referencias.

OutResults

Estructura CHANNEL_CONFIG_RESULTS que contiene parámetros de configuración para la solicitud saliente.

InResults

Estructura CHANNEL_CONFIG_RESULTS que contiene parámetros de configuración para la solicitud entrante.

IncomingQueueDepth

Especifica la longitud de la cola entrante en unidades de transferencia de mensajes (MTU).

Response

Este miembro se usa como parámetro de entrada para una solicitud de BRB_L2CA_OPEN_CHANNEL_RESPONSE y un parámetro de salida para la solicitud BRB_L2CA_OPEN_CHANNEL .

Para una solicitud de BRB_L2CA_OPEN_CHANNEL_RESPONSE , este miembro contiene una marca que indica la respuesta del controlador de perfil al dispositivo remoto. Los valores de marca válidos se encuentran en la tabla siguiente.

Marca	Descripción
CONNECT_RSP_RESULT_NO_RESOURCES	El controlador de perfil rechazó la conexión debido a una falta de recursos.
CONNECT_RSP_RESULT_PENDING	El controlador de perfil está ocupado actualmente y no puede aceptar la conexión. Vuelva a intentarlo más tarde.
CONNECT_RSP_RESULT_PSM_NEG	El controlador de perfil rechazó la conexión porque no se admite PSM.
CONNECT_RSP_RESULT_SECURITY_BLOCK	El controlador de perfil rechazó la conexión por motivos de seguridad.
CONNECT_RSP_RESULT_SUCCESS	El controlador de perfil aceptó la conexión.

Para el BRB_L2CA_OPEN_CHANNEL BRB, este miembro contiene la respuesta del dispositivo remoto al que el controlador de perfil intentó conectarse. Los valores de marca válidos se encuentran en la tabla siguiente.

Marca	Descripción
CONNECT_RSP_RESULT_NO_RESOURCES	El dispositivo remoto rechazó la conexión debido a una falta de recursos.
CONNECT_RSP_RESULT_PSM_NEG	El dispositivo remoto rechazó la conexión.
CONNECT_RSP_RESULT_SECURITY_BLOCK	El dispositivo remoto rechazó la conexión por motivos de seguridad.
CONNECT_RSP_RESULT_SUCCESS	El dispositivo remoto aceptó la conexión.

ResponseStatus

Si durante una llamada al BRB_L2CA_OPEN_CHANNEL_RESPONSE BRB, el miembro Response se establece CONNECT_RSP_RESULT_PENDINGen , este miembro es válido y contiene uno de los valores siguientes:

CONNECT_RSP_STATUS_AUTHENTICATION_PENDING
CONNECT_RSP_STATUS_AUTHORIZATION_PENDING
CONNECT_RSP_STATUS_NO_INFORMATION

Comentarios

Para abrir un canal L2CAP, los controladores de perfil deben compilar y enviar una solicitud de BRB_L2CA_OPEN_CHANNEL .

Los controladores de perfil que actúan como clientes especifican una dirección de destino, un PSM y una variedad de parámetros de configuración.

Si la solicitud de BRB_L2CA_OPEN_CHANNEL se completa correctamente, hay disponible una variedad de información sobre la conexión recién creada en los miembros OutResults e InResults . OutResults especifica los parámetros de la mitad de salida del canal y InResults especifica los parámetros de la mitad entrante del canal.

Varios de los parámetros de configuración pasados en esta estructura, como el miembro Mtu , son rangos utilizados para la negociación con la radio remota. Los clientes deben proporcionar una gama lo más amplia posible para aumentar las posibilidades de negociación correcta del canal. La especificación de un tamaño mínimo de MTU mayor que el tamaño mínimo de MTU de Bluetooth básico solo debe realizarse cuando sea absolutamente necesario. Si se produce un error en la negociación, se producirá un error en la conexión.

Los controladores de perfil deben asignar la memoria para almacenar la matriz almacenada en el miembro ExtraOptions y no deben liberar esta memoria hasta que la función de devolución de llamada definida en el miembro devolución de llamada devuelva con una notificación IndicationFreeExtraOptionsINDICATION_CODE valor pasado en su parámetro De indicación .

El miembro IncomingQueueDepth de la estructura _BRB_L2CA_OPEN_CHANNEL especifica el número máximo de MTUs que la pila del controlador Bluetooth recibirá y pondrá en cola en la conexión antes de empezar a descartarlas. Establecer este valor en un número muy pequeño aumenta las posibilidades de pérdida de datos, mientras que establecerlo en un número muy grande puede aumentar el uso de memoria. Establecer este miembro en 10 es un compromiso efectivo.

Para aceptar o rechazar una solicitud de conexión L2CAP entrante iniciada por un dispositivo remoto, los controladores de perfil deben compilar y enviar una solicitud de BRB_L2CA_OPEN_CHANNEL_RESPONSE .

Un controlador de perfil debe compilar y enviar una solicitud de BRB_L2CA_OPEN_CHANNEL_RESPONSE cuando la pila del controlador Bluetooth llama a la función de devolución de llamada L2CAP del controlador de perfil y pasa IndicationRemoteConnect en el parámetro De indicación de la función de devolución de llamada.

Según el valor del miembro Response de esta estructura, la pila del controlador Bluetooth aceptará o rechazará la solicitud de conexión.

El controlador de perfil especifica si la conexión debe aceptarse almacenando un valor adecuado en el miembro Response de esta estructura.

Después de recibir la respuesta CONNECT_RSP_RESULT_PENDING, el cliente de conexión debe restablecer su temporizador de conexión y esperar un mensaje de respuesta de conexión actualizado. Los controladores de perfil que llaman al BRB BRB_L2CA_OPEN_CHANNEL_RESPONSE donde el miembro Response está establecido en CONNECT_RSP_RESULT_PENDING deben emitir rápidamente un brB de BRB_L2CA_OPEN_CHANNEL_RESPONSE adicional con un valor de conexión actualizado. El valor actualizado puede ser cualquiera de los códigos de estado descritos en el miembro Response , incluido el reenvío de un valor de CONNECT_RSP_RESULT_PENDING.

Los controladores de perfil deben asignar la memoria para almacenar la matriz almacenada en el miembro ExtraOptions y no deben liberar esta memoria hasta que la función de devolución de llamada definida en el miembro Callback devuelva con una notificación IndicationFreeExtraOptionsINDICATION_CODE valor pasado en su parámetro De indicación .