Función BluetoothGATTGetIncludedServices (bluetoothleapis.h)

La función BluetoothGATTGetIncludedServices obtiene todos los servicios incluidos disponibles para un servicio determinado.

Sintaxis

HRESULT BluetoothGATTGetIncludedServices(
  [in]            HANDLE               hDevice,
  [in, optional]  PBTH_LE_GATT_SERVICE ParentService,
  [in]            USHORT               IncludedServicesBufferCount,
  [out, optional] PBTH_LE_GATT_SERVICE IncludedServicesBuffer,
  [out]           USHORT               *IncludedServicesBufferActual,
  [in]            ULONG                Flags
);

Parámetros

[in] hDevice

Controla el dispositivo Bluetooth o el servicio primario.

[in, optional] ParentService

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 elemento primario.

[in] IncludedServicesBufferCount

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

[out, optional] IncludedServicesBuffer

Dirección de un búfer que contiene una estructura de BTH_LE_GATT_SERVICE en la que se van a devolver los servicios incluidos.

[out] IncludedServicesBufferActual

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

[in] Flags

Marcas para modificar el comportamiento de BluetoothGATTGetIncludedServices:

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: IncludedServicesBuffer es NULL y IncludedServicesBufferCount es 0. IncludedServicesBuffer no es NULL, pero IncludedServicesBufferCount es NULL. IncludedServicesBuffer no es NULL y IncludedServicesBufferCount 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 IncludedServicesBufferActual y NULL en IncludedServicesBuffer.

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 Included Services Buffer Size
////////////////////////////////////////////////////////////////////////////
hr = BluetoothGATTGetIncludedServices(
     hLEDevice,
     gattService,
     0,
     NULL,
     &inclServicesBufferSize,
     BLUETOOTH_GATT_FLAG_NONE);

     if (HRESULT_FROM_WIN32(ERROR_MORE_DATA) != hr) {
         PrintHr("BluetoothGATTGetIncludedServices - Buffer Size", hr);
         goto Done;
     }

     if (inclServicesBufferSize > 0) {
         pInclServicesBuffer = (PBTH_LE_GATT_ PBTH_LE_GATT_SERVICE)
                    malloc(inclServicesBufferSize * sizeof(BTH_LE_GATT_SERVICE));

         if (NULL == pInclServicesBuffer) {
             printf("pInclServicesBuffer out of memory\r\n");
             goto Done;
         } else {
             RtlZeroMemory(pInclServicesBuffer, 
                    inclServicesBufferSize * sizeof(BTH_LE_GATT_SERVICE));
         }

         ////////////////////////////////////////////////////////////////////////////
         // Retrieve Included Services
         ////////////////////////////////////////////////////////////////////////////

         hr = BluetoothGATTGetIncludedServices (
              hLEDevice,
              gattService,
              inclServicesBufferSize,
              pInclServicesBuffer,
              &numIncludedServices
              BLUETOOTH_GATT_FLAG_NONE);

         if (S_OK != hr) {
             PrintHr("BluetoothGATTGetIncludedServices - 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