Función BluetoothGATTGetCharacteristics (bluetoothleapis.h)

La función BluetoothGATTGetCharacteristics obtiene todas las características disponibles para el servicio especificado.

Sintaxis

HRESULT BluetoothGATTGetCharacteristics(
  [in]            HANDLE                      hDevice,
  [in, optional]  PBTH_LE_GATT_SERVICE        Service,
  [in]            USHORT                      CharacteristicsBufferCount,
  [out, optional] PBTH_LE_GATT_CHARACTERISTIC CharacteristicsBuffer,
  [out]           USHORT                      *CharacteristicsBufferActual,
  [in]            ULONG                       Flags
);

Parámetros

[in] hDevice

Controle el dispositivo o el servicio Bluetooth.

[in, optional] Service

Dirección de una estructura de BTH_LE_GATT_SERVICE que contiene el servicio primario de los servicios incluidos que se van a recuperar. Este parámetro es necesario si se pasa un identificador de dispositivo a hDevice. Este parámetro es opcional si se pasó un identificador de servicio a hDevice, en cuyo caso el servicio especificado por el identificador de servicio se tratará como primario.

[in] CharacteristicsBufferCount

Número de elementos asignados para el parámetro CharacteristicsBuffer .

[out, optional] CharacteristicsBuffer

Puntero a un búfer en el que se van a devolver características como una matriz de estructuras de BTH_LE_GATT_CHARACTERISTIC .

[out] CharacteristicsBufferActual

Puntero al búfer en el que se devuelve el número real de características que se devolvieron en el parámetro CharacteristicsBuffer .

[in] Flags

Marcas para modificar el comportamiento de BluetoothGATTGetCharacteristics:

Marca	Descripción
BLUETOOTH_GATT_FLAG_NONE	El cliente no tiene requisitos gatt específicos (valor predeterminado).

Valor devuelto

Esta función devuelve los valores siguientes:

Código devuelto	Descripción
S_OK	La operación se ha completado correctamente.
ERROR_MORE_DATA	El parámetro de búfer es NULL y el número de elementos disponibles se devuelve en su lugar.
ERROR_ACCESS_DENIED	Se devuelve si se proporciona un servicio primario y un identificador de servicio y la jerarquía de servicios no se acumula en el identificador de servicio primario proporcionado.
ERROR_INVALID_PARAMETER	Se produjo una de las siguientes condiciones: CharacteristicsBuffer es NULL y CharacteristicsBufferCount es 0 CharacteristicsBuffer no es NULL, pero CharacteristicsBufferCount es NULL CharacteristicsBuffer no es NULL y CharacteristicsBufferCount es 0
ERROR_INVALID_USER_BUFFER	Se especifica un búfer, pero el tamaño del recuento de búferes es menor que el necesario, en bytes.
ERROR_BAD_COMMAND	Los datos actuales de la memoria caché parecen ser incoherentes y conducen a errores internos.
ERROR_NO_SYSTEM_RESOURCES	La operación se quedó sin memoria.

Comentarios

Las características devueltas se almacenan en caché después de recuperar correctamente las características del dispositivo directamente. A menos que se reciba un evento de cambio de servicio, no se espera que cambie la lista de características devueltas.

Los controladores de perfil deben asignar previamente un búfer suficientemente grande para que se devuelva la matriz de características. Los autores de llamadas pueden determinar el tamaño de búfer necesario pasando un valor distinto de NULL en CharacteristicsBufferActual y NULL en CharacteristicsBuffer.

No modifique la estructura de características devuelta y, a continuación, use la estructura modificada en las llamadas de función posteriores. El comportamiento no está definido si el autor de la llamada lo hace.

El servicio primario debe estar presente en la memoria caché; de lo contrario, se producirá un error en la función. El servicio primario debe ser un servicio devuelto por BluetoothGATTGetServices o BluetoothGATTGetIncludedServices.

Ejemplo

////////////////////////////////////////////////////////////////////////////
// Determine Characteristic Buffer Size
////////////////////////////////////////////////////////////////////////////

        hr = BluetoothGATTGetCharacteristics(
                hCurrService,
                currGattService,
                0,
                NULL,
                &charBufferSize,
                BLUETOOTH_GATT_FLAG_NONE);
        
        if (HRESULT_FROM_WIN32(ERROR_MORE_DATA) != hr) {
            PrintHr("BluetoothGATTGetCharacteristics - Buffer Size", hr);
            goto Done;
        }
        
        if (charBufferSize > 0) {
            pCharBuffer = (PBTH_LE_GATT_CHARACTERISTIC)
                    malloc(charBufferSize * sizeof(BTH_LE_GATT_CHARACTERISTIC));
        
            if (NULL == pCharBuffer) {
                printf("pCharBuffer out of memory\r\n");
                goto Done;
            } else {
                RtlZeroMemory(pCharBuffer, 
                        charBufferSize * sizeof(BTH_LE_GATT_CHARACTERISTIC));
            }

////////////////////////////////////////////////////////////////////////////
// Retrieve Characteristics
////////////////////////////////////////////////////////////////////////////
    
            hr = BluetoothGATTGetCharacteristics(
                    hCurrService,
                    currGattService,
                    charBufferSize,
                    pCharBuffer,
                    &numChars,
                    BLUETOOTH_GATT_FLAG_NONE);

            if (S_OK != hr) {
                PrintHr("BluetoothGATTGetCharacteristics - Actual Data", hr);
                goto Done; // Allow continuation
            }

            if (numChars != charBufferSize) {
                printf("buffer size and buffer size actual size mismatch\r\n");
                goto Done;
            }
        }

Requisitos

Requisito	Value
Cliente mínimo compatible	Compatible con Windows 8 y versiones posteriores de Windows.
Plataforma de destino	Universal
Encabezado	bluetoothleapis.h
Library	BluetoothApis.lib
Archivo DLL	BluetoothApis.dll

Consulte también

BTH_LE_GATT_CHARACTERISTIC

BTH_LE_GATT_SERVICE