BluetoothGATTGetCharacteristics 함수(bluetoothleapis.h)
BluetoothGATTGetCharacteristics 함수는 지정된 서비스에 사용할 수 있는 모든 특성을 가져옵니다.
구문
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
);
매개 변수
[in] hDevice
Bluetooth 디바이스 또는 서비스에 대한 핸들입니다.
[in, optional] Service
검색할 포함된 서비스의 부모 서비스를 포함하는 BTH_LE_GATT_SERVICE 구조체의 주소입니다. 이 매개 변수는 디바이스 핸들이 hDevice에 전달되는 경우에 필요합니다. 서비스 핸들이 hDevice에 전달된 경우 이 매개 변수는 선택 사항이며, 이 경우 서비스 핸들에서 지정한 서비스가 부모로 처리됩니다.
[in] CharacteristicsBufferCount
CharacteristicsBuffer 매개 변수에 할당된 요소 수입니다.
[out, optional] CharacteristicsBuffer
특성을 BTH_LE_GATT_CHARACTERISTIC 구조체의 배열로 반환할 버퍼에 대한 포인터입니다.
[out] CharacteristicsBufferActual
이 반환되는 버퍼에 대한 포인터는 CharacteristicsBuffer 매개 변수에 반환된 실제 특성 수를 반환합니다.
[in] Flags
BluetoothGATTGetCharacteristics의 동작을 수정하는 플래그:
| 플래그 | 설명 |
|---|---|
| BLUETOOTH_GATT_FLAG_NONE | 클라이언트에 특정 GATT 요구 사항(기본값)이 없습니다. |
반환 값
이 함수는 다음 값을 반환합니다.
| 반환 코드 | Description |
|---|---|
|
작업이 성공적으로 완료되었습니다. |
|
버퍼 매개 변수가 NULL 이고 사용 가능한 항목 수가 대신 반환됩니다. |
|
부모 서비스와 서비스 핸들이 모두 제공되고 서비스 계층이 제공된 부모 서비스 핸들로 롤업되지 않는 경우 반환됩니다. |
|
다음 조건 중 하나가 발생했습니다.
|
|
버퍼가 지정되었지만 버퍼 수 크기는 필요한 크기(바이트)보다 작습니다. |
|
캐시의 현재 데이터가 일치하지 않는 것으로 나타나 내부 오류가 발생합니다. |
|
작업에 메모리가 부족합니다. |
설명
반환된 특성은 디바이스에서 특성을 직접 성공적으로 검색하면 캐시됩니다. 서비스 변경 이벤트가 수신되지 않는 한 반환된 특성 목록은 변경되지 않을 것으로 예상됩니다.
프로필 드라이버는 반환할 특성 배열에 대해 충분히 큰 버퍼를 미리 할당해야 합니다. 호출자는 CharacteristicsBufferActual 및 CharacteristicsBuffer에서 NULL이 아닌 값을 전달하여 필요한 버 퍼 크기를 확인할 수 있습니다.
반환된 특성 구조를 수정하지 말고 후속 함수 호출에서 수정된 구조를 사용합니다. 호출자가 이 작업을 수행하는 경우 동작이 정의되지 않습니다.
부모 서비스는 캐시에 있어야 합니다. 그렇지 않으면 함수가 실패합니다. 부모 서비스는 BluetoothGATTGetServices 또는 BluetoothGATTGetIncludedServices에서 반환되는 서비스여야 합니다.
예제
////////////////////////////////////////////////////////////////////////////
// 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;
}
}
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows 8 이상 버전의 Windows에서 지원됩니다. |
| 대상 플랫폼 | 유니버설 |
| 헤더 | bluetoothleapis.h |
| 라이브러리 | BluetoothApis.lib |
| DLL | BluetoothApis.dll |