IOCTL_BTH_HCI_VENDOR_COMMAND IOCTL (bthioctl.h)

Article
02/06/2025

La requête IOCTL_BTH_HCI_VENDOR_COMMAND permet aux applications Bluetooth d’envoyer des commandes spécifiques au fournisseur aux radios.

Code principal

IRP_MJ_DEVICE_CONTROL

Mémoire tampon d’entrée

Le membre AssociatedIrp.SystemBuffer pointe vers une structure BTH_VENDOR_SPECIFIC_COMMAND. La structure contient un identificateur de fabricant, une version de protocole de gestion des liens (LMP), un en-tête de commande HCI et les données de commande du fournisseur associées qui incluent des données de modèle facultatives pour faire correspondre un événement à la commande.

Longueur de la mémoire tampon d’entrée

Longueur d’une structure BTH_VENDOR_SPECIFIC_COMMAND.

Mémoire tampon de sortie

Le membre AssociatedIrp.SystemBuffer pointe vers une mémoire tampon qui contient les données d’événement retournées par la radio. Les données sont disponibles dans le membre EventInfo de la structure BTH_VENDOR_EVENT_INFO.

typedef struct _BTH_VENDOR_EVENT_INFO {
  BTH_ADDR BthAddress;
  ULONG    EventSize;
  UCHAR    EventInfo[1];
} BTH_VENDOR_EVENT_INFO, *PBTH_VENDOR_EVENT_INFO;

Le membre EventSize fournit la taille des données d’événement spécifiques au fournisseur retournées par la radio.

Longueur de la mémoire tampon de sortie

Longueur d’une structure BTH_VENDOR_EVENT_INFO.

Bloc d’état

Si la requête réussit, l'Information membre de la structure STATUS_BLOCK est défini sur la taille, en octets, de la mémoire tampon qui contient la réponse de commande.

Le membre Status est défini sur l’une des valeurs du tableau suivant.

Valeur d’état	Description
STATUS_SUCCESS	Le IOCTL s’est terminé avec succès.
STATUS_BUFFER_TOO_SMALL	La mémoire tampon d’entrée qui a été passée était trop petite.
STATUS_INVALID_PARAMETER	La mémoire tampon d’entrée qui a été passée n’était pas valide.
STATUS_PRIVILEGE_NOT_HELD	L’appelant n’a pas les privilèges requis.
STATUS_INSUFFICIENT_RESOURCES	La mémoire disponible était insuffisante pour traiter la requête.

Remarques

La demande IOCTL_BTH_HCI_VENDOR_COMMAND fournit un mécanisme qui permet aux fournisseurs de créer des commandes spécifiques à leurs radios Bluetooth.

Valeurs de version de l’ID du fabricant et du protocole de gestion des liens (LMP) qui se trouvent dans le BTH_VENDOR_SPECIFIC_COMMAND structure permet d’empêcher l’envoi de commandes spécifiques au fournisseur à la radio incorrecte. La version LMP permet aux fournisseurs d’envoyer des commandes spécifiques au fournisseur aux radios qui ont une version LMP correspondante. Si la version LMP est égale à zéro, toutes les radios de ce fournisseur recevront la commande spécifique au fournisseur.

Les modèles sont requis si une commande spécifique au fournisseur ne suit pas le contrôle de flux HCI standard et qu’un événement spécifique au fournisseur est généré en réponse à la commande spécifique au fournisseur.

Si des modèles sont requis, la commande doit être suivie d'BTH_VENDOR_PATTERN structures pour les modèles présents dans l’événement. Ces modèles permettent à la pile de pilotes Bluetooth de faire correspondre les événements spécifiques au fournisseur avec les commandes spécifiques au fournisseur correspondantes.

La structure BTH_VENDOR_PATTERN spécifie de tels modèles qui suivent les données de commande spécifiques au fournisseur spécifiées dans le membre Data de BTH_VENDOR_SPECIFIC_COMMAND structure. La taille totale maximale de tous les modèles qui suivent la commande ne doit pas être supérieure à 255.

Avertissement Le processus qui envoie des IOCTL_BTH_HCI_VENDOR_COMMAND doit avoir le privilège de SE_LOAD_DRIVER_NAME. Un processus qui s’exécute dans le système ou un contexte d’administrateur peut élever ses privilèges à l’aide du Kit de développement logiciel (SDK) LookupPrivilegeValue et fonctions AdjustTokenPrivileges. L’exemple de code suivant montre comment obtenir ce privilège. Notez que l’exemple ne montre pas la gestion des erreurs.

HANDLE procToken;
LUID luid;
TOKEN_PRIVILEGES tp;

OpenProcessToken(GetCurrentProcess(), TOKEN_ADJUST_PRIVILEGES | TOKEN_QUERY, &procToken);

LookupPrivilegeValue(NULL, SE_LOAD_DRIVER_NAME, &luid);

Tp.PrivilegeCount = 1;
Tp.privileges[0].Luid = luid;
Tp.Privileges[0].Attributes = SE_PRIVILEGE_ENABLED;

AdjustTokenPrivileges(procToken, FALSE, &tp, sizeof(TOKEN_PRIVILEGES), (PTOKEN_PRIVILEGES) NULL, (PDWORD)NULL);

L’événement généré en raison de cette commande est copié dans la mémoire tampon de sortie (y compris l’en-tête d’événement).

Exigences

Exigence	Valeur
client minimum pris en charge	Versions :_Available sur Microsoft Windows Vista SP2 et versions ultérieures du système d’exploitation.
d’en-tête	bthioctl.h (include Bthioctl.h)
IRQL	<= PASSIVE_LEVEL