BluetoothGATTGetDescriptorValue 함수(bluetoothleapis.h)

아티클
03/14/2023

BluetoothGATTGetDescriptorValue 함수는 지정된 설명자의 값을 가져옵니다.

구문

HRESULT BluetoothGATTGetDescriptorValue(
  [in]            HANDLE                        hDevice,
  [in]            PBTH_LE_GATT_DESCRIPTOR       Descriptor,
  [in]            ULONG                         DescriptorValueDataSize,
  [out, optional] PBTH_LE_GATT_DESCRIPTOR_VALUE DescriptorValue,
  [out, optional] USHORT                        *DescriptorValueSizeRequired,
  [in]            ULONG                         Flags
);

매개 변수

[in] hDevice

서비스에 대한 핸들입니다.

[in] Descriptor

검색할 설명자 값의 부모 설명자를 포함하는 BTH_LE_GATT_DESCRIPTOR 구조체에 대한 포인터입니다.

[in] DescriptorValueDataSize

DescriptorValue 매개 변수에 할당된 바이트 수입니다.

[out, optional] DescriptorValue

설명자 값을 반환할 BTH_LE_GATT_DESCRIPTOR_VALUE 구조체에 대한 포인터입니다.

[out, optional] DescriptorValueSizeRequired

DescriptorValue가 가리키는 버퍼에 데이터를 반환하는 데 필요한 추가 바이트 수를 저장할 버퍼에 대한 포인터입니다.

[in] Flags

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

플래그	설명
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	설명자 값은 캐시에 있는지 여부에 관계없이 캐시에서 읽어야 합니다.

반환 값

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

반환 코드	Description
S_OK	작업이 성공적으로 완료되었습니다.
ERROR_MORE_DATA	버퍼 매개 변수가 NULL 이고 사용 가능한 항목 수가 대신 반환됩니다.
ERROR_ACCESS_DENIED	부모 서비스와 서비스 핸들이 모두 제공되고 서비스 계층이 제공된 부모 서비스 핸들로 롤업되지 않는 경우 반환됩니다.
ERROR_INVALID_PARAMETER	DescriptorValue 및 DescriptorValueSizeRequired는 모두 0입니다.
ERROR_INVALID_USER_BUFFER	버퍼가 지정되었지만 버퍼 수 크기는 필요한 크기(바이트)보다 작습니다.
ERROR_INVALID_FUNCTION	설명자 값이 캐시에서 검색되도록 지정되었지만 설명자 값은 캐시에 없습니다.
ERROR_BAD_COMMAND	캐시의 현재 데이터가 일치하지 않는 것으로 나타나 내부 오류가 발생합니다.
ERROR_BAD_NET_RESP	대상 서버가 적절한 네트워크 응답을 제공하지 않았습니다.
ERROR_SEM_TIMEOUT	요청 시간이 초과되었습니다.
ERROR_NO_SYSTEM_RESOURCES	작업에 메모리가 부족합니다.
E_BLUETOOTH_ATT_INVALID_HANDLE	지정된 특성 핸들이 이 서버에서 유효하지 않습니다.
E_BLUETOOTH_ATT_READ_NOT_PERMITTED	특성을 읽을 수 없습니다.
E_BLUETOOTH_ATT_WRITE_NOT_PERMITTED	특성을 쓸 수 없습니다.
E_BLUETOOTH_ATT_INVALID_PDU	특성 PDU가 잘못되었습니다.
E_BLUETOOTH_ATT_INSUFFICIENT_AUTHENTICATION	특성을 읽거나 쓰려면 인증이 필요합니다.
E_BLUETOOTH_ATT_REQUEST_NOT_SUPPORTED	특성 서버는 클라이언트에서 받은 요청을 지원하지 않습니다.
E_BLUETOOTH_ATT_INVALID_OFFSET	지정된 오프셋이 특성의 끝을 지났습니다.
E_BLUETOOTH_ATT_INSUFFICIENT_AUTHORIZATION	특성을 읽거나 쓰려면 권한 부여가 필요합니다.
E_BLUETOOTH_ATT_PREPARE_QUEUE_FULL	너무 많은 준비 쓰기가 큐에 대기되었습니다.
E_BLUETOOTH_ATT_ATTRIBUTE_NOT_FOUND	지정된 특성 핸들 범위 내에서 특성을 찾을 수 없습니다.
E_BLUETOOTH_ATT_ATTRIBUTE_NOT_LONG	읽기 Blob 요청을 사용하여 특성을 읽거나 쓸 수 없습니다.
E_BLUETOOTH_ATT_INSUFFICIENT_ENCRYPTION_KEY_SIZE	이 링크를 암호화하는 데 사용되는 암호화 키 크기가 충분하지 않습니다.
E_BLUETOOTH_ATT_INVALID_ATTRIBUTE_VALUE_LENGTH	작업에 특성 값 길이가 잘못되었습니다.
E_BLUETOOTH_ATT_UNLIKELY	요청된 특성 요청에는 가능성이 낮아서 요청된 대로 완료할 수 없는 오류가 발생했습니다.
E_BLUETOOTH_ATT_INSUFFICIENT_ENCRYPTION	특성을 읽거나 쓰려면 암호화가 필요합니다.
E_BLUETOOTH_ATT_UNSUPPORTED_GROUP_TYPE	특성 유형은 더 높은 계층 사양에 정의된 대로 지원되는 그룹화 특성이 아닙니다.
E_BLUETOOTH_ATT_INSUFFICIENT_RESOURCES	요청을 완료할 리소스가 부족합니다.
E_BLUETOOTH_ATT_UNKNOWN_ERROR	예약된 범위에 있는 오류가 수신되었습니다.

설명

설명자 값이 이미 있는 경우 캐시에서 반환됩니다. 모든 디바이스 특성이 페어링 또는 연결 시 캐시되기 때문에 대부분의 경우입니다. 그러나 설명자 값이 없으면 설명자 값이 디바이스에서 직접 읽혀지고 디바이스에서 성공적으로 읽을 때 캐시됩니다. BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_CACHE 또는 BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_DEVICE 있는 경우 설명자 값은 지정된 메서드를 사용하여 읽습니다.

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

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

부모 서비스는 캐시에 있어야 합니다. 그렇지 않으면 함수가 실패합니다. 부모 서비스는 BluetoothGATTGetServices 또는 BluetoothGATTGetIncludedServices에서 반환되는 서비스여야 합니다.

예제


////////////////////////////////////////////////////////////////////////////
// Determine Descriptor Value Buffer Size
////////////////////////////////////////////////////////////////////////////
                hr = BluetoothGATTGetDescriptorValue(
                        hCurrService,
                        currGattDescriptor,
                        0,
                        NULL,
                        &descValueDataSize,
                        BLUETOOTH_GATT_FLAG_NONE);

                if (HRESULT_FROM_WIN32(ERROR_MORE_DATA) != hr) {
                    PrintHr("BluetoothGATTGetDescriptorValue - Buffer Size", hr);
                    goto Done; // allow continuation
                }

                pDescValueBuffer = (PBTH_LE_GATT_DESCRIPTOR_VALUE)malloc(descValueDataSize);

                if (NULL == pDescValueBuffer) {
                    printf("pDescValueBuffer out of memory\r\n");
                    goto Done;
                } else {
                    RtlZeroMemory(pDescValueBuffer, descValueDataSize);
                }

////////////////////////////////////////////////////////////////////////////
// Retrieve the Descriptor Value
////////////////////////////////////////////////////////////////////////////

                hr = BluetoothGATTGetDescriptorValue(
                        hCurrService,
                        currGattDescriptor,
                        (ULONG)descValueDataSize,
                        pDescValueBuffer,
                        NULL,
                        BLUETOOTH_GATT_FLAG_NONE);

                if (S_OK != hr) {
                    PrintHr("BluetoothGATTGetDescriptorValue - Actual Data", hr);
                    goto Done; // allow continuation
                }

요구 사항

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

추가 정보

BTH_LE_GATT_DESCRIPTOR

BTH_LE_GATT_DESCRIPTOR_VALUE

다음을 통해 공유

BluetoothGATTGetDescriptorValue 함수(bluetoothleapis.h)

구문

매개 변수

반환 값

설명

요구 사항

추가 정보

피드백

추가 리소스