BluetoothGATTGetCharacteristicValue 함수(bluetoothleapis.h)
BluetoothGATTGetCharacteristicValue 함수는 지정된 특성의 값을 가져옵니다.
구문
HRESULT BluetoothGATTGetCharacteristicValue(
[in] HANDLE hDevice,
[in] PBTH_LE_GATT_CHARACTERISTIC Characteristic,
[in] ULONG CharacteristicValueDataSize,
[out, optional] PBTH_LE_GATT_CHARACTERISTIC_VALUE CharacteristicValue,
[out, optional] USHORT *CharacteristicValueSizeRequired,
[in] ULONG Flags
);
매개 변수
[in] hDevice
서비스에 대한 핸들입니다.
[in] Characteristic
검색할 특성 값의 부모 특성에 대한 포인터입니다.
[in] CharacteristicValueDataSize
CharacteristicValue 매개 변수에 할당된 바이트 수입니다.
[out, optional] CharacteristicValue
특성 값을 반환할 버퍼에 대한 포인터입니다.
[out, optional] CharacteristicValueSizeRequired
CharacteristicValue가 가리키는 버퍼에 데이터를 반환하는 데 필요한 바이트 수를 저장할 버퍼에 대한 포인터입니다.
[in] Flags
BluetoothGATTGetCharacteristicValue의 동작을 수정하는 플래그:
| 플래그 | 설명 |
|---|---|
| BLUETOOTH_GATT_FLAG_NONE | 클라이언트에 특정 GATT 요구 사항(기본값)이 없습니다. |
| BLUETOOTH_GATT_FLAG_CONNECTION_ENCRYPTED | 클라이언트는 암호화된 채널을 통해 데이터를 전송하도록 요청합니다. |
| BLUETOOTH_GATT_FLAG_CONNECTION_AUTHENTICATED | 클라이언트는 인증된 채널을 통해 데이터를 전송하도록 요청합니다. |
| BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_DEVICE | 특성 값은 디바이스에서 직접 읽는 것입니다. 이미 있는 경우 캐시에 있는 덮어씁니다. |
| BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_CACHE | 특성 값은 캐시에 있는지 여부에 관계없이 캐시에서 읽어야 합니다. |
반환 값
BluetoothGATTGetCharacteristicValue 함수는 다음 값을 반환합니다.
| 반환 코드 | Description |
|---|---|
|
작업이 성공적으로 완료되었습니다. |
|
버퍼 매개 변수가 NULL이고 사용 가능한 항목 수가 대신 반환됩니다. |
|
부모 서비스와 서비스 핸들이 모두 제공되고 서비스 계층이 제공된 부모 서비스 핸들로 롤업되지 않는 경우 반환됩니다. |
|
CharacteristicValue 및 CharacteristicValueSizeRequired는 모두 0입니다. |
|
버퍼가 지정되었지만 버퍼 수 크기는 필요한 크기(바이트)보다 작습니다. |
|
캐시의 현재 데이터가 일치하지 않는 것으로 나타나 내부 오류가 발생합니다. |
|
대상 서버가 적절한 네트워크 응답을 제공하지 않았습니다. |
|
요청 시간이 초과되었습니다. |
|
특성 값은 특성 속성에 의해 지시된 대로 읽을 수 없습니다. |
|
작업에 메모리가 부족합니다. |
|
지정된 특성 핸들이 이 서버에서 잘못되었습니다. |
|
특성을 읽을 수 없습니다. |
|
특성을 쓸 수 없습니다. |
|
특성 PDU가 잘못되었습니다. |
|
특성을 읽거나 쓰려면 인증이 필요합니다. |
|
특성 서버는 클라이언트에서 받은 요청을 지원하지 않습니다. |
|
지정된 오프셋이 특성의 끝을 지났습니다. |
|
특성을 읽거나 쓰려면 권한 부여가 필요합니다. |
|
너무 많은 준비 쓰기가 큐에 대기되었습니다. |
|
지정된 특성 핸들 범위 내에서 특성을 찾을 수 없습니다. |
|
읽기 Blob 요청을 사용하여 특성을 읽거나 쓸 수 없습니다. |
|
이 링크를 암호화하는 데 사용되는 암호화 키 크기가 부족합니다. |
|
작업에 특성 값 길이가 잘못되었습니다. |
|
요청된 특성 요청에는 가능성이 낮아서 요청된 대로 완료할 수 없는 오류가 발생했습니다. |
|
특성을 읽거나 쓰려면 암호화가 필요합니다. |
|
특성 유형은 더 높은 계층 사양에 정의된 대로 지원되는 그룹화 특성이 아닙니다. |
|
요청을 완료할 리소스가 부족합니다. |
|
예약된 범위에 있는 오류가 수신되었습니다. |
설명
특성 값이 이미 있는 경우 캐시에서 반환됩니다. 페어링 또는 연결 시 모든 디바이스 특성이 캐시되기 때문에 대부분의 경우입니다. 그러나 특성 값이 없는 경우 특성 값은 디바이스에서 직접 읽고 디바이스에서 성공적으로 읽으면 캐시됩니다. BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_CACHE 또는 BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_DEVICE 있으면 지정된 메서드를 사용하여 특성 값을 읽습니다.
반환된 특성은 디바이스에서 특성을 직접 성공적으로 검색하면 캐시됩니다. 서비스 변경 이벤트가 수신되지 않는 한 반환된 특성 목록은 변경되지 않을 것으로 예상됩니다.
프로필 드라이버는 반환할 특성 배열에 대해 충분히 큰 버퍼를 미리 할당해야 합니다. 호출자는 CharacteristicValueSizeRequired및CharacteristicValue에서 NULL이 아닌 값을 전달하여 필요한 버퍼 크기를 결정할 수 있습니다.
부모 서비스는 캐시에 있어야 합니다. 그렇지 않으면 함수가 실패합니다. 부모 서비스는 BluetoothGATTGetServices 또는 BluetoothGATTGetIncludedServices에서 반환되는 서비스여야 합니다.
예제
if (currGattChar->IsReadable) {
////////////////////////////////////////////////////////////////////////////
// Determine Characteristic Value Buffer Size
////////////////////////////////////////////////////////////////////////////
hr = BluetoothGATTGetCharacteristicValue(
hCurrService,
currGattChar,
0,
NULL,
&charValueDataSize,
BLUETOOTH_GATT_FLAG_NONE);
if (HRESULT_FROM_WIN32(ERROR_MORE_DATA) != hr) {
PrintHr("BluetoothGATTGetCharacteristicValue - Buffer Size", hr);
goto GetDescriptors; // Proceed to retrieving descriptors
}
pCharValueBuffer = (PBTH_LE_GATT_CHARACTERISTIC_VALUE)malloc(charValueDataSize);
if (NULL == pCharValueBuffer) {
printf("pCharValueBuffer out of memory\r\n");
goto Done;
} else {
RtlZeroMemory(pCharValueBuffer, charValueDataSize);
}
////////////////////////////////////////////////////////////////////////////
// Retrieve the Characteristic Value
////////////////////////////////////////////////////////////////////////////
hr = BluetoothGATTGetCharacteristicValue(
hCurrService,
currGattChar,
(ULONG)charValueDataSize,
pCharValueBuffer,
NULL,
BLUETOOTH_GATT_FLAG_NONE);
if (S_OK != hr) {
PrintHr("BluetoothGATTGetCharacteristicValue - Actual Data", hr);
goto GetDescriptors; // Proceed to retrieving descriptors
}
PrintCharacteristicValue(pCharValueBuffer, 2, currGattChar->CharacteristicUuid);
// Free before going to next iteration, or memory leak.
free(pCharValueBuffer);
pCharValueBuffer = NULL;
}
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows 8 이상 버전의 Windows에서 지원됩니다. |
| 대상 플랫폼 | 유니버설 |
| 헤더 | bluetoothleapis.h |
| 라이브러리 | BluetoothAPIs.lib |
| DLL | BluetoothAPIs.dll |