Función BluetoothGATTGetServices (bluetoothleapis.h)

La función BluetoothGATTGetServices obtiene todos los servicios principales disponibles para un servidor.

Sintaxis

HRESULT BluetoothGATTGetServices(
  [in]            HANDLE               hDevice,
  [in]            USHORT               ServicesBufferCount,
  [out, optional] PBTH_LE_GATT_SERVICE ServicesBuffer,
  [out]           USHORT               *ServicesBufferActual,
  [in]            ULONG                Flags
);

Parámetros

[in] hDevice

Controla el dispositivo Bluetooth desde el que obtener la lista de servicios principales.

[in] ServicesBufferCount

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

[out, optional] ServicesBuffer

Puntero al búfer que contiene una estructura BTH_LE_GATT_SERVICE en la que se van a devolver servicios.

[out] ServicesBufferActual

Puntero al búfer en el que se devolvió el número real de servicios en el parámetro ServicesBuffer .

[in] Flags

Marcas para modificar el comportamiento de BluetoothGATTGetServices:

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

Valor devuelto

Esta función devuelve los siguientes valores:

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 condiciones siguientes: ServicesBuffer es NULL y ServicesBufferCount es 0 ServicesBuffer no es NULL, pero ServicesBufferCount es NULL ServicesBuffer no es NULL y ServicesBufferCount 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_INVALID_FUNCTION	Se especificó que los servicios se recuperaran de la memoria caché, pero no hay servicios presentes en la memoria caché.
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

Los servicios devueltos se almacenan en caché tras la recuperación correcta de los servicios desde el dispositivo directamente. A menos que se reciba un evento de cambio de servicio, no se espera que cambie la lista de servicios devueltos.

Los controladores de perfil deben asignar previamente un búfer suficientemente grande para que se devuelva la matriz de servicios principales. Los autores de llamadas pueden determinar el tamaño de búfer necesario pasando un valor distinto de NULL en ServicesBufferActual y NULL en ServicesBuffer.

No modifique la estructura de servicio 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.

Ejemplo

////////////////////////////////////////////////////////////////////////////
// Determine Services Buffer Size
////////////////////////////////////////////////////////////////////////////

    hr = BluetoothGATTGetServices(
            hLEDevice,
            0,
            NULL,
            &serviceBufferCount,
            BLUETOOTH_GATT_FLAG_NONE);
    
    if (HRESULT_FROM_WIN32(ERROR_MORE_DATA) != hr) {
        PrintHr("BluetoothGATTGetServices - Buffer Size", hr);
        goto Done;
    }

    pServiceBuffer = (PBTH_LE_GATT_SERVICE)
            malloc(sizeof(BTH_LE_GATT_SERVICE) * serviceBufferCount);
    
    if (NULL == pServiceBuffer) {
        printf("pServiceBuffer out of memory\r\n");
        goto Done;
    } else {
        RtlZeroMemory(pServiceBuffer, 
                sizeof(BTH_LE_GATT_SERVICE) * serviceBufferCount);
    }
    
////////////////////////////////////////////////////////////////////////////
// Retrieve Services
////////////////////////////////////////////////////////////////////////////
    
    hr = BluetoothGATTGetServices(
            hLEDevice,
            serviceBufferCount,
            pServiceBuffer,
            &numServices,
            BLUETOOTH_GATT_FLAG_NONE);
    
    if (S_OK != hr) {
        PrintHr("BluetoothGATTGetServices - Actual Data", hr);
        goto Done;
    }

Requisitos

Requisito	Value
Cliente mínimo compatible	Se admite en 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_SERVICE