다음을 통해 공유

BluetoothGATTGetIncludedServices 함수(bluetoothleapis.h)

  • 아티클

BluetoothGATTGetIncludedServices 함수는 지정된 서비스에 사용할 수 있는 모든 포함된 서비스를 가져옵니다.

구문

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

매개 변수

[in] hDevice

Bluetooth 디바이스 또는 부모 서비스에 대한 핸들입니다.

[in, optional] ParentService

검색할 포함된 서비스의 부모 서비스를 포함하는 BTH_LE_GATT_SERVICE 구조체의 주소입니다. 디바이스 핸들이 hDevice에 전달되는 경우 이 매개 변수가 필요합니다. 서비스 핸들이 hDevice에 전달된 경우 이 매개 변수는 선택 사항이며, 이 경우 서비스 핸들에 지정된 서비스가 부모로 처리됩니다.

[in] IncludedServicesBufferCount

IncludedServicesBuffer 매개 변수에 할당된 요소 수입니다.

[out, optional] IncludedServicesBuffer

포함된 서비스를 반환할 BTH_LE_GATT_SERVICE 구조를 포함하는 버퍼의 주소입니다.

[out] IncludedServicesBufferActual

포함된 서비스의 실제 수가 IncludedServicesBuffer 매개 변수에 반환된 버퍼에 대한 포인터입니다.

[in] Flags

BluetoothGATTGetIncludedServices의 동작을 수정하는 플래그:

플래그 설명
BLUETOOTH_GATT_FLAG_NONE 클라이언트에 특정 GATT 요구 사항(기본값)이 없습니다.

반환 값

이 함수는 다음 값을 반환합니다.

반환 코드 Description
S_OK
 작업이 성공적으로 완료되었습니다.
ERROR_MORE_DATA
 버퍼 매개 변수가 NULL 이고 사용 가능한 항목 수가 대신 반환됩니다.
ERROR_ACCESS_DENIED
 부모 서비스와 서비스 핸들이 모두 제공되고 서비스 계층이 제공된 부모 서비스 핸들로 롤업되지 않는 경우 반환됩니다.
ERROR_INVALID_PARAMETER
 다음 조건 중 하나가 발생했습니다.
  • IncludedServicesBuffer 는 NULL이고 IncludedServicesBufferCount 는 0입니다.
  • IncludedServicesBuffer 는 NULL이 아니지만 IncludedServicesBufferCount 는 NULL입니다.
  • IncludedServicesBuffer 는 NULL이 아니고 IncludedServicesBufferCount 는 0입니다.
ERROR_INVALID_USER_BUFFER
 버퍼가 지정되었지만 버퍼 수 크기는 필요한 크기(바이트)보다 작습니다.
ERROR_INVALID_FUNCTION
 서비스는 캐시에서 검색되도록 지정되었지만 캐시에는 서비스가 없습니다.
ERROR_BAD_COMMAND
 캐시의 현재 데이터가 일치하지 않는 것으로 나타나 내부 오류가 발생합니다.
ERROR_NO_SYSTEM_RESOURCES
 작업에 메모리가 부족합니다.

설명

반환된 서비스는 디바이스에서 서비스를 성공적으로 검색하면 직접 캐시됩니다. 서비스 변경 이벤트가 수신되지 않는 한 반환된 서비스 목록은 변경되지 않습니다.

프로필 드라이버는 반환할 기본 서비스 배열에 대해 충분히 큰 버퍼를 미리 할당해야 합니다. 호출자는 IncludedServicesBuffer에서 NULL이 아닌 값을 전달하고 IncludedServicesBuffer에서 NULL을 전달하여 필요한 버퍼 크기를 확인할 수 있습니다.

반환된 서비스 구조를 수정하지 말고 후속 함수 호출에서 수정된 구조를 사용합니다. 호출자가 이 작업을 수행하는 경우 동작이 정의되지 않습니다.

예제


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

요구 사항

요구 사항 값
지원되는 최소 클라이언트 Windows 8 이상 버전의 Windows에서 지원됩니다.
대상 플랫폼 유니버설
헤더 bluetoothleapis.h
라이브러리 BluetoothApis.lib
DLL BluetoothAPIs.dll

추가 정보

BTH_LE_GATT_SERVICE