From patchwork Thu Sep 10 23:15:56 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Miao-chen Chou X-Patchwork-Id: 11769555 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id EE72759D for ; Thu, 10 Sep 2020 23:18:05 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id D3F81208CA for ; Thu, 10 Sep 2020 23:18:05 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (1024-bit key) header.d=chromium.org header.i=@chromium.org header.b="hMfupg7q" Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1725562AbgIJXSF (ORCPT ); Thu, 10 Sep 2020 19:18:05 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:54032 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1725283AbgIJXSD (ORCPT ); Thu, 10 Sep 2020 19:18:03 -0400 Received: from mail-pf1-x431.google.com (mail-pf1-x431.google.com [IPv6:2607:f8b0:4864:20::431]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id C1E80C061573 for ; Thu, 10 Sep 2020 16:18:02 -0700 (PDT) Received: by mail-pf1-x431.google.com with SMTP id x123so5742514pfc.7 for ; Thu, 10 Sep 2020 16:18:02 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=chromium.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=OwcQPbWK9wBBKShQmm51i7xxWQDNt4zUBesrzpNnDCQ=; b=hMfupg7qDjfXkmunwm5bLnNs2RQTsaUyZvoSbHGXPuxnBNRo/kk0+rg99gBhYFwyWj RWXbUha50lxLrosBzNOCmDQ3BGKmA6p2ULd91LqOIcwAcfsGHXlupM1FFchpbydsEV+P n3JDyxrOpnSMb3ENcIXnBESDAmqwZ0leVxCRU= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=OwcQPbWK9wBBKShQmm51i7xxWQDNt4zUBesrzpNnDCQ=; b=fnlAUd4Cpzd7mZoz8Y1x+OQe7XUqOhQ6mgXVPhx9eSwoXULMJDEhXuBO01nz8Q7dFt 5TeCapf70BK43L5NnBuX2uAHYhyytOhTUkxDmZJJTHBkRwZySLXlQ8NlUihhP6pYinPW D0NAtui99IfJwKivO1C0MSo4cAbZgWVCuWCmaerVYQlGEoaiIici/LgQM5/f3ISxfmiT 2ANDhGwSsU9AxPtzgsVkyvGa50kwfz97yi4sBM/cwCyejZMvLFhWXWoLWGnF1k/Jzwbl uPMofel0/F+oLsOwICXDS0s8EwXa6UfAB9J5+JSZlFbvTsiM5Wqy1KW90D3qcx3psB/A uD9w== X-Gm-Message-State: AOAM532SP5J7ei3/l4rot63cVTDU+GGFMgy801KfafGhivfMpSrsMqON iiSmar2zOHwaYePVxzwGwRiDg46IC+9f3g== X-Google-Smtp-Source: ABdhPJzGs/I3r7GTdRO38SVjmTT3AOSidBJHUP78dslrtp29w5XT6CsYYYX708Dv8rRt7kdM9sv58w== X-Received: by 2002:a17:902:a40e:: with SMTP id p14mr7526567plq.4.1599779881464; Thu, 10 Sep 2020 16:18:01 -0700 (PDT) Received: from mcchou0.mtv.corp.google.com ([2620:15c:202:201:de4a:3eff:fe75:1314]) by smtp.gmail.com with ESMTPSA id k29sm76790pgf.21.2020.09.10.16.18.00 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 10 Sep 2020 16:18:00 -0700 (PDT) From: Miao-chen Chou To: Bluetooth Kernel Mailing List Cc: Alain Michaud , Luiz Augusto von Dentz , Manish Mandlik , Howard Chung , Miao-chen Chou Subject: [BlueZ PATCH v4 8/8] doc: Update Advertisement Monitor API description Date: Thu, 10 Sep 2020 16:15:56 -0700 Message-Id: <20200910161528.BlueZ.v4.8.Iee7e9d13c78dd02c5b283a203dea11a4a4ffa7cc@changeid> X-Mailer: git-send-email 2.26.2 In-Reply-To: <20200910161528.BlueZ.v4.1.Iaa9dc2a66de5fbfa97627e1dbeb800116d3aa91e@changeid> References: <20200910161528.BlueZ.v4.1.Iaa9dc2a66de5fbfa97627e1dbeb800116d3aa91e@changeid> MIME-Version: 1.0 Sender: linux-bluetooth-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-bluetooth@vger.kernel.org This modifies the following description to Advertisement Monitor API. - Add org.bluez.Error.Failed to RegisterMonitor() method. - Add more description about the usage of RegisterMonitor() and UnregisterMonitor() methods. - Add description about the ranges for the fields in property RSSIThresholdsAndTimers. Reviewed-by: Yun-Hao Chung Reviewed-by: Manish Mandlik --- (no changes since v1) doc/advertisement-monitor-api.txt | 34 +++++++++++++++++++++++-------- 1 file changed, 25 insertions(+), 9 deletions(-) diff --git a/doc/advertisement-monitor-api.txt b/doc/advertisement-monitor-api.txt index 74adbfae9..e09b6fd25 100644 --- a/doc/advertisement-monitor-api.txt +++ b/doc/advertisement-monitor-api.txt @@ -49,7 +49,7 @@ Properties string Type [read-only] org.bluez.AdvertisementMonitorManager1 for the available options. - (Int16, Uint16, Int16, Uint16) RSSIThreshholdsAndTimers [read-only, optional] + (Int16, Uint16, Int16, Uint16) RSSIThresholdsAndTimers [read-only, optional] This contains HighRSSIThreshold, HighRSSIThresholdTimer, LowRSSIThreshold, LowRSSIThresholdTimer in order. The @@ -66,7 +66,11 @@ Properties string Type [read-only] RSSIs of the received advertisement(s) during LowRSSIThresholdTimer do not reach LowRSSIThreshold. - array{(uint8, uint8, string)} Patterns [read-only, optional] + The valid range of a RSSI is -127 to +20 dBm while 127 + dBm indicates unset. The valid range of a timer is 1 to + 300 seconds while 0 indicates unset. + + array{(uint8, uint8, array{byte})} Patterns [read-only, optional] If Type is set to 0x01, this must exist and has at least one entry in the array. @@ -80,8 +84,9 @@ Properties string Type [read-only] See https://www.bluetooth.com/specifications/ assigned-numbers/generic-access-profile/ for the possible allowed value. - string content_of_pattern - This is the value of the pattern. + array{byte} content_of_pattern + This is the value of the pattern. The maximum + length of the bytes is 31. Advertisement Monitor Manager hierarchy ======================================= @@ -91,20 +96,31 @@ Object path /org/bluez/{hci0,hci1,...} Methods void RegisterMonitor(object application) - This registers a hierarchy of advertisement monitors. + This registers the root path of a hierarchy of + advertisement monitors. The application object path together with the D-Bus system bus connection ID define the identification of the application registering advertisement monitors. + Once a root path is registered by a client via this + method, the client can freely expose/unexpose + advertisement monitors without re-registering the root + path again. After use, the client should call + UnregisterMonitor() method to invalidate the + advertisement monitors. Possible errors: org.bluez.Error.InvalidArguments org.bluez.Error.AlreadyExists + org.bluez.Error.Failed void UnregisterMonitor(object application) - This unregisters advertisement monitors that have been - previously registered. The object path parameter must - match the same value that has been used on - registration. + This unregisters a hierarchy of advertisement monitors + that has been previously registered. The object path + parameter must match the same value that has been used + on registration. Upon unregistration, the advertisement + monitor(s) should expect to receive Release() method as + the signal that the advertisement monitor(s) has been + deactivated. Possible errors: org.bluez.Error.InvalidArguments org.bluez.Error.DoesNotExist