From patchwork Mon Oct 9 23:29:23 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luiz Augusto von Dentz X-Patchwork-Id: 13414674 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 3F007E9371F for ; Mon, 9 Oct 2023 23:29:44 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S234612AbjJIX3n (ORCPT ); Mon, 9 Oct 2023 19:29:43 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:55932 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232095AbjJIX3m (ORCPT ); Mon, 9 Oct 2023 19:29:42 -0400 Received: from mail-pl1-x62e.google.com (mail-pl1-x62e.google.com [IPv6:2607:f8b0:4864:20::62e]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 73A16A4 for ; Mon, 9 Oct 2023 16:29:37 -0700 (PDT) Received: by mail-pl1-x62e.google.com with SMTP id d9443c01a7336-1c87a85332bso41980515ad.2 for ; Mon, 09 Oct 2023 16:29:37 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1696894176; x=1697498976; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:message-id:date:subject:to :from:from:to:cc:subject:date:message-id:reply-to; bh=r7RBPLmDzGivlZggMbmZBgWVPFOALRZSlggaK2gzrmQ=; b=D9g5rRSAwFBfFlWeDKXjCSpEjWazuImDaqBlUv0+9Y06FErCi5USVza12YBy660ABg ZHr8eb987JmHyaZrVH9VrM1i3MTJwjnj00dHhiswH8Gc6rPa4xwjUTRWohycSTZy2CE6 EdIRvesGyDJ+JaHX3efZVNJEFDeL5bF3Z/gPB2GgFfN7Xk7W8ayLh9Rz5l5mIWMZ6zKW vdajzKUMejJzvqUvyqE3SD8RVKtzc2rHgV1l56dWCU02wHiURM8ygIsejm4A/Q1XZ6A4 52NRfggGPp6ThvKeFyQuNYPEu5xA6+//4Q9qFNo9hAFcL2qAMx+vxB5sloIzwWXpBKXo wPzQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1696894176; x=1697498976; h=content-transfer-encoding:mime-version:message-id:date:subject:to :from:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=r7RBPLmDzGivlZggMbmZBgWVPFOALRZSlggaK2gzrmQ=; b=PFTrPCuC2LZ8B2yiFisGolgapQSLPFjHpRkiquTwt8ainKeF8t20bv9DXrdheRi6Fh Wi6+OuLa08R7jSf5f15LdqY9+wzPkhL86jQIihrYEV9wZN10GTqgIXD43Z3BUK+3clyv jH1gvYyp/8V3FfYLxIN+C0Qz3U9frENs53VACeiXI5//pEqe0RbSLKCVFu4PXdEwvQnf 1RFslLBzC3DaZGt9jJqJPrY6GFIUKa8+NgKd369Wa4YtTyDYYnEURERt7tgDj9W2N6Nu Fc5bBcJDM1cZvHsiPBwq0YocMuVwZqiSYXJgRvDVsiX3VWID3aDNzVVTzCxnyIUJFdh2 z81w== X-Gm-Message-State: AOJu0YweuZ+XlODz8s2oURd22r84UWisDCjvvGfeHuFams0ggGZiEiQ8 RjMHo7Kj+JhGKAErwunpkSj8/uQKZJd2QSCJ X-Google-Smtp-Source: AGHT+IGYCTVniZ2yV3Gk/ed+zFaRzbdpcP7yhAOavKyQ4SswZ7SqyQCbq2jxf/Hu30hRZY0FRDFaFw== X-Received: by 2002:a17:902:ecd1:b0:1c0:cbaf:6930 with SMTP id a17-20020a170902ecd100b001c0cbaf6930mr18569451plh.54.1696894175581; Mon, 09 Oct 2023 16:29:35 -0700 (PDT) Received: from lvondent-mobl4.. (c-98-232-221-87.hsd1.or.comcast.net. [98.232.221.87]) by smtp.gmail.com with ESMTPSA id s20-20020a170902989400b001c5b8087fe5sm10182711plp.94.2023.10.09.16.29.34 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 09 Oct 2023 16:29:34 -0700 (PDT) From: Luiz Augusto von Dentz To: linux-bluetooth@vger.kernel.org Subject: [PATCH v2 01/11] doc/adapter-api: Rename to org.bluez.Adapter.rst Date: Mon, 9 Oct 2023 16:29:23 -0700 Message-ID: <20231009232933.500652-1-luiz.dentz@gmail.com> X-Mailer: git-send-email 2.41.0 MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-bluetooth@vger.kernel.org From: Luiz Augusto von Dentz This renames adapter-api.txt to org.bluez.Adapter.rst and generate a manpage org.bluez.Adapter.5. --- Makefile.am | 8 +- doc/adapter-api.txt | 373 ---------------------------------- doc/org.bluez.Adapter.rst | 412 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 416 insertions(+), 377 deletions(-) delete mode 100644 doc/adapter-api.txt create mode 100644 doc/org.bluez.Adapter.rst diff --git a/Makefile.am b/Makefile.am index 8d35dbb55e69..5eb94985a1b7 100644 --- a/Makefile.am +++ b/Makefile.am @@ -357,14 +357,14 @@ CLEANFILES += $(builtin_files) src/bluetooth.service if MANPAGES man_MANS += src/bluetoothd.8 -man_MANS += doc/org.bluez.DeviceSet.5 +man_MANS += doc/org.bluez.Adapter.5 doc/org.bluez.DeviceSet.5 man_MANS += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \ doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \ doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \ doc/org.bluez.MediaTransport.5 endif manual_pages += src/bluetoothd.8 -manual_pages += doc/org.bluez.DeviceSet.5 +manual_pages += doc/org.bluez.Adapter.5 doc/org.bluez.DeviceSet.5 manual_pages += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \ doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \ doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \ @@ -405,12 +405,12 @@ EXTRA_DIST += doc/assigned-numbers.txt doc/supported-features.txt \ doc/settings-storage.txt EXTRA_DIST += doc/mgmt-api.txt \ - doc/adapter-api.txt doc/device-api.txt \ + doc/device-api.txt \ doc/agent-api.txt doc/profile-api.txt \ doc/network-api.txt doc/health-api.txt \ doc/sap-api.txt doc/input-api.txt -EXTRA_DIST += doc/org.bluez.DeviceSet.rst +EXTRA_DIST += doc/org.bluez.Adapter.rst doc/org.bluez.DeviceSet.rst EXTRA_DIST += doc/org.bluez.Media.rst doc/org.bluez.MediaControl.rst \ doc/org.bluez.MediaPlayer.rst doc/org.bluez.MediaFolder.rst \ diff --git a/doc/adapter-api.txt b/doc/adapter-api.txt deleted file mode 100644 index 10c290c62fe2..000000000000 --- a/doc/adapter-api.txt +++ /dev/null @@ -1,373 +0,0 @@ -BlueZ D-Bus Adapter API description -*********************************** - - -Adapter hierarchy -================= - -Service org.bluez -Interface org.bluez.Adapter1 -Object path [variable prefix]/{hci0,hci1,...} - -Methods void StartDiscovery() - - This method starts the device discovery session. This - includes an inquiry procedure and remote device name - resolving. Use StopDiscovery to release the sessions - acquired. - - This process will start creating Device objects as - new devices are discovered. - - During discovery RSSI delta-threshold is imposed. - - Each client can request a single device discovery session - per adapter. - - Possible errors: org.bluez.Error.NotReady - org.bluez.Error.Failed - org.bluez.Error.InProgress - - void StopDiscovery() - - This method will cancel any previous StartDiscovery - transaction. - - Note that a discovery procedure is shared between all - discovery sessions thus calling StopDiscovery will only - release a single session and discovery will stop when - all sessions from all clients have finished. - - Possible errors: org.bluez.Error.NotReady - org.bluez.Error.Failed - org.bluez.Error.NotAuthorized - - void RemoveDevice(object device) - - This removes the remote device object at the given - path. It will remove also the pairing information. - - Possible errors: org.bluez.Error.InvalidArguments - org.bluez.Error.Failed - - void SetDiscoveryFilter(dict filter) - - This method sets the device discovery filter for the - caller. When this method is called with no filter - parameter, filter is removed. - - Parameters that may be set in the filter dictionary - include the following: - - array{string} UUIDs - - Filter by service UUIDs, empty means match - _any_ UUID. - - When a remote device is found that advertises - any UUID from UUIDs, it will be reported if: - - Pathloss and RSSI are both empty. - - only Pathloss param is set, device advertise - TX pwer, and computed pathloss is less than - Pathloss param. - - only RSSI param is set, and received RSSI is - higher than RSSI param. - - int16 RSSI - - RSSI threshold value. - - PropertiesChanged signals will be emitted - for already existing Device objects, with - updated RSSI value. If one or more discovery - filters have been set, the RSSI delta-threshold, - that is imposed by StartDiscovery by default, - will not be applied. - - uint16 Pathloss - - Pathloss threshold value. - - PropertiesChanged signals will be emitted - for already existing Device objects, with - updated Pathloss value. - - string Transport (Default "auto") - - Transport parameter determines the type of - scan. - - Possible values: - "auto" - interleaved scan - "bredr" - BR/EDR inquiry - "le" - LE scan only - - If "le" or "bredr" Transport is requested, - and the controller doesn't support it, - org.bluez.Error.Failed error will be returned. - If "auto" transport is requested, scan will use - LE, BREDR, or both, depending on what's - currently enabled on the controller. - - bool DuplicateData (Default: true) - - Disables duplicate detection of advertisement - data. - - When enabled PropertiesChanged signals will be - generated for either ManufacturerData and - ServiceData everytime they are discovered. - - bool Discoverable (Default: false) - - Make adapter discoverable while discovering, - if the adapter is already discoverable setting - this filter won't do anything. - - string Pattern (Default: none) - - Discover devices where the pattern matches - either the prefix of the address or - device name which is convenient way to limited - the number of device objects created during a - discovery. - - When set disregards device discoverable flags. - - Note: The pattern matching is ignored if there - are other client that don't set any pattern as - it work as a logical OR, also setting empty - string "" pattern will match any device found. - - When discovery filter is set, Device objects will be - created as new devices with matching criteria are - discovered regardless of they are connectable or - discoverable which enables listening to - non-connectable and non-discoverable devices. - - When multiple clients call SetDiscoveryFilter, their - filters are internally merged, and notifications about - new devices are sent to all clients. Therefore, each - client must check that device updates actually match - its filter. - - When SetDiscoveryFilter is called multiple times by the - same client, last filter passed will be active for - given client. - - SetDiscoveryFilter can be called before StartDiscovery. - It is useful when client will create first discovery - session, to ensure that proper scan will be started - right after call to StartDiscovery. - - Possible errors: org.bluez.Error.NotReady - org.bluez.Error.NotSupported - org.bluez.Error.Failed - - array{string} GetDiscoveryFilters() - - Return available filters that can be given to - SetDiscoveryFilter. - - Possible errors: None - - object ConnectDevice(dict properties) [experimental] - - This method connects to device without need of - performing General Discovery. Connection mechanism is - similar to Connect method from Device1 interface with - exception that this method returns success when physical - connection is established and you can specify bearer to - connect with parameter. After this method returns, - services discovery will continue and any supported - profile will be connected. There is no need for calling - Connect on Device1 after this call. If connection was - successful this method returns object path to created - device object or device that already exist. - - Parameters that may be set in the filter dictionary - include the following: - - string Address - - The Bluetooth device address of the remote - device. This parameter is mandatory. - - string AddressType - - The Bluetooth device Address Type. This is - address type that should be used for initial - connection. If this parameter is not present - BR/EDR device is created. - - Possible values: - "public" - Public address - "random" - Random address - - Possible errors: org.bluez.Error.InvalidArguments - org.bluez.Error.AlreadyExists - org.bluez.Error.NotSupported - org.bluez.Error.NotReady - org.bluez.Error.Failed - -Properties string Address [readonly] - - The Bluetooth device address. - - string AddressType [readonly] - - The Bluetooth Address Type. For dual-mode and BR/EDR - only adapter this defaults to "public". Single mode LE - adapters may have either value. With privacy enabled - this contains type of Identity Address and not type of - address used for connection. - - Possible values: - "public" - Public address - "random" - Random address - - string Name [readonly] - - The Bluetooth system name (pretty hostname). - - This property is either a static system default - or controlled by an external daemon providing - access to the pretty hostname configuration. - - string Alias [readwrite] - - The Bluetooth friendly name. This value can be - changed. - - In case no alias is set, it will return the system - provided name. Setting an empty string as alias will - convert it back to the system provided name. - - When resetting the alias with an empty string, the - property will default back to system name. - - On a well configured system, this property never - needs to be changed since it defaults to the system - name and provides the pretty hostname. Only if the - local name needs to be different from the pretty - hostname, this property should be used as last - resort. - - uint32 Class [readonly] - - The Bluetooth class of device. - - This property represents the value that is either - automatically configured by DMI/ACPI information - or provided as static configuration. - - boolean Powered [readwrite] - - Switch an adapter on or off. This will also set the - appropriate connectable state of the controller. - - The value of this property is not persistent. After - restart or unplugging of the adapter it will reset - back to false. - - string PowerState [readonly, experimental] - - The power state of an adapter. - - The power state will show whether the adapter is - turning off, or turning on, as well as being on - or off. - - Possible values: - "on" - powered on - "off" - powered off - "off-enabling" - transitioning from "off" to "on" - "on-disabling" - transitioning from "on" to "off" - "off-blocked" - blocked by rfkill - - boolean Discoverable [readwrite] - - Switch an adapter to discoverable or non-discoverable - to either make it visible or hide it. This is a global - setting and should only be used by the settings - application. - - If the DiscoverableTimeout is set to a non-zero - value then the system will set this value back to - false after the timer expired. - - In case the adapter is switched off, setting this - value will fail. - - When changing the Powered property the new state of - this property will be updated via a PropertiesChanged - signal. - - For any new adapter this settings defaults to false. - - boolean Pairable [readwrite] - - Switch an adapter to pairable or non-pairable. This is - a global setting and should only be used by the - settings application. - - Note that this property only affects incoming pairing - requests. - - For any new adapter this settings defaults to true. - - uint32 PairableTimeout [readwrite] - - The pairable timeout in seconds. A value of zero - means that the timeout is disabled and it will stay in - pairable mode forever. - - The default value for pairable timeout should be - disabled (value 0). - - uint32 DiscoverableTimeout [readwrite] - - The discoverable timeout in seconds. A value of zero - means that the timeout is disabled and it will stay in - discoverable/limited mode forever. - - The default value for the discoverable timeout should - be 180 seconds (3 minutes). - - boolean Discovering [readonly] - - Indicates that a device discovery procedure is active. - - array{string} UUIDs [readonly] - - List of 128-bit UUIDs that represents the available - local services. - - string Modalias [readonly, optional] - - Local Device ID information in modalias format - used by the kernel and udev. - - array{string} Roles [readonly] - - List of supported roles. Possible values: - "central": Supports the central role. - "peripheral": Supports the peripheral role. - "central-peripheral": Supports both roles - concurrently. - - array{string} ExperimentalFeatures [readonly, optional] - - List of 128-bit UUIDs that represents the experimental - features currently enabled. - - uint16 Manufacturer [readonly] - - The manufacturer of the device, as a uint16 company - identifier defined by the Core Bluetooth Specification. - - byte Version [readonly] - - The Bluetooth version supported by the device, as a - core version code defined by the Core Bluetooth - Specification. diff --git a/doc/org.bluez.Adapter.rst b/doc/org.bluez.Adapter.rst new file mode 100644 index 000000000000..f537281238e4 --- /dev/null +++ b/doc/org.bluez.Adapter.rst @@ -0,0 +1,412 @@ +================= +org.bluez.Adapter +================= + +------------------------------------- +BlueZ D-Bus Adapter API documentation +------------------------------------- + +:Version: BlueZ +:Date: October 2023 +:Manual section: 5 +:Manual group: Linux System Administration + +Interface +========= + +:Service: org.bluez +:Interface: org.bluez.Adapter1 +:Object path: [variable prefix]/{hci0,hci1,...} + +Methods +------- + +void StartDiscovery() +````````````````````` + + Starts device discovery session which may include starting an inquiry + and/or scanning procedures and remote device name resolving. + + Use **StopDiscovery** to release the sessions acquired. + + This process will start creating Device objects as new devices are + discovered. + + During discovery RSSI delta-threshold is imposed. + + Each client can request a single device discovery session per adapter. + + Possible errors: + + :org.bluez.Error.NotReady: + :org.bluez.Error.Failed: + :org.bluez.Error.InProgress: + +void StopDiscovery() +```````````````````` + + Stops device discovery session started by **StartDiscovery**. + + Note that a discovery procedure is shared between all discovery sessions + thus calling StopDiscovery will only release a single session and + discovery will stop when all sessions from all clients have finished. + + Possible errors: + + :org.bluez.Error.NotReady: + :org.bluez.Error.Failed: + :org.bluez.Error.NotAuthorized: + +void RemoveDevice(object device) +```````````````````````````````` + + Removes the remote device object at the given path including cahed + information such as bonding information. + + Possible errors: + + :org.bluez.Error.InvalidArguments: + :org.bluez.Error.Failed: + +void SetDiscoveryFilter(dict filter) +```````````````````````````````````` + + Sets the device discovery filter for the caller. When this method is + called with no filter parameter, filter is removed. + + Possible filter values: + + :array{string} UUIDs: + + Filter by service UUIDs, empty means match *any* UUID. + + When a remote device is found that advertises any UUID from + UUIDs, it will be reported if: + + - **Pathloss** and **RSSI** are both empty. + - only **Pathloss** param is set, device advertise TX power, and + computed pathloss is less than Pathloss param. + - only **RSSI** param is set, and received RSSI is higher + than RSSI param. + + :int16 RSSI: + + RSSI threshold value. + + PropertiesChanged signals will be emitted for already existing + Device objects, with updated RSSI value. If one or more + discovery filters have been set, the RSSI delta-threshold, that + is imposed by StartDiscovery by default, will not be applied. + + :uint16 Pathloss: + + Pathloss threshold value. + + PropertiesChanged signals will be emitted for already existing + Device objects, with updated Pathloss value. + + :string Transport (Default "auto"): + + Transport parameter determines the type of scan. + + Possible values: + + :"auto": + + Interleaved scan, use LE, BREDR, or both, depending on + what's currently enabled. + + :"bredr": + + BR/EDR inquiry only. + + :"le": + + LE scan only. + + + :bool DuplicateData (Default true): + + Disables duplicate detection of advertisement data. + + When enabled PropertiesChanged signals will be generated for + either ManufacturerData and ServiceData everytime they are + discovered. + + :bool Discoverable (Default false): + + Make adapter discoverable while discovering, if the adapter is + already discoverable setting this filter won't do anything. + + :string Pattern (Default none): + + Discover devices where the pattern matches either the prefix of + the address or device name which is convenient way to limited + the number of device objects created during a discovery. + + When set disregards device discoverable flags. + + Note: The pattern matching is ignored if there are other client + that don't set any pattern as it work as a logical OR, also + setting empty string "" pattern will match any device found. + + When discovery filter is set, Device objects will be created as + new devices with matching criteria are discovered regardless of + they are connectable or discoverable which enables listening to + non-connectable and non-discoverable devices. + + When multiple clients call SetDiscoveryFilter, their filters are + internally merged, and notifications about new devices are sent + to all clients. Therefore, each client must check that device + updates actually match its filter. + + When SetDiscoveryFilter is called multiple times by the same + client, last filter passed will be active for given client. + + SetDiscoveryFilter can be called before StartDiscovery. + It is useful when client will create first discovery session, + to ensure that proper scan will be started right after call to + StartDiscovery. + + Possible errors: + + :org.bluez.Error.NotReady: + :org.bluez.Error.NotSupported: + :org.bluez.Error.Failed: + +array{string} GetDiscoveryFilters() +``````````````````````````````````` + + Returns available filters that can be given to **SetDiscoveryFilter**. + + Possible errors: None + +object ConnectDevice(dict properties) [experimental] +```````````````````````````````````````````````````` + + connects to device without need of performing General Discovery. + Connection mechanism is similar to Connect method on + **org.bluez.Device1(5)** interface with exception that this method + returns success when physical connection is established and you can + specify bearer to connect with parameter. After this method returns, + services discovery will continue and any supported profile will be + connected. There is no need for calling Connect on Device1 after this + call. If connection was successful this method returns object path to + created device object or device that already exist. + + Possible properties values: + + :string Address (Mandatory): + + The Bluetooth device address of the remote device. + + :string AddressType (Default "BR/EDR"): + + The Bluetooth device Address Type. This is address type that + should be used for initial connection. + + Possible values: + + :"public": + + Public address + + :"random": + + Random address + + Possible errors: + + :org.bluez.Error.InvalidArguments: + :org.bluez.Error.AlreadyExists: + :org.bluez.Error.NotSupported: + :org.bluez.Error.NotReady: + :org.bluez.Error.Failed: + +Properties +---------- + +string Address [readonly] +````````````````````````` + + The Bluetooth device address. + +string AddressType [readonly] +````````````````````````````` + + The Bluetooth Address Type. For dual-mode and BR/EDR only adapter this + defaults to "public". Single mode LE adapters may have either value. + With privacy enabled this contains type of Identity Address and not + type of address used for connection. + + Possible values: + + :"public": + + Public address. + + + :"random: + + Random address. + +string Name [readonly] +`````````````````````` + + The Bluetooth system name (pretty hostname). + + This property is either a static system default or controlled by an + external daemon providing access to the pretty hostname configuration. + +string Alias [readwrite] +```````````````````````` + + The Bluetooth friendly name. This value can be changed. + + In case no alias is set, it will return the system provided name. + Setting an empty string as alias will convert it back to the system + provided name. + + When resetting the alias with an empty string, the property will default + back to system name. + + On a well configured system, this property never needs to be changed + since it defaults to the system name and provides the pretty hostname. + Only if the local name needs to be different from the pretty hostname, + this property should be used as last resort. + +uint32 Class [readonly] +``````````````````````` + + The Bluetooth class of device. + + This property represents the value that is either automatically + configured by DMI/ACPI information or provided as static configuration. + +boolean Powered [readwrite] +``````````````````````````` + + Switch an adapter on or off. This will also set the appropriate + connectable state of the controller. + + The value of this property is not persistent. After restart or + unplugging of the adapter it will reset back to false. + +string PowerState [readonly, experimental] +`````````````````````````````````````````` + + The power state of an adapter. + + The power state will show whether the adapter is turning off, or turning + on, as well as being on or off. + + Possible values: + + :"on": + + Powered on. + + :"off": + + Powered off + + :"off-enabling": + + Transitioning from "off" to "on". + + :"on-disabling": + + Transitioning from "on" to "off". + + :"off-blocked": + + Blocked by rfkill. + +boolean Discoverable [readwrite] (Default: false) +````````````````````````````````````````````````` + + Switch an adapter to discoverable or non-discoverable to either make it + visible or hide it. This is a global setting and should only be used by + the settings application. + + If the DiscoverableTimeout is set to a non-zero value then the system + will set this value back to false after the timer expired. + + In case the adapter is switched off, setting this value will fail. + + When changing the Powered property the new state of this property will + be updated via a PropertiesChanged signal. + +boolean Pairable [readwrite] (Default: true) +```````````````````````````````````````````` + + Switch an adapter to pairable or non-pairable. This is a global setting + and should only be used by the settings application. + + Note that this property only affects incoming pairing requests. + +uint32 PairableTimeout [readwrite] (Default: 0) +``````````````````````````````````````````````` + + The pairable timeout in seconds. A value of zero means that the timeout + is disabled and it will stay in pairable mode forever. + +uint32 DiscoverableTimeout [readwrite] (Default: 180) +````````````````````````````````````````````````````` + + The discoverable timeout in seconds. A value of zero means that the + timeout is disabled and it will stay in discoverable/limited mode + forever. + +boolean Discovering [readonly] +`````````````````````````````` + + Indicates that a device discovery procedure is active. + +array{string} UUIDs [readonly] +`````````````````````````````` + + List of 128-bit UUIDs that represents the available local services. + +string Modalias [readonly, optional] +```````````````````````````````````` + + Local Device ID information in modalias format used by the kernel and + udev. + +array{string} Roles [readonly] +`````````````````````````````` + + List of supported roles. + + Possible values: + + :"central": + + Supports the central role. + + :"peripheral": + + Supports the peripheral role. + + :"central-peripheral": + + Supports both roles concurrently. + +array{string} ExperimentalFeatures [readonly, optional] +``````````````````````````````````````````````````````` + + List of 128-bit UUIDs that represents the experimental features + currently enabled. + +uint16 Manufacturer [readonly] +`````````````````````````````` + + The manufacturer of the device, as a uint16 company identifier defined + by the Core Bluetooth Specification. + +byte Version [readonly] +``````````````````````` + + The Bluetooth version supported by the device, as a core version code + defined by the Core Bluetooth Specification. From patchwork Mon Oct 9 23:29:24 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luiz Augusto von Dentz X-Patchwork-Id: 13414675 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id C6082E9413E for ; Mon, 9 Oct 2023 23:29:44 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S234615AbjJIX3o (ORCPT ); Mon, 9 Oct 2023 19:29:44 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:55936 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231434AbjJIX3m (ORCPT ); Mon, 9 Oct 2023 19:29:42 -0400 Received: from mail-pg1-x529.google.com (mail-pg1-x529.google.com [IPv6:2607:f8b0:4864:20::529]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 8ADD3A7 for ; Mon, 9 Oct 2023 16:29:39 -0700 (PDT) Received: by mail-pg1-x529.google.com with SMTP id 41be03b00d2f7-58d26cfe863so808179a12.2 for ; Mon, 09 Oct 2023 16:29:39 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1696894178; x=1697498978; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=CqKUg053lyYsj/ooEOZyT990Wlr0Y5kgkhv8tFgOXzE=; b=gC0HF7PoX6bVd2TQe7JOOKxwT77el0nG12Bj34mVhV1avCTxc9DDQQCA4E7OK5SwLJ bXiwHxN+GH2OBIXubndirO+ENOSPiSYoH/YVjdThZac02EsvUEcurpSrI+BsuB4v2y8F uddU83ZcmtbcK29AE+r3LpoM4eNoPbufu6qXcfepUZAQ3vzxw21SzUQSOC7mIFncIneT jscu57aY8078bFr4mIgH6kHrgcaJvVXuvfN6I6oTNYogL/s7R9KvOZYPy0QposfkzILF qTkMLrflB/3im051DlnOuda+rJQjgQ4jdn+0Qb884w6Bjce9F5z1AaDw3J9JeolH0/JF jjOg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1696894178; x=1697498978; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=CqKUg053lyYsj/ooEOZyT990Wlr0Y5kgkhv8tFgOXzE=; b=rVFq0ZQA7HnvfVc6tnyKt6o94hRY8jm4MGHSKWsgVCpKPGUyDHro6DYWPFCnzqpjKz XGWYz8hTRsYDehI5Ipridpd44bxmHeondW+YO6ThmRp2STfrJjxxyw5IXu/BP6E4uQ9p skEWLN6spq2aSV8m+obJ1jYuREE8a//+B36sEIdZPkNvmzefPzWaAifSSw9dFdbcjEkh JePH7QSL/W+ZcOh44SJD7yS2XCGfuctv0TMklxkhzPB5zVgausx+qfUxBcXdnOBnHBoa b4YAmTa9WtfEBE+QKCdn+E9ms0rrOnoB7t0x+1tyfce2weOEC8rr8f37FiD5uozurMe/ vWVQ== X-Gm-Message-State: AOJu0YxzrlhV0pzFXqH7pOODkwlzKxKl2ywradr9KPuFld72xkivwuuC tSPDW4PQ13e2YG+0w0NJ/IDc39o8xEZajUU0 X-Google-Smtp-Source: AGHT+IHsLM7kRIdE7CL0q19bu1EBe+THGBPEJ2/zo2Ah6io0k42fzmOkQ5ph20+AMxYXfThggboNsQ== X-Received: by 2002:a05:6a21:3e07:b0:171:c88a:891e with SMTP id bk7-20020a056a213e0700b00171c88a891emr298951pzc.55.1696894177976; Mon, 09 Oct 2023 16:29:37 -0700 (PDT) Received: from lvondent-mobl4.. (c-98-232-221-87.hsd1.or.comcast.net. [98.232.221.87]) by smtp.gmail.com with ESMTPSA id s20-20020a170902989400b001c5b8087fe5sm10182711plp.94.2023.10.09.16.29.35 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 09 Oct 2023 16:29:36 -0700 (PDT) From: Luiz Augusto von Dentz To: linux-bluetooth@vger.kernel.org Subject: [PATCH v2 02/11] doc/device-api: Rename to org.bluez.Device.rst Date: Mon, 9 Oct 2023 16:29:24 -0700 Message-ID: <20231009232933.500652-2-luiz.dentz@gmail.com> X-Mailer: git-send-email 2.41.0 In-Reply-To: <20231009232933.500652-1-luiz.dentz@gmail.com> References: <20231009232933.500652-1-luiz.dentz@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-bluetooth@vger.kernel.org From: Luiz Augusto von Dentz This renames device-api.txt to org.bluez.Device.rst and generate a manpage org.bluez.Device.5. --- Makefile.am | 10 +- doc/device-api.txt | 293 ---------------------------------- doc/org.bluez.Device.rst | 329 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 335 insertions(+), 297 deletions(-) delete mode 100644 doc/device-api.txt create mode 100644 doc/org.bluez.Device.rst diff --git a/Makefile.am b/Makefile.am index 5eb94985a1b7..9e74f4f0fc76 100644 --- a/Makefile.am +++ b/Makefile.am @@ -357,14 +357,16 @@ CLEANFILES += $(builtin_files) src/bluetooth.service if MANPAGES man_MANS += src/bluetoothd.8 -man_MANS += doc/org.bluez.Adapter.5 doc/org.bluez.DeviceSet.5 +man_MANS += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \ + doc/org.bluez.DeviceSet.5 man_MANS += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \ doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \ doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \ doc/org.bluez.MediaTransport.5 endif manual_pages += src/bluetoothd.8 -manual_pages += doc/org.bluez.Adapter.5 doc/org.bluez.DeviceSet.5 +manual_pages += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \ + doc/org.bluez.DeviceSet.5 manual_pages += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \ doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \ doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \ @@ -405,12 +407,12 @@ EXTRA_DIST += doc/assigned-numbers.txt doc/supported-features.txt \ doc/settings-storage.txt EXTRA_DIST += doc/mgmt-api.txt \ - doc/device-api.txt \ doc/agent-api.txt doc/profile-api.txt \ doc/network-api.txt doc/health-api.txt \ doc/sap-api.txt doc/input-api.txt -EXTRA_DIST += doc/org.bluez.Adapter.rst doc/org.bluez.DeviceSet.rst +EXTRA_DIST += doc/org.bluez.Adapter.rst doc/org.bluez.Device.rst \ + doc/org.bluez.DeviceSet.rst EXTRA_DIST += doc/org.bluez.Media.rst doc/org.bluez.MediaControl.rst \ doc/org.bluez.MediaPlayer.rst doc/org.bluez.MediaFolder.rst \ diff --git a/doc/device-api.txt b/doc/device-api.txt deleted file mode 100644 index e4a8d3c5af33..000000000000 --- a/doc/device-api.txt +++ /dev/null @@ -1,293 +0,0 @@ -BlueZ D-Bus Device API description -********************************** - - -Device hierarchy -================ - -Service org.bluez -Interface org.bluez.Device1 -Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX - -Methods void Connect() - - This is a generic method to connect any profiles - the remote device supports that can be connected - to and have been flagged as auto-connectable on - our side. If only subset of profiles is already - connected it will try to connect currently disconnected - ones. - - If at least one profile was connected successfully this - method will indicate success. - - For dual-mode devices only one bearer is connected at - time, the conditions are in the following order: - - 1. Connect the disconnected bearer if already - connected. - - 2. Connect first the bonded bearer. If no - bearers are bonded or both are skip and check - latest seen bearer. - - 3. Connect last seen bearer, in case the - timestamps are the same BR/EDR takes - precedence. - - Possible errors: org.bluez.Error.NotReady - org.bluez.Error.Failed - org.bluez.Error.InProgress - org.bluez.Error.AlreadyConnected - - void Disconnect() - - This method gracefully disconnects all connected - profiles and then terminates low-level ACL connection. - - ACL connection will be terminated even if some profiles - were not disconnected properly e.g. due to misbehaving - device. - - This method can be also used to cancel a preceding - Connect call before a reply to it has been received. - - For non-trusted devices connected over LE bearer calling - this method will disable incoming connections until - Connect method is called again. - - Possible errors: org.bluez.Error.NotConnected - - void ConnectProfile(string uuid) - - This method connects a specific profile of this - device. The UUID provided is the remote service - UUID for the profile. - - Possible errors: org.bluez.Error.Failed - org.bluez.Error.InProgress - org.bluez.Error.InvalidArguments - org.bluez.Error.NotAvailable - org.bluez.Error.NotReady - - void DisconnectProfile(string uuid) - - This method disconnects a specific profile of - this device. The profile needs to be registered - client profile. - - There is no connection tracking for a profile, so - as long as the profile is registered this will always - succeed. - - Possible errors: org.bluez.Error.Failed - org.bluez.Error.InProgress - org.bluez.Error.InvalidArguments - org.bluez.Error.NotSupported - - void Pair() - - This method will connect to the remote device, - initiate pairing and then retrieve all SDP records - (or GATT primary services). - - If the application has registered its own agent, - then that specific agent will be used. Otherwise - it will use the default agent. - - Only for applications like a pairing wizard it - would make sense to have its own agent. In almost - all other cases the default agent will handle - this just fine. - - In case there is no application agent and also - no default agent present, this method will fail. - - Possible errors: org.bluez.Error.InvalidArguments - org.bluez.Error.Failed - org.bluez.Error.AlreadyExists - org.bluez.Error.AuthenticationCanceled - org.bluez.Error.AuthenticationFailed - org.bluez.Error.AuthenticationRejected - org.bluez.Error.AuthenticationTimeout - org.bluez.Error.ConnectionAttemptFailed - - void CancelPairing() - - This method can be used to cancel a pairing - operation initiated by the Pair method. - - Possible errors: org.bluez.Error.DoesNotExist - org.bluez.Error.Failed - -Properties string Address [readonly] - - The Bluetooth device address of the remote device. - - string AddressType [readonly] - - The Bluetooth device Address Type. For dual-mode and - BR/EDR only devices this defaults to "public". Single - mode LE devices may have either value. If remote device - uses privacy than before pairing this represents address - type used for connection and Identity Address after - pairing. - - Possible values: - "public" - Public address - "random" - Random address - - string Name [readonly, optional] - - The Bluetooth remote name. This value can not be - changed. Use the Alias property instead. - - This value is only present for completeness. It is - better to always use the Alias property when - displaying the devices name. - - If the Alias property is unset, it will reflect - this value which makes it more convenient. - - string Icon [readonly, optional] - - Proposed icon name according to the freedesktop.org - icon naming specification. - - uint32 Class [readonly, optional] - - The Bluetooth class of device of the remote device. - - uint16 Appearance [readonly, optional] - - External appearance of device, as found on GAP service. - - array{string} UUIDs [readonly, optional] - - List of 128-bit UUIDs that represents the available - remote services. - - boolean Paired [readonly] - - Indicates if the remote device is paired. Paired means - the pairing process where devices exchange the - information to establish an encrypted connection has - been completed. - - boolean Bonded [readonly] - - Indicates if the remote device is bonded. Bonded means - the information exchanged on pairing process has been - stored and will be persisted. - - boolean Connected [readonly] - - Indicates if the remote device is currently connected. - A PropertiesChanged signal indicate changes to this - status. - - boolean Trusted [readwrite] - - Indicates if the remote is seen as trusted. This - setting can be changed by the application. - - boolean Blocked [readwrite] - - If set to true any incoming connections from the - device will be immediately rejected. Any device - drivers will also be removed and no new ones will - be probed as long as the device is blocked. - - boolean WakeAllowed [readwrite] - - If set to true this device will be allowed to wake the - host from system suspend. - - string Alias [readwrite] - - The name alias for the remote device. The alias can - be used to have a different friendly name for the - remote device. - - In case no alias is set, it will return the remote - device name. Setting an empty string as alias will - convert it back to the remote device name. - - When resetting the alias with an empty string, the - property will default back to the remote name. - - object Adapter [readonly] - - The object path of the adapter the device belongs to. - - boolean LegacyPairing [readonly] - - Set to true if the device only supports the pre-2.1 - pairing mechanism. This property is useful during - device discovery to anticipate whether legacy or - simple pairing will occur if pairing is initiated. - - Note that this property can exhibit false-positives - in the case of Bluetooth 2.1 (or newer) devices that - have disabled Extended Inquiry Response support. - - string Modalias [readonly, optional] - - Remote Device ID information in modalias format - used by the kernel and udev. - - int16 RSSI [readonly, optional] - - Received Signal Strength Indicator of the remote - device (inquiry or advertising). - - int16 TxPower [readonly, optional] - - Advertised transmitted power level (inquiry or - advertising). - - dict ManufacturerData [readonly, optional] - - Manufacturer specific advertisement data. Keys are - 16 bits Manufacturer ID followed by its byte array - value. - - dict ServiceData [readonly, optional] - - Service advertisement data. Keys are the UUIDs in - string format followed by its byte array value. - - bool ServicesResolved [readonly] - - Indicate whether or not service discovery has been - resolved. - - array{byte} AdvertisingFlags [readonly, experimental] - - The Advertising Data Flags of the remote device. - - dict AdvertisingData [readonly, experimental] - - The Advertising Data of the remote device. Keys are - are 8 bits AD Type followed by data as byte array. - - Note: Only types considered safe to be handled by - application are exposed. - - Possible values: - - ... - - Example: - - 0x26 0x01 0x01... - - array{object, dict} Sets [readonly, experimental] - - The object paths of the sets the device belongs to - followed by a dictionary which can contain the - following: - - byte Rank: - - Rank of the device in the Set. diff --git a/doc/org.bluez.Device.rst b/doc/org.bluez.Device.rst new file mode 100644 index 000000000000..4fdb31b0acbe --- /dev/null +++ b/doc/org.bluez.Device.rst @@ -0,0 +1,329 @@ +================ +org.bluez.Device +================ + +------------------------------------ +BlueZ D-Bus Device API documentation +------------------------------------ + +:Version: BlueZ +:Date: October 2023 +:Manual section: 5 +:Manual group: Linux System Administration + +Interface +========= + +:Service: org.bluez +:Interface: org.bluez.Device1 +:Object path: [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX + +Methods +------- + +void Connect() +`````````````` + + Connects all profiles the remote device supports that can be connected + to and have been flagged as auto-connectable. If only subset of profiles + is already connected it will try to connect currently disconnected ones. + + If at least one profile was connected successfully this method will + indicate success. + + For dual-mode devices only one bearer is connected at time, the + conditions are in the following order: + + 1. Connect the disconnected bearer if already connected. + + 2. Connect first the bonded bearer. If no bearers are bonded or both + are skip and check latest seen bearer. + + 3. Connect last seen bearer, in case the timestamps are the same BR/EDR + takes precedence. + + Possible errors: + + :org.bluez.Error.NotReady: + :org.bluez.Error.Failed: + :org.bluez.Error.InProgress: + :org.bluez.Error.AlreadyConnected: + +void Disconnect() +````````````````` + + Disconnects all connected profiles and then terminates low-level ACL + connection. + + ACL connection will be terminated even if some profiles were not + disconnected properly e.g. due to misbehaving device. + + This method can be also used to cancel a preceding Connect call before + a reply to it has been received. + + For non-trusted devices connected over LE bearer calling this method + will disable incoming connections until Connect method is called again. + + Possible errors: + + :org.bluez.Error.NotConnected: + +void ConnectProfile(string uuid) +```````````````````````````````` + + Connects a specific profile of this device. The UUID provided is the + remote service UUID for the profile. + + Possible errors: + + :org.bluez.Error.Failed: + :org.bluez.Error.InProgress: + :org.bluez.Error.InvalidArguments: + :org.bluez.Error.NotAvailable: + :org.bluez.Error.NotReady: + +void DisconnectProfile(string uuid) +``````````````````````````````````` + + Disconnects a specific profile of this device. The profile needs to be + registered client profile. + + There is no connection tracking for a profile, so as long as the + profile is registered this will always succeed. + + Possible errors: + + :org.bluez.Error.Failed: + :org.bluez.Error.InProgress: + :org.bluez.Error.InvalidArguments: + :org.bluez.Error.NotSupported: + +void Pair() +``````````` + + Connects to the remote device and initiate pairing procedure then + proceed with service discovery. + + If the application has registered its own agent, then that specific + agent will be used. Otherwise it will use the default agent. + + Only for applications like a pairing wizard it would make sense to have + its own agent. In almost all other cases the default agent will handle + this just fine. + + In case there is no application agent and also no default agent present, + this method will fail. + + Possible errors: + + :org.bluez.Error.InvalidArguments: + :org.bluez.Error.Failed: + :org.bluez.Error.AlreadyExists: + :org.bluez.Error.AuthenticationCanceled: + :org.bluez.Error.AuthenticationFailed: + :org.bluez.Error.AuthenticationRejected: + :org.bluez.Error.AuthenticationTimeout: + :org.bluez.Error.ConnectionAttemptFailed: + +void CancelPairing() +```````````````````` + + Cancels a pairing operation initiated by the **Pair** method. + + Possible errors: + + :org.bluez.Error.DoesNotExist: + :org.bluez.Error.Failed: + +Properties +---------- + +string Address [readonly] +````````````````````````` + + The Bluetooth device address of the remote device. + +string AddressType [readonly] +````````````````````````````` + + The Bluetooth device Address Type. For dual-mode and BR/EDR only devices + this defaults to "public". Single mode LE devices may have either value. + If remote device uses privacy than before pairing this represents + address type used for connection and Identity Address after pairing. + + Possible values: + + :"public": + + Public address + + :"random": + + Random address + +string Name [readonly, optional] +```````````````````````````````` + + The Bluetooth remote name. + + This value is only present for completeness. It is better to always use + the **Alias** property when displaying the devices name. + + If the **Alias** property is unset, it will reflect this value which + makes it more convenient. + +string Icon [readonly, optional] +```````````````````````````````` + + Proposed icon name according to the freedesktop.org icon naming + specification. + +uint32 Class [readonly, optional] +````````````````````````````````` + + The Bluetooth class of device of the remote device. + +uint16 Appearance [readonly, optional] +`````````````````````````````````````` + + External appearance of device, as found on GAP service. + +array{string} UUIDs [readonly, optional] +```````````````````````````````````````` + + List of 128-bit UUIDs that represents the available remote services. + +boolean Paired [readonly] +````````````````````````` + + Indicates if the remote device is paired. Paired means the pairing + process where devices exchange the information to establish an + encrypted connection has been completed. + +boolean Bonded [readonly] +````````````````````````` + + Indicates if the remote device is bonded. Bonded means the information + exchanged on pairing process has been stored and will be persisted. + +boolean Connected [readonly] +```````````````````````````` + + Indicates if the remote device is currently connected. + A PropertiesChanged signal indicate changes to this status. + +boolean Trusted [readwrite] +``````````````````````````` + + Indicates if the remote is seen as trusted. This setting can be changed + by the application. + +boolean Blocked [readwrite] +``````````````````````````` + + If set to true any incoming connections from the device will be + immediately rejected. Any device drivers will also be removed and + no new ones will be probed as long as the device is blocked. + +boolean WakeAllowed [readwrite] +``````````````````````````````` + + If set to true this device will be allowed to wake the host from + system suspend. + +string Alias [readwrite] +```````````````````````` + + The name alias for the remote device. The alias can be used to have a + different friendly name for the remote device. + + In case no alias is set, it will return the remote device name. Setting + an empty string as alias will convert it back to the remote device name. + + When resetting the alias with an empty string, the property will default + back to the remote name. + +object Adapter [readonly] +````````````````````````` + + The object path of the adapter the device belongs to. + +boolean LegacyPairing [readonly] +```````````````````````````````` + + Set to true if the device only supports the pre-2.1 pairing mechanism. + This property is useful during device discovery to anticipate whether + legacy or simple pairing will occur if pairing is initiated. + + Note that this property can exhibit false-positives in the case of + Bluetooth 2.1 (or newer) devices that have disabled Extended Inquiry + Response support. + +string Modalias [readonly, optional] +```````````````````````````````````` + + Remote Device ID information in modalias format used by the kernel and + udev. + +int16 RSSI [readonly, optional] +``````````````````````````````` + + Received Signal Strength Indicator of the remote device (inquiry or + advertising). + +int16 TxPower [readonly, optional] +`````````````````````````````````` + + Advertised transmitted power level (inquiry or advertising). + +dict ManufacturerData [readonly, optional] +`````````````````````````````````````````` + + Manufacturer specific advertisement data. Keys are 16 bits Manufacturer + ID followed by its byte array value. + +dict ServiceData [readonly, optional] +````````````````````````````````````` + + Service advertisement data. Keys are the UUIDs in string format followed + by its byte array value. + +bool ServicesResolved [readonly] +```````````````````````````````` + + Indicate whether or not service discovery has been resolved. + +array{byte} AdvertisingFlags [readonly, experimental] +````````````````````````````````````````````````````` + + The Advertising Data Flags of the remote device. + +dict AdvertisingData [readonly, experimental] +````````````````````````````````````````````` + + The Advertising Data of the remote device. Keys are 1 byte AD Type + followed by data as byte array. + + Note: Only types considered safe to be handled by application are + exposed. + + Possible values: + + :: + + + + Example: + + + 0x26 0x01 0x01... + +array{object, dict} Sets [readonly, experimental] +````````````````````````````````````````````````` + + The object paths of the sets the device belongs to followed by a + dictionary which can contain the following: + + :byte Rank: + + Rank of the device in the Set. From patchwork Mon Oct 9 23:29:25 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luiz Augusto von Dentz X-Patchwork-Id: 13414676 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 72F6AE95A8D for ; Mon, 9 Oct 2023 23:29:45 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1378202AbjJIX3p (ORCPT ); Mon, 9 Oct 2023 19:29:45 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:55948 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232095AbjJIX3o (ORCPT ); Mon, 9 Oct 2023 19:29:44 -0400 Received: from mail-pl1-x62f.google.com (mail-pl1-x62f.google.com [IPv6:2607:f8b0:4864:20::62f]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id F1D619D for ; Mon, 9 Oct 2023 16:29:41 -0700 (PDT) Received: by mail-pl1-x62f.google.com with SMTP id d9443c01a7336-1c888b3a25aso30029025ad.0 for ; Mon, 09 Oct 2023 16:29:41 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1696894180; x=1697498980; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=R3unjQojlbVvLNK7E7W62JL7SG6twcnQHkRwrrK4+Zo=; b=CpcR1BkxVzElEmXQ35ZfNpGxNZF1PTApVFdgWM3GdiuKguz+59y/hVb11MnUqn+s0H 5qFCUhL06toJ7MWr16XZvPWxPm1JDl5+leIwfyQU74tGBx4KEB4K5DP7rDkpJMvql1BS GaVwL7PPMhvXJeXBNtSMSAVb8O01+B8azUdsQL59BtdMOt37f9X6jbx5lB825TeGYEfG oAz3n2goCUDfuNUT1V0rns3yTaiJy4BLqjovUmqovNX81AdtbjSPsC8KLkPzKLEK/zhn q1ZeIlAunnI66lL30osiE4gTV13sGwfJsLkbkaZDUnGpNJYjxsfedn1P+aXK1PLi7CvU Fe8g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1696894180; x=1697498980; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=R3unjQojlbVvLNK7E7W62JL7SG6twcnQHkRwrrK4+Zo=; b=S4apKyEozxv3xi9QZqzNxu1HJ5AO3Qv7Vsxmx9+IVKX4q0ER+a2bZ9eAeDt8rHkAaP qQLLnLjOWw2ctqdpQc3WLt2JcdIwhxBzWyEFyubZh2u2M6BjEP3BMGb3RO2GULGjQv0j a2be+BK9CC16WRAED+Yl0qdr07YbNL5BrmpXsXeO028e96i5YAfuAyWLzLwMGoq8k9bO KWN3lvLYFgl/uHa+MDgcOikJUiEemZNpBKOOkKhNz/ajJJHTjyXnhybd2UGm2yadx42W hu97MrYPYaLpEYk+r+p9E/742vmU0jQuOQ7It9u8i0+/aUWFLlhAJaPa5YN0r3RkDoYm 57rA== X-Gm-Message-State: AOJu0Yzr05cnAl0kQPSjiFGKJ3y8iFcoIzk+qfirlSF9lS9fr53C//nK RZiwG6SBjZjL93hPYOpdf5zIsMSYO0YjTlUt X-Google-Smtp-Source: AGHT+IEwBoMCigec7Te6fGge/ZnPvb5Wl435ILOeXtyYNTavDi8GDZZHXW//6wb03/+AY7iNZGAmNQ== X-Received: by 2002:a17:903:1c6:b0:1bf:7d3b:4405 with SMTP id e6-20020a17090301c600b001bf7d3b4405mr18438515plh.14.1696894180338; Mon, 09 Oct 2023 16:29:40 -0700 (PDT) Received: from lvondent-mobl4.. (c-98-232-221-87.hsd1.or.comcast.net. [98.232.221.87]) by smtp.gmail.com with ESMTPSA id s20-20020a170902989400b001c5b8087fe5sm10182711plp.94.2023.10.09.16.29.38 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 09 Oct 2023 16:29:38 -0700 (PDT) From: Luiz Augusto von Dentz To: linux-bluetooth@vger.kernel.org Subject: [PATCH v2 03/11] doc/agent-api: Rename to org.bluez.Agent{Manager}.rst Date: Mon, 9 Oct 2023 16:29:25 -0700 Message-ID: <20231009232933.500652-3-luiz.dentz@gmail.com> X-Mailer: git-send-email 2.41.0 In-Reply-To: <20231009232933.500652-1-luiz.dentz@gmail.com> References: <20231009232933.500652-1-luiz.dentz@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-bluetooth@vger.kernel.org From: Luiz Augusto von Dentz This renames agent-api.txt to org.bluez.Agent{Manager}.rst and generate manpages org.bluez.Agent{Manager}.5. --- Makefile.am | 11 +- doc/agent-api.txt | 185 --------------------------------- doc/org.bluez.Agent.rst | 149 ++++++++++++++++++++++++++ doc/org.bluez.AgentManager.rst | 83 +++++++++++++++ 4 files changed, 239 insertions(+), 189 deletions(-) delete mode 100644 doc/agent-api.txt create mode 100644 doc/org.bluez.Agent.rst create mode 100644 doc/org.bluez.AgentManager.rst diff --git a/Makefile.am b/Makefile.am index 9e74f4f0fc76..b25bc521cab3 100644 --- a/Makefile.am +++ b/Makefile.am @@ -358,7 +358,8 @@ CLEANFILES += $(builtin_files) src/bluetooth.service if MANPAGES man_MANS += src/bluetoothd.8 man_MANS += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \ - doc/org.bluez.DeviceSet.5 + doc/org.bluez.DeviceSet.5 doc/org.bluez.AgentManager.5 \ + doc/org.bluez.Agent.5 man_MANS += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \ doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \ doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \ @@ -366,7 +367,8 @@ man_MANS += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \ endif manual_pages += src/bluetoothd.8 manual_pages += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \ - doc/org.bluez.DeviceSet.5 + doc/org.bluez.DeviceSet.5 doc/org.bluez.AgentManager.5 \ + doc/org.bluez.Agent.5 manual_pages += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \ doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \ doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \ @@ -407,12 +409,13 @@ EXTRA_DIST += doc/assigned-numbers.txt doc/supported-features.txt \ doc/settings-storage.txt EXTRA_DIST += doc/mgmt-api.txt \ - doc/agent-api.txt doc/profile-api.txt \ + doc/profile-api.txt \ doc/network-api.txt doc/health-api.txt \ doc/sap-api.txt doc/input-api.txt EXTRA_DIST += doc/org.bluez.Adapter.rst doc/org.bluez.Device.rst \ - doc/org.bluez.DeviceSet.rst + doc/org.bluez.DeviceSet.rst doc/org.bluez.AgentManager.rst \ + doc/org.bluez.Agent.rst EXTRA_DIST += doc/org.bluez.Media.rst doc/org.bluez.MediaControl.rst \ doc/org.bluez.MediaPlayer.rst doc/org.bluez.MediaFolder.rst \ diff --git a/doc/agent-api.txt b/doc/agent-api.txt deleted file mode 100644 index 0d9347cab390..000000000000 --- a/doc/agent-api.txt +++ /dev/null @@ -1,185 +0,0 @@ -BlueZ D-Bus Agent API description -********************************** - - -Agent Manager hierarchy -======================= - -Service org.bluez -Interface org.bluez.AgentManager1 -Object path /org/bluez - - void RegisterAgent(object agent, string capability) - - This registers an agent handler. - - The object path defines the path of the agent - that will be called when user input is needed. - - Every application can register its own agent and - for all actions triggered by that application its - agent is used. - - It is not required by an application to register - an agent. If an application does chooses to not - register an agent, the default agent is used. This - is on most cases a good idea. Only application - like a pairing wizard should register their own - agent. - - An application can only register one agent. Multiple - agents per application is not supported. - - The capability parameter can have the values - "DisplayOnly", "DisplayYesNo", "KeyboardOnly", - "NoInputNoOutput" and "KeyboardDisplay" which - reflects the input and output capabilities of the - agent. - - If an empty string is used it will fallback to - "KeyboardDisplay". - - Possible errors: org.bluez.Error.InvalidArguments - org.bluez.Error.AlreadyExists - - void UnregisterAgent(object agent) - - This unregisters the agent that has been previously - registered. The object path parameter must match the - same value that has been used on registration. - - Possible errors: org.bluez.Error.DoesNotExist - - void RequestDefaultAgent(object agent) - - This requests is to make the application agent - the default agent. The application is required - to register an agent. - - Special permission might be required to become - the default agent. - - Possible errors: org.bluez.Error.DoesNotExist - - -Agent hierarchy -=============== - -Service unique name -Interface org.bluez.Agent1 -Object path freely definable - -Methods void Release() - - This method gets called when the service daemon - unregisters the agent. An agent can use it to do - cleanup tasks. There is no need to unregister the - agent, because when this method gets called it has - already been unregistered. - - string RequestPinCode(object device) - - This method gets called when the service daemon - needs to get the passkey for an authentication. - - The return value should be a string of 1-16 characters - length. The string can be alphanumeric. - - Possible errors: org.bluez.Error.Rejected - org.bluez.Error.Canceled - - void DisplayPinCode(object device, string pincode) - - This method gets called when the service daemon - needs to display a pincode for an authentication. - - An empty reply should be returned. When the pincode - needs no longer to be displayed, the Cancel method - of the agent will be called. - - This is used during the pairing process of keyboards - that don't support Bluetooth 2.1 Secure Simple Pairing, - in contrast to DisplayPasskey which is used for those - that do. - - This method will only ever be called once since - older keyboards do not support typing notification. - - Note that the PIN will always be a 6-digit number, - zero-padded to 6 digits. This is for harmony with - the later specification. - - Possible errors: org.bluez.Error.Rejected - org.bluez.Error.Canceled - - uint32 RequestPasskey(object device) - - This method gets called when the service daemon - needs to get the passkey for an authentication. - - The return value should be a numeric value - between 0-999999. - - Possible errors: org.bluez.Error.Rejected - org.bluez.Error.Canceled - - void DisplayPasskey(object device, uint32 passkey, - uint16 entered) - - This method gets called when the service daemon - needs to display a passkey for an authentication. - - The entered parameter indicates the number of already - typed keys on the remote side. - - An empty reply should be returned. When the passkey - needs no longer to be displayed, the Cancel method - of the agent will be called. - - During the pairing process this method might be - called multiple times to update the entered value. - - Note that the passkey will always be a 6-digit number, - so the display should be zero-padded at the start if - the value contains less than 6 digits. - - void RequestConfirmation(object device, uint32 passkey) - - This method gets called when the service daemon - needs to confirm a passkey for an authentication. - - To confirm the value it should return an empty reply - or an error in case the passkey is invalid. - - Note that the passkey will always be a 6-digit number, - so the display should be zero-padded at the start if - the value contains less than 6 digits. - - Possible errors: org.bluez.Error.Rejected - org.bluez.Error.Canceled - - void RequestAuthorization(object device) - - This method gets called to request the user to - authorize an incoming pairing attempt which - would in other circumstances trigger the just-works - model, or when the user plugged in a device that - implements cable pairing. In the latter case, the - device would not be connected to the adapter via - Bluetooth yet. - - Possible errors: org.bluez.Error.Rejected - org.bluez.Error.Canceled - - void AuthorizeService(object device, string uuid) - - This method gets called when the service daemon - needs to authorize a connection/service request. - - Possible errors: org.bluez.Error.Rejected - org.bluez.Error.Canceled - - void Cancel() - - This method gets called to indicate that the agent - request failed before a reply was returned. diff --git a/doc/org.bluez.Agent.rst b/doc/org.bluez.Agent.rst new file mode 100644 index 000000000000..11d09b94d228 --- /dev/null +++ b/doc/org.bluez.Agent.rst @@ -0,0 +1,149 @@ +=============== +org.bluez.Agent +=============== + +----------------------------------- +BlueZ D-Bus Agent API documentation +----------------------------------- + +:Version: BlueZ +:Date: October 2023 +:Manual section: 5 +:Manual group: Linux System Administration + +Interface +========= + +:Service: unique name +:Interface: org.bluez.Agent1 +:Object path: freely definable + +Methods +------- + +void Release() +`````````````` + + This method gets called when the service daemon unregisters the agent. + An agent can use it to do cleanup tasks. There is no need to unregister + the agent, because when this method gets called it has already been + unregistered. + +string RequestPinCode(object device) +```````````````````````````````````` + + This method gets called when the service daemon needs to get the passkey + for an authentication. + + The return value should be a string of 1-16 characters length. The + string can be alphanumeric. + + Possible errors: + + :org.bluez.Error.Rejected: + :org.bluez.Error.Canceled: + +void DisplayPinCode(object device, string pincode) +`````````````````````````````````````````````````` + + This method gets called when the service daemon needs to display a + pincode for an authentication. + + An empty reply should be returned. When the pincode needs no longer to + be displayed, the Cancel method of the agent will be called. + + This is used during the pairing process of keyboards that don't support + Bluetooth 2.1 Secure Simple Pairing, in contrast to DisplayPasskey which + is used for those that do. + + This method will only ever be called once since older keyboards do not + support typing notification. + + Note that the PIN will always be a 6-digit number, zero-padded to 6 + digits. This is for harmony with the later specification. + + Possible errors: + + :org.bluez.Error.Rejected: + :org.bluez.Error.Canceled: + +uint32 RequestPasskey(object device) +```````````````````````````````````` + + This method gets called when the service daemon needs to get the passkey + for an authentication. + + The return value should be a numeric value between 0-999999. + + Possible errors: + + :org.bluez.Error.Rejected: + :org.bluez.Error.Canceled: + +void DisplayPasskey(object device, uint32 passkey, uint16 entered) +`````````````````````````````````````````````````````````````````` + + This method gets called when the service daemon needs to display a + passkey for an authentication. + + The entered parameter indicates the number of already typed keys on the + remote side. + + An empty reply should be returned. When the passkey needs no longer to + be displayed, the Cancel method of the agent will be called. + + During the pairing process this method might be called multiple times to + update the entered value. + + Note that the passkey will always be a 6-digit number, so the display + should be zero-padded at the start if the value contains less than 6 + digits. + +void RequestConfirmation(object device, uint32 passkey) +``````````````````````````````````````````````````````` + + This method gets called when the service daemon needs to confirm a + passkey for an authentication. + + To confirm the value it should return an empty reply or an error in case + the passkey is invalid. + + Note that the passkey will always be a 6-digit number, so the display + should be zero-padded at the start if the value contains less than 6 + digits. + + Possible errors: + + :org.bluez.Error.Rejected: + :org.bluez.Error.Canceled: + +void RequestAuthorization(object device) +```````````````````````````````````````` + + This method gets called to request the user to authorize an incoming + pairing attempt which would in other circumstances trigger the + just-works model, or when the user plugged in a device that implements + cable pairing. In the latter case, the device would not be connected to + the adapter via Bluetooth yet. + + Possible errors: + + :org.bluez.Error.Rejected: + :org.bluez.Error.Canceled: + +void AuthorizeService(object device, string uuid) +````````````````````````````````````````````````` + + This method gets called when the service daemon needs to authorize a + connection/service request. + + Possible errors: + + :org.bluez.Error.Rejected: + :org.bluez.Error.Canceled: + +void Cancel() +````````````` + + This method gets called to indicate that the agent request failed before + a reply was returned. diff --git a/doc/org.bluez.AgentManager.rst b/doc/org.bluez.AgentManager.rst new file mode 100644 index 000000000000..dfc0297da8d2 --- /dev/null +++ b/doc/org.bluez.AgentManager.rst @@ -0,0 +1,83 @@ +====================== +org.bluez.AgentManager +====================== + +------------------------------------------ +BlueZ D-Bus AgentManager API documentation +------------------------------------------ + +:Version: BlueZ +:Date: October 2023 +:Manual section: 5 +:Manual group: Linux System Administration + +Interface +========= + +:Service: org.bluez +:Interface: org.bluez.AgentManager1 +:Object path: /org/bluez + +Methods +------- + +void RegisterAgent(object agent, string capability) +``````````````````````````````````````````````````` + + Registers pairing agent. + + The object path defines the path of the agent that will be called when + user input is needed and must implement **org.bluez.Agent(5)** + interface. + + Every application can register its own agent and for all actions + triggered by that application its agent is used. + + It is not required by an application to register an agent. If an + application does chooses to not register an agent, the default agent is + used. This is on most cases a good idea. Only application like a pairing + wizard should register their own agent. + + An application can only register one agent. Multiple agents per + application is not supported. + + Possible capability values: + + :"": + + Fallback to "KeyboardDisplay". + + :"DisplayOnly": + :"DisplayYesNo": + :"KeyboardOnly": + :"NoInputNoOutput": + :"KeyboardDisplay": + + Possible errors: + + :org.bluez.Error.InvalidArguments: + :org.bluez.Error.AlreadyExists: + +void UnregisterAgent(object agent) +`````````````````````````````````` + + Unregisters an agent that has been previously registered using + **RegisterAgent**. The object path parameter must match the same value + that has been used on registration. + + Possible errors: + + :org.bluez.Error.DoesNotExist: + +void RequestDefaultAgent(object agent) +`````````````````````````````````````` + + Requests to make the application agent the default agent. The + application is required to register an agent. + + Special permission might be required to become the default agent. + + Possible errors: + + :org.bluez.Error.DoesNotExist: + From patchwork Mon Oct 9 23:29:26 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luiz Augusto von Dentz X-Patchwork-Id: 13414677 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id E57DCE95A9C for ; Mon, 9 Oct 2023 23:29:47 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1379093AbjJIX3r (ORCPT ); Mon, 9 Oct 2023 19:29:47 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:58926 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1379050AbjJIX3q (ORCPT ); Mon, 9 Oct 2023 19:29:46 -0400 Received: from mail-pl1-x62e.google.com (mail-pl1-x62e.google.com [IPv6:2607:f8b0:4864:20::62e]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id E52089D for ; Mon, 9 Oct 2023 16:29:44 -0700 (PDT) Received: by mail-pl1-x62e.google.com with SMTP id d9443c01a7336-1c871a095ceso36652585ad.2 for ; Mon, 09 Oct 2023 16:29:44 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1696894183; x=1697498983; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=qVrLTp9UxQLsQ/wLqHYuTdmwNj7vaeKNZO1RAmb2cic=; b=HSevLFft6Yij3Gqod4o7sY5MjZiITLiLdgmk2zA/zdvhsoBoIbf0xr6QRU2QwWQlQk LZM3efPM3c05Zr8bAPDjNfRuA209XXz55yUso+OompFQzQ8Q05WxhFopBFmrhUJxcYlN bKOlBNL7Q9ZiADCMo7h8w++l5LYfH4kcQXEMAuvgXlKzjaUd5sN4sK8z9vq5tTNxyFjt DzmOJX1liagGwdBlRrY+722R+UL4TqENplsO0VO3Amqhp0ULNaTtuI/zlV6weXWHYj9X PeEC0mKaoQ9GKNZnLamBsjzVU97+/ZUEKiK0Kmer+s6cMeiAUkWZgF3VyOPIDVqOv2CY 5AhQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1696894183; x=1697498983; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=qVrLTp9UxQLsQ/wLqHYuTdmwNj7vaeKNZO1RAmb2cic=; b=wbO42rCnWu3LMturqYsXJ83ZQjmGxBZN1yD33EtkLqBD1h0RPvToap3zVgvkoikk+V DnHtWps2NlJU7D5V26xVDuNcD26+IX044Rh4w2Zj5vqVwRVdkjOV5cmHkGTlZj+eObpl t+nAr3vjRdHz3OI74Lm8Fl71SsJYWugoDq+OUV6W+NPuMmEp1b/9UrTU/SEszno2i1g9 YAMJL8WB160vKEymhrXpvAA4Ob5Hyjo1LZnia7bUGUd7rwNjHiwqG/WfHmyAeBOgSyxI 4vfj/V3fnujqiWl80ks2wSytScXc7Yq+vsYAUVeqAEMc8m3QPdiUtws0QNT0msbU40yk h/sQ== X-Gm-Message-State: AOJu0YxW37w5bYdFgC2KMFg7wFNLYY2H+Nh6p3lvFNg61uz2CuqOm3G1 3e4sQE8AY+jqOPKmAEIXNydamU8fzB9m+fj4 X-Google-Smtp-Source: AGHT+IEI/QCFA47MXBiltsrkAzBNPhqP33r1HRSp84Dw0yjPVgvU5wy9WmPj0lSbofow4TflRGavUg== X-Received: by 2002:a17:902:c947:b0:1c7:4a8a:32d1 with SMTP id i7-20020a170902c94700b001c74a8a32d1mr17033654pla.28.1696894182843; Mon, 09 Oct 2023 16:29:42 -0700 (PDT) Received: from lvondent-mobl4.. (c-98-232-221-87.hsd1.or.comcast.net. [98.232.221.87]) by smtp.gmail.com with ESMTPSA id s20-20020a170902989400b001c5b8087fe5sm10182711plp.94.2023.10.09.16.29.40 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 09 Oct 2023 16:29:40 -0700 (PDT) From: Luiz Augusto von Dentz To: linux-bluetooth@vger.kernel.org Subject: [PATCH v2 04/11] doc/profile-api: Rename to org.bluez.Profile{Manager}.rst Date: Mon, 9 Oct 2023 16:29:26 -0700 Message-ID: <20231009232933.500652-4-luiz.dentz@gmail.com> X-Mailer: git-send-email 2.41.0 In-Reply-To: <20231009232933.500652-1-luiz.dentz@gmail.com> References: <20231009232933.500652-1-luiz.dentz@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-bluetooth@vger.kernel.org From: Luiz Augusto von Dentz This renames profile-api.txt to org.bluez.Profile{Manager}.rst and generate manpages org.bluez.Profile{Manager}.5. --- Makefile.am | 10 +- doc/org.bluez.Profile.rst | 51 ++++++++++ doc/org.bluez.ProfileManager.rst | 141 +++++++++++++++++++++++++ doc/profile-api.txt | 170 ------------------------------- 4 files changed, 198 insertions(+), 174 deletions(-) create mode 100644 doc/org.bluez.Profile.rst create mode 100644 doc/org.bluez.ProfileManager.rst delete mode 100644 doc/profile-api.txt diff --git a/Makefile.am b/Makefile.am index b25bc521cab3..64004004fb2a 100644 --- a/Makefile.am +++ b/Makefile.am @@ -359,7 +359,8 @@ if MANPAGES man_MANS += src/bluetoothd.8 man_MANS += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \ doc/org.bluez.DeviceSet.5 doc/org.bluez.AgentManager.5 \ - doc/org.bluez.Agent.5 + doc/org.bluez.Agent.5 doc/org.bluez.ProfileManager.5 \ + doc/org.bluez.Profile.5 man_MANS += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \ doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \ doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \ @@ -368,7 +369,8 @@ endif manual_pages += src/bluetoothd.8 manual_pages += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \ doc/org.bluez.DeviceSet.5 doc/org.bluez.AgentManager.5 \ - doc/org.bluez.Agent.5 + doc/org.bluez.Agent.5 doc/org.bluez.ProfileManager.5 \ + doc/org.bluez.Profile.5 manual_pages += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \ doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \ doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \ @@ -409,13 +411,13 @@ EXTRA_DIST += doc/assigned-numbers.txt doc/supported-features.txt \ doc/settings-storage.txt EXTRA_DIST += doc/mgmt-api.txt \ - doc/profile-api.txt \ doc/network-api.txt doc/health-api.txt \ doc/sap-api.txt doc/input-api.txt EXTRA_DIST += doc/org.bluez.Adapter.rst doc/org.bluez.Device.rst \ doc/org.bluez.DeviceSet.rst doc/org.bluez.AgentManager.rst \ - doc/org.bluez.Agent.rst + doc/org.bluez.Agent.rst doc/org.bluez.ProfileManager.rst \ + doc/org.bluez.Profile.rst EXTRA_DIST += doc/org.bluez.Media.rst doc/org.bluez.MediaControl.rst \ doc/org.bluez.MediaPlayer.rst doc/org.bluez.MediaFolder.rst \ diff --git a/doc/org.bluez.Profile.rst b/doc/org.bluez.Profile.rst new file mode 100644 index 000000000000..d8ae669c7323 --- /dev/null +++ b/doc/org.bluez.Profile.rst @@ -0,0 +1,51 @@ +================= +org.bluez.Profile +================= + +------------------------------------- +BlueZ D-Bus Profile API documentation +------------------------------------- + +:Version: BlueZ +:Date: October 2023 +:Manual section: 5 +:Manual group: Linux System Administration + +Interface +========= + +:Service: unique name +:Interface: org.bluez.Profile1 +:Object path: freely definable + +Methods +------- + +void Release() [noreply] +```````````````````````` + + This method gets called when the service daemon unregisters the profile. + A profile can use it to do cleanup tasks. There is no need to unregister + the profile, because when this method gets called it has already been + unregistered. + +void NewConnection(object device, fd, dict fd_properties) +````````````````````````````````````````````````````````` + + This method gets called when a new service level connection has been + made and authorized. + + Possible fd_properties values: + + :uint16 Version [optional]: + + Profile version. + + :uint16 Features [optional]: + + Profile features. + + Possible errors: + + :org.bluez.Error.Rejected: + :org.bluez.Error.Canceled: diff --git a/doc/org.bluez.ProfileManager.rst b/doc/org.bluez.ProfileManager.rst new file mode 100644 index 000000000000..ccd7a2673d77 --- /dev/null +++ b/doc/org.bluez.ProfileManager.rst @@ -0,0 +1,141 @@ +======================== +org.bluez.ProfileManager +======================== + +-------------------------------------------- +BlueZ D-Bus ProfileManager API documentation +-------------------------------------------- + +:Version: BlueZ +:Date: October 2023 +:Manual section: 5 +:Manual group: Linux System Administration + +Interface +========= + +:Service: org.bluez +:Interface: org.bluez.ProfileManager1 +:Object path: /org/bluez + +Methods +------- + +void RegisterProfile(object profile, string uuid, dict options) +``````````````````````````````````````````````````````````````` + + Registers profile agent. + + The object path defines the path of the profile that will be called + when there is a connection and must implement **org.bluez.Profile(5)** + interface. + + If an application disconnects from the bus all its registered profiles + will be removed. + + Possible uuid values: + + :"0000111f-0000-1000-8000-00805f9b34fb": + + HFP AG, default profile Version is 1.7, profile Features is + 0b001001 and RFCOMM channel is 13. Authentication is required. + + :"0000111e-0000-1000-8000-00805f9b34fb": + + HFP HS, default profile Version is 1.7, profile Features is + 0b000000 and RFCOMM channel is 7. Authentication is required. + + :"00001112-0000-1000-8000-00805f9b34fb": + + HSP AG, default profile Version is 1.2, RFCOMM channel is 12 and + Authentication is required. Does not support any Features, + option is ignored. + + :"00001108-0000-1000-8000-00805f9b34fb": + + HSP HS, default profile Version is 1.2, profile Features is 0b0 + and RFCOMM channel is 6. Authentication is required. + Features is one bit value, specify capability of Remote Audio + Volume Control (by default turned off). + + :"": + + Vendor defined UUID, no defaults, must set options. + + Possible options values: + + :string Name: + + Human readable name for the profile + + :string Service: + + The primary service class UUID (if different from the actual + profile UUID). + + :string Role: + + For asymmetric profiles that do not have UUIDs available to + uniquely identify each side this parameter allows specifying the + precise local role. + + Possible values: + + :"client": + :"server": + + :uint16 Channel: + + RFCOMM channel number that is used for client and server UUIDs. + + If applicable it will be used in the SDP record as well. + + :uint16 PSM: + + PSM number that is used for client and server UUIDs. + + If applicable it will be used in the SDP record as well. + + :boolean RequireAuthentication: + + Pairing is required before connections will be established. + No devices will be connected if not paired. + + :boolean RequireAuthorization: + + Request authorization before any connection will be established. + + :boolean AutoConnect: + + In case of a client UUID this will force connection of the + RFCOMM or L2CAP channels when a remote device is connected. + + :string ServiceRecord: + + Provide a manual SDP record. + + :uint16 Version: + + Profile version (for SDP record) + + :uint16 Features: + + Profile features (for SDP record) + + Possible errors: + + :org.bluez.Error.InvalidArguments: + :org.bluez.Error.AlreadyExists: + +void UnregisterProfile(object profile) +`````````````````````````````````````` + + Unregisters profile object that has been previously registered using + **RegisterProfile**. + + The object path parameter must match the same value that has been used + on registration. + + Possible errors: + + :org.bluez.Error.DoesNotExist: diff --git a/doc/profile-api.txt b/doc/profile-api.txt deleted file mode 100644 index 183c6c11a7ba..000000000000 --- a/doc/profile-api.txt +++ /dev/null @@ -1,170 +0,0 @@ -BlueZ D-Bus Profile API description -*********************************** - - -Profile Manager hierarchy -========================= - -Service org.bluez -Interface org.bluez.ProfileManager1 -Object path /org/bluez - - void RegisterProfile(object profile, string uuid, dict options) - - This registers a profile implementation. - - If an application disconnects from the bus all - its registered profiles will be removed. - - Some predefined services: - - HFP AG UUID: 0000111f-0000-1000-8000-00805f9b34fb - - Default profile Version is 1.7, profile Features - is 0b001001 and RFCOMM channel is 13. - Authentication is required. - - HFP HS UUID: 0000111e-0000-1000-8000-00805f9b34fb - - Default profile Version is 1.7, profile Features - is 0b000000 and RFCOMM channel is 7. - Authentication is required. - - HSP AG UUID: 00001112-0000-1000-8000-00805f9b34fb - - Default profile Version is 1.2, RFCOMM channel - is 12 and Authentication is required. Does not - support any Features, option is ignored. - - HSP HS UUID: 00001108-0000-1000-8000-00805f9b34fb - - Default profile Version is 1.2, profile Features - is 0b0 and RFCOMM channel is 6. Authentication - is required. Features is one bit value, specify - capability of Remote Audio Volume Control - (by default turned off). - - Available options: - - string Name - - Human readable name for the profile - - string Service - - The primary service class UUID - (if different from the actual - profile UUID) - - string Role - - For asymmetric profiles that do not - have UUIDs available to uniquely - identify each side this - parameter allows specifying the - precise local role. - - Possible values: "client", "server" - - uint16 Channel - - RFCOMM channel number that is used - for client and server UUIDs. - - If applicable it will be used in the - SDP record as well. - - uint16 PSM - - PSM number that is used for client - and server UUIDs. - - If applicable it will be used in the - SDP record as well. - - boolean RequireAuthentication - - Pairing is required before connections - will be established. No devices will - be connected if not paired. - - boolean RequireAuthorization - - Request authorization before any - connection will be established. - - boolean AutoConnect - - In case of a client UUID this will - force connection of the RFCOMM or - L2CAP channels when a remote device - is connected. - - string ServiceRecord - - Provide a manual SDP record. - - uint16 Version - - Profile version (for SDP record) - - uint16 Features - - Profile features (for SDP record) - - Possible errors: org.bluez.Error.InvalidArguments - org.bluez.Error.AlreadyExists - - void UnregisterProfile(object profile) - - This unregisters the profile that has been previously - registered. The object path parameter must match the - same value that has been used on registration. - - Possible errors: org.bluez.Error.DoesNotExist - - -Profile hierarchy -================= - -Service unique name -Interface org.bluez.Profile1 -Object path freely definable - -Methods void Release() [noreply] - - This method gets called when the service daemon - unregisters the profile. A profile can use it to do - cleanup tasks. There is no need to unregister the - profile, because when this method gets called it has - already been unregistered. - - void NewConnection(object device, fd, dict fd_properties) - - This method gets called when a new service level - connection has been made and authorized. - - Common fd_properties: - - uint16 Version Profile version (optional) - uint16 Features Profile features (optional) - - Possible errors: org.bluez.Error.Rejected - org.bluez.Error.Canceled - - void RequestDisconnection(object device) - - This method gets called when a profile gets - disconnected. - - The file descriptor is no longer owned by the service - daemon and the profile implementation needs to take - care of cleaning up all connections. - - If multiple file descriptors are indicated via - NewConnection, it is expected that all of them - are disconnected before returning from this - method call. - - Possible errors: org.bluez.Error.Rejected - org.bluez.Error.Canceled From patchwork Mon Oct 9 23:29:27 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luiz Augusto von Dentz X-Patchwork-Id: 13414678 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 942EAE9413E for ; Mon, 9 Oct 2023 23:29:48 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1379100AbjJIX3s (ORCPT ); Mon, 9 Oct 2023 19:29:48 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:58930 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1379086AbjJIX3r (ORCPT ); Mon, 9 Oct 2023 19:29:47 -0400 Received: from mail-pl1-x631.google.com (mail-pl1-x631.google.com [IPv6:2607:f8b0:4864:20::631]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 812E9A4 for ; Mon, 9 Oct 2023 16:29:45 -0700 (PDT) Received: by mail-pl1-x631.google.com with SMTP id d9443c01a7336-1c5c91bece9so36662345ad.3 for ; Mon, 09 Oct 2023 16:29:45 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1696894184; x=1697498984; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=PRxH1waw56FtswklNdEvqOLXLAlzGTnUWqOZjyGi8FQ=; b=FF4UAv/iIEGvjRglvLIxj41v2FGTT6kjAHNZGzu2dpk32YKjWYoep5sxfw9uxzgszB HCtnR/CYBCcbSdgouZ9qzSqT4d7KP86SlOlR2KrEice4/hh6oDwSoq9gaCp39gJC8z+U tGmkchge6EN0dw6VmCh73fY+UwdUGuZWjnPJdk3PSiKfVwBmZkdIaUjqP8gNS1XfSuEB WSxkv9rlk+OP5Fb3r47ZXJHW1wP07coOW4UkH5VgjNhkfnXn6sNeV0bnvbAbl86m1ISp usajzbdDeYxaWvw1svR216bkFfoI54vIG0SVnu7BbfRa6slzP1gyXYDQQnamCDxqWp3j 5ozA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1696894184; x=1697498984; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=PRxH1waw56FtswklNdEvqOLXLAlzGTnUWqOZjyGi8FQ=; b=A5FCshoeKG5zS4XbXV47VGf8+0E7T7zB11dPZ6Mnrjc420NpL2OjdvJbS/EPVChBpm gzcBVTEc4hl+eAPvZ85cuKFGh5Z8q0CljVpZfo10+g7CnFeUIjoYFPU+4EqBUZ4iX5fm rQjd/hdzLMTXVjuDs1wbaMMzGosbNoK5NVbHOaEq/LrbH/X8choVV6nxz2lh3s8SRmwq i+05rDfltY/RSkaJE+zBljInghWnleOTZ0LdIubAWFziDVC1SR90l8UYrkrHOIvXUBG4 mzyztEAxlnk9QQ5rrCwwZRo+a89hTGBlG7zVUY4qETbCh5hhUQCO4WiKloWKtrcCRXud glkQ== X-Gm-Message-State: AOJu0YzhSEsDd8uS+Yyt1rWiznzK2cGyvdROznJsf57JNbT4od6st2OL HS6m/VF9IsepWaW5wf9sZVqBO13mASjEiMO6 X-Google-Smtp-Source: AGHT+IHh6AdiCDfaUAIxjmwB0NSf2WT9WurmsMJL5sszKqlDXgx+aUDttP9oZ1nWeNw/npS/crZybA== X-Received: by 2002:a17:902:cecb:b0:1c3:411c:9b7d with SMTP id d11-20020a170902cecb00b001c3411c9b7dmr16904986plg.57.1696894184175; Mon, 09 Oct 2023 16:29:44 -0700 (PDT) Received: from lvondent-mobl4.. (c-98-232-221-87.hsd1.or.comcast.net. [98.232.221.87]) by smtp.gmail.com with ESMTPSA id s20-20020a170902989400b001c5b8087fe5sm10182711plp.94.2023.10.09.16.29.43 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 09 Oct 2023 16:29:43 -0700 (PDT) From: Luiz Augusto von Dentz To: linux-bluetooth@vger.kernel.org Subject: [PATCH v2 05/11] doc/network-api: Rename to org.bluez.Network{Server}.rst Date: Mon, 9 Oct 2023 16:29:27 -0700 Message-ID: <20231009232933.500652-5-luiz.dentz@gmail.com> X-Mailer: git-send-email 2.41.0 In-Reply-To: <20231009232933.500652-1-luiz.dentz@gmail.com> References: <20231009232933.500652-1-luiz.dentz@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-bluetooth@vger.kernel.org From: Luiz Augusto von Dentz This renames network-api.txt to org.bluez.Network{Server}.rst and generate manpages org.bluez.Network{Server}.5. --- Makefile.am | 11 +++-- doc/network-api.txt | 76 ------------------------------ doc/org.bluez.Network.rst | 83 +++++++++++++++++++++++++++++++++ doc/org.bluez.NetworkServer.rst | 68 +++++++++++++++++++++++++++ 4 files changed, 158 insertions(+), 80 deletions(-) delete mode 100644 doc/network-api.txt create mode 100644 doc/org.bluez.Network.rst create mode 100644 doc/org.bluez.NetworkServer.rst diff --git a/Makefile.am b/Makefile.am index 64004004fb2a..797dc6b78fa5 100644 --- a/Makefile.am +++ b/Makefile.am @@ -360,7 +360,8 @@ man_MANS += src/bluetoothd.8 man_MANS += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \ doc/org.bluez.DeviceSet.5 doc/org.bluez.AgentManager.5 \ doc/org.bluez.Agent.5 doc/org.bluez.ProfileManager.5 \ - doc/org.bluez.Profile.5 + doc/org.bluez.Profile.5 doc/org.bluez.NetworkServer.5 \ + doc/org.bluez.Network.5 man_MANS += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \ doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \ doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \ @@ -370,7 +371,8 @@ manual_pages += src/bluetoothd.8 manual_pages += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \ doc/org.bluez.DeviceSet.5 doc/org.bluez.AgentManager.5 \ doc/org.bluez.Agent.5 doc/org.bluez.ProfileManager.5 \ - doc/org.bluez.Profile.5 + doc/org.bluez.Profile.5 doc/org.bluez.NetworkServer.5 \ + doc/org.bluez.Network.5 manual_pages += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \ doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \ doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \ @@ -411,13 +413,14 @@ EXTRA_DIST += doc/assigned-numbers.txt doc/supported-features.txt \ doc/settings-storage.txt EXTRA_DIST += doc/mgmt-api.txt \ - doc/network-api.txt doc/health-api.txt \ + doc/health-api.txt \ doc/sap-api.txt doc/input-api.txt EXTRA_DIST += doc/org.bluez.Adapter.rst doc/org.bluez.Device.rst \ doc/org.bluez.DeviceSet.rst doc/org.bluez.AgentManager.rst \ doc/org.bluez.Agent.rst doc/org.bluez.ProfileManager.rst \ - doc/org.bluez.Profile.rst + doc/org.bluez.Profile.rst doc/org.bluez.NetworkServer.rst \ + doc/org.bluez.Network.rst EXTRA_DIST += doc/org.bluez.Media.rst doc/org.bluez.MediaControl.rst \ doc/org.bluez.MediaPlayer.rst doc/org.bluez.MediaFolder.rst \ diff --git a/doc/network-api.txt b/doc/network-api.txt deleted file mode 100644 index 109da28bf10d..000000000000 --- a/doc/network-api.txt +++ /dev/null @@ -1,76 +0,0 @@ -BlueZ D-Bus Network API description -*********************************** - - -Network hierarchy -================= - -Service org.bluez -Interface org.bluez.Network1 -Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX - -Methods string Connect(string uuid) - - Connect to the network device and return the network - interface name. Examples of the interface name are - bnep0, bnep1 etc. - - uuid can be either one of "gn", "panu" or "nap" (case - insensitive) or a traditional string representation of - UUID or a hexadecimal number. - - The connection will be closed and network device - released either upon calling Disconnect() or when - the client disappears from the message bus. - - Possible errors: org.bluez.Error.AlreadyConnected - org.bluez.Error.ConnectionAttemptFailed - - void Disconnect() - - Disconnect from the network device. - - To abort a connection attempt in case of errors or - timeouts in the client it is fine to call this method. - - Possible errors: org.bluez.Error.Failed - -Properties boolean Connected [readonly] - - Indicates if the device is connected. - - string Interface [readonly] - - Indicates the network interface name when available. - - string UUID [readonly] - - Indicates the connection role when available. - - -Network server hierarchy -======================== - -Service org.bluez -Interface org.bluez.NetworkServer1 -Object path /org/bluez/{hci0,hci1,...} - -Methods void Register(string uuid, string bridge) - - Register server for the provided UUID. Every new - connection to this server will be added the bridge - interface. - - Valid UUIDs are "gn", "panu" or "nap". - - Initially no network server SDP is provided. Only - after this method a SDP record will be available - and the BNEP server will be ready for incoming - connections. - - void Unregister(string uuid) - - Unregister the server for provided UUID. - - All servers will be automatically unregistered when - the calling application terminates. diff --git a/doc/org.bluez.Network.rst b/doc/org.bluez.Network.rst new file mode 100644 index 000000000000..d81a69d3c8af --- /dev/null +++ b/doc/org.bluez.Network.rst @@ -0,0 +1,83 @@ +================= +org.bluez.Network +================= + +------------------------------------- +BlueZ D-Bus Network API documentation +------------------------------------- + +:Version: BlueZ +:Date: October 2023 +:Manual section: 5 +:Manual group: Linux System Administration + +Interface +========= + +:Service: org.bluez +:Interface: org.bluez.Network1 +:Object path: [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX + +Methods +------- + +string Connect(string uuid) +``````````````````````````` + + Connects to the network device and return the network interface name. + + Possible uuid values: + + :"panu", "00001115-0000-1000-8000-00805f9b34fb": + + Personal Network User role. + + :"nap", "00001116-0000-1000-8000-00805f9b34fb": + + Network Access Point role. + + :"gn", "00001117-0000-1000-8000-00805f9b34fb": + + Group Network role. + + The connection will be closed and network device released either upon + calling **Disconnect()** or when the client disappears from the + message bus. + + Possible errors: + + :org.bluez.Error.InvalidArguments: + :org.bluez.Error.NotSupported: + :org.bluez.Error.InProgress: + :org.bluez.Error.Failed: + +void Disconnect() +````````````````` + + Disconnects from the network device. + + To abort a connection attempt in case of errors or timeouts in the + client it is fine to call this method. + + Possible errors: + + :org.bluez.Error.Failed: + :org.bluez.Error.NotConnected: + +Properties +---------- + +boolean Connected [readonly] +```````````````````````````` + + Indicates if the device is connected. + +string Interface [readonly, optional] +````````````````````````````````````` + + Indicates the network interface name when available. + +string UUID [readonly, optional] +```````````````````````````````` + + Indicates the connection role when available. diff --git a/doc/org.bluez.NetworkServer.rst b/doc/org.bluez.NetworkServer.rst new file mode 100644 index 000000000000..d15d223c5eca --- /dev/null +++ b/doc/org.bluez.NetworkServer.rst @@ -0,0 +1,68 @@ +======================= +org.bluez.NetworkServer +======================= + +------------------------------------------- +BlueZ D-Bus NetworkServer API documentation +------------------------------------------- + +:Version: BlueZ +:Date: October 2023 +:Manual section: 5 +:Manual group: Linux System Administration + +Interface +========= + +:Service: org.bluez +:Interface: org.bluez.NetworkServer1 +:Object path: /org/bluez/{hci0,hci1,...} + + +Methods +------- + +void Register(string uuid, string bridge) +````````````````````````````````````````` + + Registers server for the provided UUID. + + Every new connection to this server will be added the bridge interface. + + Possible uuid values: + + :"panu", "00001115-0000-1000-8000-00805f9b34fb": + + Personal Network User role. + + :"nap", "00001116-0000-1000-8000-00805f9b34fb": + + Network Access Point role. + + :"gn", "00001117-0000-1000-8000-00805f9b34fb": + + Group Network role. + + Initially no network server SDP is provided. Only after this method a + SDP record will be available and the BNEP server will be ready for + incoming connections. + + Possible errors: + + :org.bluez.Error.InvalidArguments: + :org.bluez.Error.AlreadyExists: + :org.bluez.Error.Failed: + +void Unregister(string uuid) +```````````````````````````` + + Unregisters the server for provided UUID which was previously + registered with **Register()** method. + + All servers will be automatically unregistered when the calling + application terminates. + + Possible errors: + + :org.bluez.Error.InvalidArguments: + :org.bluez.Error.Failed: From patchwork Mon Oct 9 23:29:28 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luiz Augusto von Dentz X-Patchwork-Id: 13414679 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 88CC2E9371F for ; Mon, 9 Oct 2023 23:29:50 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1379104AbjJIX3u (ORCPT ); Mon, 9 Oct 2023 19:29:50 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:58958 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1379101AbjJIX3t (ORCPT ); Mon, 9 Oct 2023 19:29:49 -0400 Received: from mail-pl1-x629.google.com (mail-pl1-x629.google.com [IPv6:2607:f8b0:4864:20::629]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id B2366A4 for ; Mon, 9 Oct 2023 16:29:47 -0700 (PDT) Received: by mail-pl1-x629.google.com with SMTP id d9443c01a7336-1c63164a2b6so44790065ad.0 for ; Mon, 09 Oct 2023 16:29:47 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1696894186; x=1697498986; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=38cuLNQBXrWB5OzgDJk9XBNGuRqGtwf007h1s4UEi60=; b=c8hDCF+VU48F+zAibNpqzp6Zxs+Nz9cNn4uEJcWyPCPqb7WSljjHIMAyanHmjuz0gj Mk4hKo7lMB+SqCBVr13rMr2gbqhPUV5EYxHJg7U4iCEy5RVmLj74WjDPKCVMv9Wp/hu0 U/9VbeayouGnmRYWOAxqmlXGdh8JZf0c2P6tX4PCjpMKKcgNmnLTtsDrkohmJ82wmncK JopRdqDhcijbIZdfkcfmLeH0EZBmV6+d1PF80eN40ZPOkBHVbTDO5vLOnEPB8xGJOgCT POyTS1tpygSP2iOSFE7sCBDUj0C/WQBps56EnyNc5/YtWJ6kjVvnNN8owMrMd0COf4Rx CTpw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1696894186; x=1697498986; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=38cuLNQBXrWB5OzgDJk9XBNGuRqGtwf007h1s4UEi60=; b=qYnQq9iffylnaHzSTOE0PUQeX1zEgE1bOs1LyWXnNHsYnf7g/XCOHsekVVVgmfxtbW SMtr2ka1NMQghLhW3Tko9doxcwlksJvFUi+b3uenCaVpr1H98eCNQJxztuQwMU272htW Uw2uSCNKBjNBtqmLAgMC1d+1s7QaKkAapO8uk7K+0r+IuA5rE+OrDK784RA++kQDjI2x 0YlZaBOZL2J12QB120WEWtlsQ/kZJuTdSpXsZuTA024OXvz+tcF2wngTrsBmF8O12snc dPindPHgXslergMmsao2DRKcoaFe2lUjoS7/uhLg8I9lXFSZPjJYOE6HxCNmiYUDA4pa S4mQ== X-Gm-Message-State: AOJu0YyCyfwDQK5ZfWOPT1S8vuOJGXw8gLMTEALnIW43Kn+rAsrWA5ns 5e+/r95S1w44jXoB9nUUhMz4DgKi0D+ND/nt X-Google-Smtp-Source: AGHT+IFHVJjUJrbPBnaD2z5tiOYCZeoKlS/Iypwi7G588yNdIvTtaOd1+YjnASdxCvfgY1Viu3JTjA== X-Received: by 2002:a17:902:e5c1:b0:1c6:23fd:fb18 with SMTP id u1-20020a170902e5c100b001c623fdfb18mr18776276plf.0.1696894186294; Mon, 09 Oct 2023 16:29:46 -0700 (PDT) Received: from lvondent-mobl4.. (c-98-232-221-87.hsd1.or.comcast.net. [98.232.221.87]) by smtp.gmail.com with ESMTPSA id s20-20020a170902989400b001c5b8087fe5sm10182711plp.94.2023.10.09.16.29.44 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 09 Oct 2023 16:29:44 -0700 (PDT) From: Luiz Augusto von Dentz To: linux-bluetooth@vger.kernel.org Subject: [PATCH v2 06/11] doc/input-api: Rename to org.bluez.Input.rst Date: Mon, 9 Oct 2023 16:29:28 -0700 Message-ID: <20231009232933.500652-6-luiz.dentz@gmail.com> X-Mailer: git-send-email 2.41.0 In-Reply-To: <20231009232933.500652-1-luiz.dentz@gmail.com> References: <20231009232933.500652-1-luiz.dentz@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-bluetooth@vger.kernel.org From: Luiz Augusto von Dentz This renames input-api.txt to org.bluez.Input.rst and generate manpages org.bluez.Input.5. --- Makefile.am | 8 +++---- doc/input-api.txt | 32 -------------------------- doc/org.bluez.Input.rst | 51 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 55 insertions(+), 36 deletions(-) delete mode 100644 doc/input-api.txt create mode 100644 doc/org.bluez.Input.rst diff --git a/Makefile.am b/Makefile.am index 797dc6b78fa5..f717d2c2336b 100644 --- a/Makefile.am +++ b/Makefile.am @@ -361,7 +361,7 @@ man_MANS += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \ doc/org.bluez.DeviceSet.5 doc/org.bluez.AgentManager.5 \ doc/org.bluez.Agent.5 doc/org.bluez.ProfileManager.5 \ doc/org.bluez.Profile.5 doc/org.bluez.NetworkServer.5 \ - doc/org.bluez.Network.5 + doc/org.bluez.Network.5 doc/org.bluez.Input.5 man_MANS += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \ doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \ doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \ @@ -372,7 +372,7 @@ manual_pages += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \ doc/org.bluez.DeviceSet.5 doc/org.bluez.AgentManager.5 \ doc/org.bluez.Agent.5 doc/org.bluez.ProfileManager.5 \ doc/org.bluez.Profile.5 doc/org.bluez.NetworkServer.5 \ - doc/org.bluez.Network.5 + doc/org.bluez.Network.5 doc/org.bluez.Input.5 manual_pages += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \ doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \ doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \ @@ -414,13 +414,13 @@ EXTRA_DIST += doc/assigned-numbers.txt doc/supported-features.txt \ EXTRA_DIST += doc/mgmt-api.txt \ doc/health-api.txt \ - doc/sap-api.txt doc/input-api.txt + doc/sap-api.txt EXTRA_DIST += doc/org.bluez.Adapter.rst doc/org.bluez.Device.rst \ doc/org.bluez.DeviceSet.rst doc/org.bluez.AgentManager.rst \ doc/org.bluez.Agent.rst doc/org.bluez.ProfileManager.rst \ doc/org.bluez.Profile.rst doc/org.bluez.NetworkServer.rst \ - doc/org.bluez.Network.rst + doc/org.bluez.Network.rst doc/org.bluez.Input.rst EXTRA_DIST += doc/org.bluez.Media.rst doc/org.bluez.MediaControl.rst \ doc/org.bluez.MediaPlayer.rst doc/org.bluez.MediaFolder.rst \ diff --git a/doc/input-api.txt b/doc/input-api.txt deleted file mode 100644 index 67da08b102c9..000000000000 --- a/doc/input-api.txt +++ /dev/null @@ -1,32 +0,0 @@ -BlueZ D-Bus Input API description -********************************* - -Input hierarchy -=============== - -Service org.bluez -Interface org.bluez.Input1 -Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX - -Properties string ReconnectMode [readonly] - - Determines the Connectability mode of the HID device as - defined by the HID Profile specification, Section 5.4.2. - - This mode is based in the two properties - HIDReconnectInitiate (see Section 5.3.4.6) and - HIDNormallyConnectable (see Section 5.3.4.14) which - define the following four possible values: - - "none" Device and host are not required to - automatically restore the connection. - - "host" Bluetooth HID host restores connection. - - "device" Bluetooth HID device restores - connection. - - "any" Bluetooth HID device shall attempt to - restore the lost connection, but - Bluetooth HID Host may also restore the - connection. diff --git a/doc/org.bluez.Input.rst b/doc/org.bluez.Input.rst new file mode 100644 index 000000000000..c3c223c913d8 --- /dev/null +++ b/doc/org.bluez.Input.rst @@ -0,0 +1,51 @@ +=============== +org.bluez.Input +=============== + +----------------------------------- +BlueZ D-Bus Input API documentation +----------------------------------- + +:Version: BlueZ +:Date: October 2023 +:Manual section: 5 +:Manual group: Linux System Administration + +Interface +========= + +:Service: org.bluez +:Interface: org.bluez.Input1 +:Object path: [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX + +Properties +---------- + +string ReconnectMode [readonly] +``````````````````````````````` + + Indicates the Connectability mode of the HID device as defined by the + HID Profile specification, Section 5.4.2. + + This mode is based in the two properties HIDReconnectInitiate (see + Section 5.3.4.6) and HIDNormallyConnectable (see Section 5.3.4.14) which + define the following four possible values: + + :"none": + + Device and host are not required to automatically restore the + connection. + + :"host": + + Bluetooth HID host restores connection. + + :"device": + + Bluetooth HID device restores connection. + + :"any": + + Bluetooth HID device shall attempt to restore the lost + connection, but Bluetooth HID Host may also restore the + connection. From patchwork Mon Oct 9 23:29:29 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luiz Augusto von Dentz X-Patchwork-Id: 13414681 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id BB5CDE9371F for ; Mon, 9 Oct 2023 23:30:00 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1379101AbjJIXaA (ORCPT ); Mon, 9 Oct 2023 19:30:00 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:59008 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1379105AbjJIX35 (ORCPT ); Mon, 9 Oct 2023 19:29:57 -0400 Received: from mail-pl1-x630.google.com (mail-pl1-x630.google.com [IPv6:2607:f8b0:4864:20::630]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 5821EA4 for ; Mon, 9 Oct 2023 16:29:50 -0700 (PDT) Received: by mail-pl1-x630.google.com with SMTP id d9443c01a7336-1c8a1541233so12601785ad.1 for ; Mon, 09 Oct 2023 16:29:50 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1696894188; x=1697498988; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=gkPh2UbzNSyJBColBTH9IoJdkJTLS0KGu6b2bTjbbRM=; b=Cslg2cyr6+IsqCZTyGhxOqi5bymawJmNIkPB83AmecU8QDSfoCZia21t0oUBc4O0Xh b3+YRWjF/MX+0LLW9GaDXt5OSmwNhv6T49sRTenrZPzydwhYP+J6XHN+RHpHjEVYr9hI xghgqs8b0YZOhKRlVwV5XB05ZMynaw/5T786ST/0+dYVS5i4Li61ecTZoHO+64T3xtmt sNMgkI02jEKTfsVTxjMhMWk5qajNECAtNSSmcVcNMgY/0/WPCOw0l8hj6h+qeXe+/UjY x5YkCmu6PwgPTcqK0898EEHwKCK5viZYYLs5X2LNZtHsiDlybkiapxluw0h1c1BhIuPv EdOQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1696894188; x=1697498988; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=gkPh2UbzNSyJBColBTH9IoJdkJTLS0KGu6b2bTjbbRM=; b=cPDRM34mM0wn32xHrcARtE1QKr+kVE3BTMOiUMe61plSFGmples02mwFfF4cTyim+i KPFn0effwXWotnnPZr/2pssOSEK/PHSxioB39kn0/FqAe8E7HLYfLoKvkrNZqJEk5w46 +zEAss8pn6TnkHT6Ee1mUACOTGV44JywvgKC5b67aAfPmQii/0gqoGmqF9CnvssWTr8H G+qofAHRJg0GFF6p5RvEYYGcabfxSbzNMeQm2C12dGG+xFeX0FjEsVx4mjdwH7WeIhwO FdjhyLJc6jiTABLdjj3Uc3bKFcnemmurLtHL2LRCnZNewcatDY9WghDQaZ4XezgaGl0A z5Yg== X-Gm-Message-State: AOJu0YxpLG20mZbaY4tR6KVC6/JhJ1qZjf3eHVxsyjuVJ5WqqyE2oSKP zUj0MRzAQOUBpm9L2ynPuNzViNV8JekQQ/14 X-Google-Smtp-Source: AGHT+IFBFR1TNzLsZ4vLwV3IhaBxE99wWK8ESq3oyenuNRkKNqCs/tWgam8ejuw8kjM4Hyo/oryb2A== X-Received: by 2002:a17:902:e550:b0:1b9:e937:9763 with SMTP id n16-20020a170902e55000b001b9e9379763mr16646835plf.12.1696894188132; Mon, 09 Oct 2023 16:29:48 -0700 (PDT) Received: from lvondent-mobl4.. (c-98-232-221-87.hsd1.or.comcast.net. [98.232.221.87]) by smtp.gmail.com with ESMTPSA id s20-20020a170902989400b001c5b8087fe5sm10182711plp.94.2023.10.09.16.29.46 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 09 Oct 2023 16:29:47 -0700 (PDT) From: Luiz Augusto von Dentz To: linux-bluetooth@vger.kernel.org Subject: [PATCH v2 07/11] doc/advertising-api: Rename to org.bluez.LEAdvertis*.rst Date: Mon, 9 Oct 2023 16:29:29 -0700 Message-ID: <20231009232933.500652-7-luiz.dentz@gmail.com> X-Mailer: git-send-email 2.41.0 In-Reply-To: <20231009232933.500652-1-luiz.dentz@gmail.com> References: <20231009232933.500652-1-luiz.dentz@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-bluetooth@vger.kernel.org From: Luiz Augusto von Dentz This renames advertising-api.txt to org.bluez.LEAdvertis*.rst and generate manpages org.bluez.LEAdvertis*.5. --- Makefile.am | 7 +- doc/advertising-api.txt | 278 ------------------------- doc/org.bluez.LEAdvertisement.rst | 195 +++++++++++++++++ doc/org.bluez.LEAdvertisingManager.rst | 144 +++++++++++++ 4 files changed, 345 insertions(+), 279 deletions(-) delete mode 100644 doc/advertising-api.txt create mode 100644 doc/org.bluez.LEAdvertisement.rst create mode 100644 doc/org.bluez.LEAdvertisingManager.rst diff --git a/Makefile.am b/Makefile.am index f717d2c2336b..cf72a7905274 100644 --- a/Makefile.am +++ b/Makefile.am @@ -366,6 +366,8 @@ man_MANS += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \ doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \ doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \ doc/org.bluez.MediaTransport.5 +man_MANS += doc/org.bluez.LEAdvertisingManager.5 \ + doc/org.bluez.LEAdvertisement.5 endif manual_pages += src/bluetoothd.8 manual_pages += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \ @@ -377,6 +379,8 @@ manual_pages += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \ doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \ doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \ doc/org.bluez.MediaTransport.5 +manual_pages += doc/org.bluez.LEAdvertisingManager.5 \ + doc/org.bluez.LEAdvertisement.5 EXTRA_DIST += src/genbuiltin src/bluetooth.conf \ src/main.conf profiles/network/network.conf \ @@ -427,7 +431,8 @@ EXTRA_DIST += doc/org.bluez.Media.rst doc/org.bluez.MediaControl.rst \ doc/org.bluez.MediaItem.rst doc/org.bluez.MediaEndpoint.rst \ doc/org.bluez.MediaTransport.rst -EXTRA_DIST += doc/gatt-api.txt doc/advertising-api.txt +EXTRA_DIST += doc/gatt-api.txt doc/org.bluez.LEAdvertisingManager.rst \ + doc/org.bluez.LEAdvertisement.rst EXTRA_DIST += doc/obex-api.txt doc/obex-agent-api.txt diff --git a/doc/advertising-api.txt b/doc/advertising-api.txt deleted file mode 100644 index a0077843defd..000000000000 --- a/doc/advertising-api.txt +++ /dev/null @@ -1,278 +0,0 @@ -BlueZ D-Bus LE Advertising API Description -****************************************** - -Advertising packets are structured data which is broadcast on the LE Advertising -channels and available for all devices in range. Because of the limited space -available in LE Advertising packets (31 bytes), each packet's contents must be -carefully controlled. - -BlueZ acts as a store for the Advertisement Data which is meant to be sent. -It constructs the correct Advertisement Data from the structured -data and configured the kernel to send the correct advertisement. - -Advertisement Data objects are registered freely and then referenced by BlueZ -when constructing the data sent to the kernel. - -LE Advertisement Data hierarchy -=============================== - -Specifies the Advertisement Data to be broadcast and some advertising -parameters. Properties which are not present will not be included in the -data. Required advertisement data types will always be included. -All UUIDs are 128-bit versions in the API, and 16 or 32-bit -versions of the same UUID will be used in the advertising data as appropriate. - -Service org.bluez -Interface org.bluez.LEAdvertisement1 -Object path freely definable - -Methods void Release() [noreply] - - This method gets called when the service daemon - removes the Advertisement. A client can use it to do - cleanup tasks. There is no need to call - UnregisterAdvertisement because when this method gets - called it has already been unregistered. - -Properties string Type - - Determines the type of advertising packet requested. - - Possible values: "broadcast" or "peripheral" - - array{string} ServiceUUIDs - - List of UUIDs to include in the "Service UUID" field of - the Advertising Data. - - dict ManufacturerData - - Manufactuer Data fields to include in - the Advertising Data. Keys are the Manufacturer ID - to associate with the data. - - array{string} SolicitUUIDs - - Array of UUIDs to include in "Service Solicitation" - Advertisement Data. - - dict ServiceData - - Service Data elements to include. The keys are the - UUID to associate with the data. - - dict Data [Experimental] - - Advertising Type to include in the Advertising - Data. Key is the advertising type and value is the - data as byte array. - - Note: Types already handled by other properties shall - not be used. - - Possible values: - - ... - - Example: - - 0x26 0x01 0x01... - - bool Discoverable [Experimental] - - Advertise as general discoverable. When present this - will override adapter Discoverable property. - - Note: This property shall not be set when Type is set - to broadcast. - - uint16 DiscoverableTimeout [Experimental] - - The discoverable timeout in seconds. A value of zero - means that the timeout is disabled and it will stay in - discoverable/limited mode forever. - - Note: This property shall not be set when Type is set - to broadcast. - - array{string} Includes - - List of features to be included in the advertising - packet. - - Possible values: as found on - LEAdvertisingManager.SupportedIncludes - - string LocalName - - Local name to be used in the advertising report. If the - string is too big to fit into the packet it will be - truncated. - - If this property is available 'local-name' cannot be - present in the Includes. - - uint16 Appearance - - Appearance to be used in the advertising report. - - Possible values: as found on GAP Service. - - uint16_t Duration - - Rotation duration of the advertisement in seconds. If - there are other applications advertising no duration is - set the default is 2 seconds. - - uint16_t Timeout - - Timeout of the advertisement in seconds. This defines - the lifetime of the advertisement. - - string SecondaryChannel [Experimental] - - Secondary channel to be used. Primary channel is - always set to "1M" except when "Coded" is set. - - Possible value: "1M" (default) - "2M" - "Coded" - - uint32 MinInterval [Experimental] - - Minimum advertising interval to be used by the - advertising set, in milliseconds. Acceptable values - are in the range [20ms, 10,485s]. If the provided - MinInterval is larger than the provided MaxInterval, - the registration will return failure. - - uint32 MaxInterval [Experimental] - - Maximum advertising interval to be used by the - advertising set, in milliseconds. Acceptable values - are in the range [20ms, 10,485s]. If the provided - MinInterval is larger than the provided MaxInterval, - the registration will return failure. - - int16 TxPower [Experimental] - - Requested transmission power of this advertising set. - The provided value is used only if the "CanSetTxPower" - feature is enabled on the Advertising Manager. The - provided value must be in range [-127 to +20], where - units are in dBm. - - -LE Advertising Manager hierarchy -================================ - -The Advertising Manager allows external applications to register Advertisement -Data which should be broadcast to devices. Advertisement Data elements must -follow the API for LE Advertisement Data described above. - -Service org.bluez -Interface org.bluez.LEAdvertisingManager1 -Object path /org/bluez/{hci0,hci1,...} - -Methods RegisterAdvertisement(object advertisement, dict options) - - Registers an advertisement object to be sent over the LE - Advertising channel. The service must be exported - under interface LEAdvertisement1. - - InvalidArguments error indicates that the object has - invalid or conflicting properties. - - InvalidLength error indicates that the data - provided generates a data packet which is too long. - - The properties of this object are parsed when it is - registered, and any changes are ignored. - - If the same object is registered twice it will result in - an AlreadyExists error. - - If the maximum number of advertisement instances is - reached it will result in NotPermitted error. - - Possible errors: org.bluez.Error.InvalidArguments - org.bluez.Error.AlreadyExists - org.bluez.Error.InvalidLength - org.bluez.Error.NotPermitted - - UnregisterAdvertisement(object advertisement) - - This unregisters an advertisement that has been - previously registered. The object path parameter must - match the same value that has been used on registration. - - Possible errors: org.bluez.Error.InvalidArguments - org.bluez.Error.DoesNotExist - -Properties byte ActiveInstances - - Number of active advertising instances. - - byte SupportedInstances - - Number of available advertising instances. - - array{string} SupportedIncludes - - List of supported system includes. - - Possible values: "tx-power" - "appearance" - "local-name" - "rsi" - - array{string} SupportedSecondaryChannels [Experimental] - - List of supported Secondary channels. Secondary - channels can be used to advertise with the - corresponding PHY. - - Possible values: "1M" - "2M" - "Coded" - - dict SupportedCapabilities [Experimental] - - Enumerates Advertising-related controller capabilities - useful to the client. - - Possible Values: - - byte MaxAdvLen - - Max advertising data length - - byte MaxScnRspLen - - Max advertising scan response length - - int16 MinTxPower - - Min advertising tx power (dBm) - - int16 MaxTxPower - - Max advertising tx power (dBm) - - array{string} SupportedFeatures [readonly,optional,Experimental] - - List of supported platform features. If no features - are available on the platform, the SupportedFeatures - array will be empty. - - Possible values: "CanSetTxPower" - - Indicates whether platform can - specify tx power on each - advertising instance. - - "HardwareOffload" - - Indicates whether multiple - advertising will be offloaded - to the controller. diff --git a/doc/org.bluez.LEAdvertisement.rst b/doc/org.bluez.LEAdvertisement.rst new file mode 100644 index 000000000000..4609bde74a5e --- /dev/null +++ b/doc/org.bluez.LEAdvertisement.rst @@ -0,0 +1,195 @@ +========================= +org.bluez.LEAdvertisement +========================= + +--------------------------------------------- +BlueZ D-Bus LEAdvertisement API documentation +--------------------------------------------- + +:Version: BlueZ +:Date: October 2023 +:Manual section: 5 +:Manual group: Linux System Administration + +Description +=========== + +Advertising packets are structured data which is broadcast on the LE Advertising +channels and available for all devices in range. Because of the limited space +available in LE Advertising packets, each packet's contents must be carefully +controlled. + +The service daemon acts as a store for the Advertisement Data which is meant to +be sent. It constructs the correct Advertisement Data from the structured +data and configured the kernel to send the correct advertisement. + +Interface +========= + +Specifies the Advertisement Data to be broadcast and some advertising +parameters. Properties which are not present will not be included in the +data. Required advertisement data types will always be included. +All UUIDs are 128-bit versions in the API, and 16 or 32-bit +versions of the same UUID will be used in the advertising data as appropriate. + +:Service: org.bluez +:Interface: org.bluez.LEAdvertisement1 +:Object path: freely definable + +Methods +------- + +void Release() [noreply] +```````````````````````` + + This method gets called when the service daemon removes the + Advertisement. A client can use it to do cleanup tasks. There is no + need to call **UnregisterAdvertisement()** because when this method + gets called it has already been unregistered. + +Properties +---------- + +string Type [readonly] +`````````````````````` + + Determines the type of advertising packet requested. + + Possible values: + + :"broadcast": + :"peripheral": + +array{string} ServiceUUIDs +`````````````````````````` + + List of UUIDs to include in the "Service UUID" field of the Advertising + Data. + +dict ManufacturerData +````````````````````` + + Manufacturer Data fields to include in the Advertising Data. Keys are + the Manufacturer ID to associate with the data. + +array{string} SolicitUUIDs +`````````````````````````` + + Array of UUIDs to include in "Service Solicitation" Advertisement Data. + +dict ServiceData +```````````````` + + Service Data elements to include. The keys are the UUID to associate + with the data. + +dict Data [Experimental] +```````````````````````` + + Advertising Data to include. Key is the advertising type and value is + the data as byte array. + + Note: Types already handled by other properties shall not be used. + + Possible values: + + :: + + + + Example: + + 0x26 0x01 0x01... + +bool Discoverable [Experimental] +```````````````````````````````` + + Advertise as general discoverable. When present this will override + adapter Discoverable property. + + Note: This property shall not be set when **Type** is set to + "broadcast". + +uint16 DiscoverableTimeout [Experimental] +````````````````````````````````````````` + + The discoverable timeout in seconds. A value of zero means that the + timeout is disabled and it will stay in discoverable/limited mode + forever. + + Note: This property shall not be set when **Type** is set to + "broadcast". + +array{string} Includes +`````````````````````` + + List of features to be included in the advertising packet. + + Possible values: + + See **org.bluez.LEAdvertisingManager(5)** **SupportedIncludes** + property. + +string LocalName +```````````````` + + Local name to be used in the advertising report. If the string is too + big to fit into the packet it will be truncated. + + If this property is available 'local-name' cannot be present in the + **Includes**. + +uint16 Appearance +````````````````` + + Appearance to be used in the advertising report. + + Possible values: as found on GAP Service. + +uint16_t Duration +````````````````` + + Rotation duration of the advertisement in seconds. If there are other + applications advertising no duration is set the default is 2 seconds. + +uint16_t Timeout +```````````````` + + Timeout of the advertisement in seconds. This defines the lifetime of + the advertisement. + +string SecondaryChannel [Experimental] +`````````````````````````````````````` + + Secondary channel to be used. Primary channel is always set to "1M" + except when "Coded" is set. + + Possible value: + + :"1M" (default): + :"2M": + :"Coded": + +uint32 MinInterval [Experimental] +````````````````````````````````` + + Minimum advertising interval to be used by the advertising set, in + milliseconds. Acceptable values are in the range [20ms, 10,485s]. + If the provided MinInterval is larger than the provided MaxInterval, + the registration will return failure. + +uint32 MaxInterval [Experimental] +````````````````````````````````` + + Maximum advertising interval to be used by the advertising set, in + milliseconds. Acceptable values are in the range [20ms, 10,485s]. If the + provided MinInterval is larger than the provided MaxInterval, the + registration will return failure. + +int16 TxPower [Experimental] +```````````````````````````` + + Requested transmission power of this advertising set. The provided value + is used only if the "CanSetTxPower" feature is enabled on the + **org.bluez.LEAdvertisingManager(5)**. The provided value must be in + range [-127 to +20], where units are in dBm. diff --git a/doc/org.bluez.LEAdvertisingManager.rst b/doc/org.bluez.LEAdvertisingManager.rst new file mode 100644 index 000000000000..b9d5cafc6ff3 --- /dev/null +++ b/doc/org.bluez.LEAdvertisingManager.rst @@ -0,0 +1,144 @@ +============================== +org.bluez.LEAdvertisingManager +============================== + +------------------------------------------------- +BlueZ D-Bus LEAvertisingManager API documentation +------------------------------------------------- + +:Version: BlueZ +:Date: October 2023 +:Manual section: 5 +:Manual group: Linux System Administration + +Interface +========= + +The Advertising Manager allows external applications to register Advertisement +Data which should be broadcast to devices. Advertisement Data elements must +follow the API for LE Advertisement Data described above. + +:Service: org.bluez +:Interface: org.bluez.LEAdvertisingManager1 +:Object path: /org/bluez/{hci0,hci1,...} + +Methods +------- + +void RegisterAdvertisement(object advertisement, dict options) +`````````````````````````````````````````````````````````````` + + Registers an advertisement object to be sent over the LE Advertising + channel. The service must implement **org.bluez.LEAdvertisement(5)** + interface. + + Possible errors: + + :org.bluez.Error.InvalidArguments: + + Indicates that the object has invalid or conflicting properties. + + :org.bluez.Error.AlreadyExists: + + Indicates the object is already registered. + + :org.bluez.Error.InvalidLength: + + Indicates that the data provided generates a data packet which + is too long + + :org.bluez.Error.NotPermitted: + + Indicates the maximum number of advertisement instances has + been reached. + +void UnregisterAdvertisement(object advertisement) +`````````````````````````````````````````````````` + + Unregisters an advertisement that has been previously registered using + **RegisterAdvertisement()**. The object path parameter must match the + same value that has been used on registration. + + Possible errors: + + :org.bluez.Error.InvalidArguments: + :org.bluez.Error.DoesNotExist: + +Properties +---------- + +byte ActiveInstances [readonly] +``````````````````````````````` + + Number of active advertising instances. + +byte SupportedInstances [readonly] +`````````````````````````````````` + + Number of available advertising instances. + +array{string} SupportedIncludes [readonly] +`````````````````````````````````````````` + + List of supported system includes. + + Possible values: + + :"tx-power": + :"appearance": + :"local-name": + :"rsi": + +array{string} SupportedSecondaryChannels [readonly, Experimental] +````````````````````````````````````````````````````````````````` + + List of supported Secondary channels. Secondary channels can be used to + advertise with the corresponding PHY. + + Possible values: + + :"1M": + :"2M": + :"Coded": + +dict SupportedCapabilities [readonly, Experimental] +``````````````````````````````````````````````````` + + Enumerates Advertising-related controller capabilities useful to the + client. + + Possible Values: + + :byte MaxAdvLen: + + Max advertising data length + + :byte MaxScnRspLen: + + Max advertising scan response length + + ;int16 MinTxPower: + + Min advertising tx power (dBm) + + :int16 MaxTxPower: + + Max advertising tx power (dBm) + +array{string} SupportedFeatures [readonly,optional,Experimental] +```````````````````````````````````````````````````````````````` + + List of supported platform features. If no features are available on + the platform, the SupportedFeatures array will be empty. + + Possible values: + + :"CanSetTxPower": + + Indicates whether platform can specify tx power on each + advertising instance. + + :"HardwareOffload": + + Indicates whether multiple advertising will be offloaded to the + controller. From patchwork Mon Oct 9 23:29:30 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luiz Augusto von Dentz X-Patchwork-Id: 13414683 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id D9214E95A9C for ; Mon, 9 Oct 2023 23:30:02 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1379111AbjJIXaB (ORCPT ); Mon, 9 Oct 2023 19:30:01 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:59900 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1379125AbjJIX37 (ORCPT ); Mon, 9 Oct 2023 19:29:59 -0400 Received: from mail-pl1-x629.google.com (mail-pl1-x629.google.com [IPv6:2607:f8b0:4864:20::629]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id F34CBB4 for ; Mon, 9 Oct 2023 16:29:51 -0700 (PDT) Received: by mail-pl1-x629.google.com with SMTP id d9443c01a7336-1c7373cff01so44599305ad.1 for ; Mon, 09 Oct 2023 16:29:51 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1696894190; x=1697498990; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=2n6vfqxYCPZeuUep7k9JrGFqvtKnSK8lPq6PHjeTbNA=; b=JZHIo3LVvBvsVQ1Ak4PqU6i9n730YqkCyC/QlaAmfqaGa5mXtdDhZpkaGk+9kuPQJi Cu4NQeukHx7ZRhSoG1Ivub3E7icxkAVvuOF+ziPSWirZJlDa5huNbDLbMe4Iqs7NY6VC GO+HoOWLFdrlO7rPm4birurIfrB4pwAHUOr2/o2wWTqJf/N7Jdfc+0jVbgiYTH28EssA sceRz3UZzs7aiYHTf4dGyAY8VwZW25qKn5TIXV0ZmiONEcSZuj4zktNhvemjBrELnPWg vPKSx3n0vab21rvRZhGLtYLGfbmbxqUHh2beMjnqVblFH4HzRNSeD3YUT+vwATDfjpOj gIDQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1696894190; x=1697498990; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=2n6vfqxYCPZeuUep7k9JrGFqvtKnSK8lPq6PHjeTbNA=; b=mOvpPWFqoZGOu79wB1v1ypMwn/zkrhkxqkSoHxH30+2vES1FB23/ZWBo84EGuGxEE9 Eh5uZgaLxt/8hSihjp2ILWqlGnsakMKnfVufk8whH6FuJ6+H2h50AmUrEOSmPdVX9TZh y4/mk0kV0+UcrzShYtqxaNf3FvVVl2dPOTTGIljavoOsGy81A2GlKomEUMexZP+5fD+4 /QMqJhvm9TAXbGNjUrM76sBUKQvrxjqD9oQFinGGFOYZffiVYpk9jqrs45rpGmtDuSz0 m1k6kLVJ0HcPfqJ0HnZiHpZmX3Bc/wdi5pcAZtsfH+6Yaflm3A9rHzqqB+sxfsLfSl/U bR2g== X-Gm-Message-State: AOJu0YwToT4M05JKmpNlAV3qi9ax+vI3SF5BkFSKaEi/h1DVbdSM3oka mJ91VhZhYOk6hpke5iwCev4ygWX12Y48uCG/ X-Google-Smtp-Source: AGHT+IEB3SiKbZkj65OunK0SRRYrR6pefsd7b1E+HVuZ/ePMRghzw1l7jS7ZZrBILPmYiq+TecVmFg== X-Received: by 2002:a17:902:e54a:b0:1b5:674d:2aa5 with SMTP id n10-20020a170902e54a00b001b5674d2aa5mr20544434plf.13.1696894189573; Mon, 09 Oct 2023 16:29:49 -0700 (PDT) Received: from lvondent-mobl4.. (c-98-232-221-87.hsd1.or.comcast.net. [98.232.221.87]) by smtp.gmail.com with ESMTPSA id s20-20020a170902989400b001c5b8087fe5sm10182711plp.94.2023.10.09.16.29.48 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 09 Oct 2023 16:29:48 -0700 (PDT) From: Luiz Augusto von Dentz To: linux-bluetooth@vger.kernel.org Subject: [PATCH v2 08/11] doc/gatt-api: Rename to org.bluez.Gatt*.rst Date: Mon, 9 Oct 2023 16:29:30 -0700 Message-ID: <20231009232933.500652-8-luiz.dentz@gmail.com> X-Mailer: git-send-email 2.41.0 In-Reply-To: <20231009232933.500652-1-luiz.dentz@gmail.com> References: <20231009232933.500652-1-luiz.dentz@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-bluetooth@vger.kernel.org From: Luiz Augusto von Dentz This renames gatt-api.txt to org.bluez.Gatt*.rst and generate manpages org.bluez.Gatt*.5. --- Makefile.am | 18 +- doc/gatt-api.txt | 512 --------------------------- doc/org.bluez.GattCharacteristic.rst | 375 ++++++++++++++++++++ doc/org.bluez.GattDescriptor.rst | 167 +++++++++ doc/org.bluez.GattManager.rst | 114 ++++++ doc/org.bluez.GattProfile.rst | 46 +++ doc/org.bluez.GattService.rst | 79 +++++ 7 files changed, 796 insertions(+), 515 deletions(-) delete mode 100644 doc/gatt-api.txt create mode 100644 doc/org.bluez.GattCharacteristic.rst create mode 100644 doc/org.bluez.GattDescriptor.rst create mode 100644 doc/org.bluez.GattManager.rst create mode 100644 doc/org.bluez.GattProfile.rst create mode 100644 doc/org.bluez.GattService.rst diff --git a/Makefile.am b/Makefile.am index cf72a7905274..0b62852a7a20 100644 --- a/Makefile.am +++ b/Makefile.am @@ -366,7 +366,11 @@ man_MANS += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \ doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \ doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \ doc/org.bluez.MediaTransport.5 -man_MANS += doc/org.bluez.LEAdvertisingManager.5 \ +man_MANS += doc/org.bluez.GattManager.5 doc/org.bluez.GattProfile.5 \ + doc/org.bluez.GattService.5 \ + doc/org.bluez.GattCharacteristic.5 \ + doc/org.bluez.GattDescriptor.5 \ + doc/org.bluez.LEAdvertisingManager.5 \ doc/org.bluez.LEAdvertisement.5 endif manual_pages += src/bluetoothd.8 @@ -379,7 +383,11 @@ manual_pages += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \ doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \ doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \ doc/org.bluez.MediaTransport.5 -manual_pages += doc/org.bluez.LEAdvertisingManager.5 \ +manual_pages += doc/org.bluez.GattManager.5 doc/org.bluez.GattProfile.5 \ + doc/org.bluez.GattService.5 \ + doc/org.bluez.GattCharacteristic.5 \ + doc/org.bluez.GattDescriptor.5 \ + doc/org.bluez.LEAdvertisingManager.5 \ doc/org.bluez.LEAdvertisement.5 EXTRA_DIST += src/genbuiltin src/bluetooth.conf \ @@ -431,7 +439,11 @@ EXTRA_DIST += doc/org.bluez.Media.rst doc/org.bluez.MediaControl.rst \ doc/org.bluez.MediaItem.rst doc/org.bluez.MediaEndpoint.rst \ doc/org.bluez.MediaTransport.rst -EXTRA_DIST += doc/gatt-api.txt doc/org.bluez.LEAdvertisingManager.rst \ +EXTRA_DIST += doc/org.bluez.GattManager.rst doc/org.bluez.GattProfile.rst\ + doc/org.bluez.GattService.rst \ + doc/org.bluez.GattCharacteristic.rst \ + doc/org.bluez.GattDescriptor.rst \ + doc/org.bluez.LEAdvertisingManager.rst \ doc/org.bluez.LEAdvertisement.rst EXTRA_DIST += doc/obex-api.txt doc/obex-agent-api.txt diff --git a/doc/gatt-api.txt b/doc/gatt-api.txt deleted file mode 100644 index f29308aec843..000000000000 --- a/doc/gatt-api.txt +++ /dev/null @@ -1,512 +0,0 @@ -BlueZ D-Bus GATT API description -******************************** - -GATT local and remote services share the same high-level D-Bus API. Local -refers to GATT based service exported by a BlueZ plugin or an external -application. Remote refers to GATT services exported by the peer. - -BlueZ acts as a proxy, translating ATT operations to D-Bus method calls and -Properties (or the opposite). Support for D-Bus Object Manager is mandatory for -external services to allow seamless GATT declarations (Service, Characteristic -and Descriptors) discovery. Each GATT service tree is required to export a D-Bus -Object Manager at its root that is solely responsible for the objects that -belong to that service. - -Releasing a registered GATT service is not defined yet. Any API extension -should avoid breaking the defined API, and if possible keep an unified GATT -remote and local services representation. - -Service hierarchy -================= - -GATT remote and local service representation. Object path for local services -is freely definable. - -External applications implementing local services must register the services -using GattManager1 registration method and must implement the methods and -properties defined in GattService1 interface. - -Service org.bluez -Interface org.bluez.GattService1 -Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/serviceXX - -Properties string UUID [read-only] - - 128-bit service UUID. - - boolean Primary [read-only] - - Indicates whether or not this GATT service is a - primary service. If false, the service is secondary. - - object Device [read-only, optional] - - Object path of the Bluetooth device the service - belongs to. Only present on services from remote - devices. - - array{object} Includes [read-only, optional] - - Array of object paths representing the included - services of this service. - - uint16 Handle [read-write, optional] (Server Only) - [read-only] (Client Only) - - Service handle. When available in the server it - would attempt to use to allocate into the database - which may fail, to auto allocate the value 0x0000 - shall be used which will cause the allocated handle to - be set once registered. - - -Characteristic hierarchy -======================== - -For local GATT defined services, the object paths need to follow the service -path hierarchy and are freely definable. - -Service org.bluez -Interface org.bluez.GattCharacteristic1 -Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/serviceXX/charYYYY - -Methods array{byte} ReadValue(dict options) - - Issues a request to read the value of the - characteristic and returns the value if the - operation was successful. - - Possible options: "offset": uint16 offset - "mtu": Exchanged MTU (Server only) - "device": Object Device (Server only) - - Possible Errors: org.bluez.Error.Failed(string ecode) - org.bluez.Error.InProgress - org.bluez.Error.NotPermitted - org.bluez.Error.NotAuthorized - org.bluez.Error.InvalidOffset - org.bluez.Error.NotSupported - - Possible Error Code: string 0x80 - 0x9f - - void WriteValue(array{byte} value, dict options) - - Issues a request to write the value of the - characteristic. - - Possible options: "offset": Start offset - "type": string - Possible values: - "command": Write without - response - "request": Write with response - "reliable": Reliable Write - "mtu": Exchanged MTU (Server only) - "device": Device path (Server only) - "link": Link type (Server only) - "prepare-authorize": True if prepare - authorization - request - - Possible Errors: org.bluez.Error.Failed(string ecode) - org.bluez.Error.InProgress - org.bluez.Error.NotPermitted - org.bluez.Error.InvalidValueLength - org.bluez.Error.NotAuthorized - org.bluez.Error.NotSupported - - Possible Error Code: string 0x80 - 0x9f - - fd, uint16 AcquireWrite(dict options) [optional] - - Acquire file descriptor and MTU for writing. Only - sockets are supported. Usage of WriteValue will be - locked causing it to return NotPermitted error. - - For server the MTU returned shall be equal or smaller - than the negotiated MTU. - - For client it only works with characteristic that has - WriteAcquired property which relies on - write-without-response Flag. - - To release the lock the client shall close the file - descriptor, a HUP is generated in case the device - is disconnected. - - Note: the MTU can only be negotiated once and is - symmetric therefore this method may be delayed in - order to have the exchange MTU completed, because of - that the file descriptor is closed during - reconnections as the MTU has to be renegotiated. - - Possible options: "device": Object Device (Server only) - "mtu": Exchanged MTU (Server only) - "link": Link type (Server only) - - Possible Errors: org.bluez.Error.Failed - org.bluez.Error.NotSupported - - fd, uint16 AcquireNotify(dict options) [optional] - - Acquire file descriptor and MTU for notify. Only - sockets are support. Usage of StartNotify will be locked - causing it to return NotPermitted error. - - For server the MTU returned shall be equal or smaller - than the negotiated MTU. - - Only works with characteristic that has NotifyAcquired - which relies on notify Flag and no other client have - called StartNotify. - - Notification are enabled during this procedure so - StartNotify shall not be called, any notification - will be dispatched via file descriptor therefore the - Value property is not affected during the time where - notify has been acquired. - - To release the lock the client shall close the file - descriptor, a HUP is generated in case the device - is disconnected. - - Note: the MTU can only be negotiated once and is - symmetric therefore this method may be delayed in - order to have the exchange MTU completed, because of - that the file descriptor is closed during - reconnections as the MTU has to be renegotiated. - - Possible options: "device": Object Device (Server only) - "mtu": Exchanged MTU (Server only) - "link": Link type (Server only) - - Possible Errors: org.bluez.Error.Failed - org.bluez.Error.NotSupported - - void StartNotify() - - Starts a notification session from this characteristic - if it supports value notifications or indications. - - Possible Errors: org.bluez.Error.Failed - org.bluez.Error.NotPermitted - org.bluez.Error.InProgress - org.bluez.Error.NotConnected - org.bluez.Error.NotSupported - - void StopNotify() - - This method will cancel any previous StartNotify - transaction. Note that notifications from a - characteristic are shared between sessions thus - calling StopNotify will release a single session. - - Possible Errors: org.bluez.Error.Failed - - void Confirm() [optional] (Server only) - - This method doesn't expect a reply so it is just a - confirmation that value was received. - - Possible Errors: org.bluez.Error.Failed - -Properties string UUID [read-only] - - 128-bit characteristic UUID. - - object Service [read-only] - - Object path of the GATT service the characteristic - belongs to. - - array{byte} Value [read-only, optional] - - The cached value of the characteristic. This property - gets updated only after a successful read request and - when a notification or indication is received, upon - which a PropertiesChanged signal will be emitted. - - boolean WriteAcquired [read-only, optional] - - True, if this characteristic has been acquired by any - client using AcquireWrite. - - For client properties is ommited in case - 'write-without-response' flag is not set. - - For server the presence of this property indicates - that AcquireWrite is supported. - - boolean NotifyAcquired [read-only, optional] - - True, if this characteristic has been acquired by any - client using AcquireNotify. - - For client this properties is ommited in case 'notify' - flag is not set. - - For server the presence of this property indicates - that AcquireNotify is supported. - - boolean Notifying [read-only, optional] - - True, if notifications or indications on this - characteristic are currently enabled. - - array{string} Flags [read-only] - - Defines how the characteristic value can be used. See - Core spec "Table 3.5: Characteristic Properties bit - field", and "Table 3.8: Characteristic Extended - Properties bit field". - - The "x-notify" and "x-indicate" flags restrict access - to notifications and indications by imposing write - restrictions on a characteristic's client - characteristic configuration descriptor. - - Allowed values: - - "broadcast" - "read" - "write-without-response" - "write" - "notify" - "indicate" - "authenticated-signed-writes" - "extended-properties" - "reliable-write" - "writable-auxiliaries" - "encrypt-read" - "encrypt-write" - "encrypt-notify" (Server only) - "encrypt-indicate" (Server only) - "encrypt-authenticated-read" - "encrypt-authenticated-write" - "encrypt-authenticated-notify" (Server only) - "encrypt-authenticated-indicate" (Server only) - "secure-read" (Server only) - "secure-write" (Server only) - "secure-notify" (Server only) - "secure-indicate" (Server only) - "authorize" - - uint16 Handle [read-write, optional] (Server Only) - [read-only] (Client Only) - - Characteristic handle. When available in the server it - would attempt to use to allocate into the database - which may fail, to auto allocate the value 0x0000 - shall be used which will cause the allocated handle to - be set once registered. - - uint16 MTU [read-only] - - Characteristic MTU, this is valid both for ReadValue - and WriteValue but either method can use long - procedures when supported. - -Characteristic Descriptors hierarchy -==================================== - -Local or remote GATT characteristic descriptors hierarchy. - -Service org.bluez -Interface org.bluez.GattDescriptor1 -Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/serviceXX/charYYYY/descriptorZZZ - -Methods array{byte} ReadValue(dict flags) - - Issues a request to read the value of the - characteristic and returns the value if the - operation was successful. - - Possible options: "offset": Start offset - "device": Device path (Server only) - "link": Link type (Server only) - - Possible Errors: org.bluez.Error.Failed - org.bluez.Error.InProgress - org.bluez.Error.NotPermitted - org.bluez.Error.NotAuthorized - org.bluez.Error.NotSupported - - void WriteValue(array{byte} value, dict flags) - - Issues a request to write the value of the - characteristic. - - Possible options: "offset": Start offset - "device": Device path (Server only) - "link": Link type (Server only) - "prepare-authorize": boolean Is prepare - authorization - request - - Possible Errors: org.bluez.Error.Failed - org.bluez.Error.InProgress - org.bluez.Error.NotPermitted - org.bluez.Error.InvalidValueLength - org.bluez.Error.NotAuthorized - org.bluez.Error.NotSupported - -Properties string UUID [read-only] - - 128-bit descriptor UUID. - - object Characteristic [read-only] - - Object path of the GATT characteristic the descriptor - belongs to. - - array{byte} Value [read-only, optional] - - The cached value of the descriptor. This property - gets updated only after a successful read request, upon - which a PropertiesChanged signal will be emitted. - - array{string} Flags [read-only] - - Defines how the descriptor value can be used. - - Possible values: - - "read" - "write" - "encrypt-read" - "encrypt-write" - "encrypt-authenticated-read" - "encrypt-authenticated-write" - "secure-read" (Server Only) - "secure-write" (Server Only) - "authorize" - - uint16 Handle [read-write, optional] (Server Only) - [read-only] (Client Only) - - Characteristic handle. When available in the server it - would attempt to use to allocate into the database - which may fail, to auto allocate the value 0x0000 - shall be used which will cause the allocated handle to - be set once registered. - -GATT Profile hierarchy -===================== - -Local profile (GATT client) instance. By registering this type of object -an application effectively indicates support for a specific GATT profile -and requests automatic connections to be established to devices -supporting it. - -Service -Interface org.bluez.GattProfile1 -Object path - -Methods void Release() - - This method gets called when the service daemon - unregisters the profile. The profile can use it to - do cleanup tasks. There is no need to unregister the - profile, because when this method gets called it has - already been unregistered. - -Properties array{string} UUIDs [read-only] - - 128-bit GATT service UUIDs to auto connect. - - -GATT Manager hierarchy -====================== - -GATT Manager allows external applications to register GATT services and -profiles. - -Registering a profile allows applications to subscribe to *remote* services. -These must implement the GattProfile1 interface defined above. - -Registering a service allows applications to publish a *local* GATT service, -which then becomes available to remote devices. A GATT service is represented by -a D-Bus object hierarchy where the root node corresponds to a service and the -child nodes represent characteristics and descriptors that belong to that -service. Each node must implement one of GattService1, GattCharacteristic1, -or GattDescriptor1 interfaces described above, based on the attribute it -represents. Each node must also implement the standard D-Bus Properties -interface to expose their properties. These objects collectively represent a -GATT service definition. - -To make service registration simple, BlueZ requires that all objects that belong -to a GATT service be grouped under a D-Bus Object Manager that solely manages -the objects of that service. Hence, the standard DBus.ObjectManager interface -must be available on the root service path. An example application hierarchy -containing two separate GATT services may look like this: - --> /com/example - | - org.freedesktop.DBus.ObjectManager - | - -> /com/example/service0 - | | - org.freedesktop.DBus.Properties - | | - org.bluez.GattService1 - | | - | -> /com/example/service0/char0 - | | - org.freedesktop.DBus.Properties - | | - org.bluez.GattCharacteristic1 - | | - | -> /com/example/service0/char1 - | | - org.freedesktop.DBus.Properties - | | - org.bluez.GattCharacteristic1 - | | - | -> /com/example/service0/char1/desc0 - | - org.freedesktop.DBus.Properties - | - org.bluez.GattDescriptor1 - | - -> /com/example/service1 - | - org.freedesktop.DBus.Properties - | - org.bluez.GattService1 - | - -> /com/example/service1/char0 - - org.freedesktop.DBus.Properties - - org.bluez.GattCharacteristic1 - -When a service is registered, BlueZ will automatically obtain information about -all objects using the service's Object Manager. Once a service has been -registered, the objects of a service should not be removed. If BlueZ receives an -InterfacesRemoved signal from a service's Object Manager, it will immediately -unregister the service. Similarly, if the application disconnects from the bus, -all of its registered services will be automatically unregistered. -InterfacesAdded signals will be ignored. - -Examples: - - Client - test/example-gatt-client - client/bluetoothctl - - Server - test/example-gatt-server - tools/gatt-service - - -Service org.bluez -Interface org.bluez.GattManager1 -Object path [variable prefix]/{hci0,hci1,...} - -Methods void RegisterApplication(object application, dict options) - - Registers a local GATT services hierarchy as described - above (GATT Server) and/or GATT profiles (GATT Client). - - The application object path together with the D-Bus - system bus connection ID define the identification of - the application registering a GATT based - service or profile. - - Possible errors: org.bluez.Error.InvalidArguments - org.bluez.Error.AlreadyExists - - void UnregisterApplication(object application) - - This unregisters the services that has been - previously registered. The object path parameter - must match the same value that has been used - on registration. - - Possible errors: org.bluez.Error.InvalidArguments - org.bluez.Error.DoesNotExist diff --git a/doc/org.bluez.GattCharacteristic.rst b/doc/org.bluez.GattCharacteristic.rst new file mode 100644 index 000000000000..cd5a0d0c788f --- /dev/null +++ b/doc/org.bluez.GattCharacteristic.rst @@ -0,0 +1,375 @@ +============================ +org.bluez.GattCharacteristic +============================ + +------------------------------------------------ +BlueZ D-Bus GattCharacteristic API documentation +------------------------------------------------ + +:Version: BlueZ +:Date: October 2023 +:Manual section: 5 +:Manual group: Linux System Administration + +Description +=========== + +GATT local/server and remote/client characteristic attribute representation +share the same high-level D-Bus API. + +Local/Server refers to GATT based characteristics exported by a plugin or an +external application. + +Remote/Client refers to GATT characteristics exported by the peer. + +Interface +========= + +Client +------ + +:Service: org.bluez +:Interface: org.bluez.GattCharacteristic1 +:Object path: [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/serviceXX/charYYYY + +Server +------ + +:Service: unique name +:Interface: org.bluez.GattCharacteristic1 +:Object path: freely definable + +Methods +------- + +array{byte} ReadValue(dict options) +``````````````````````````````````` + + Issues a request to read the value of the characteristic and returns the + value if the operation was successful. + + Possible options: + + :uint16_t offset: + + Read start offset in bytes. + + :uint16_t mtu (server only): + + Exchange MTU in bytes. + + :object device (server only): + + Device object. + + Possible Errors: + + :org.bluez.Error.Failed: + + Possible values: string 0x80 - 0x9f + + :org.bluez.Error.InProgress: + :org.bluez.Error.NotPermitted: + :org.bluez.Error.NotAuthorized: + :org.bluez.Error.InvalidOffset: + :org.bluez.Error.NotSupported: + +void WriteValue(array{byte} value, dict options) +```````````````````````````````````````````````` + + Issues a request to write the value of the characteristic. + + Possible options: + + :uint16 offset: + + Write start offset in bytes. + + :string type: + + Possible values: + + :"command": + + Use Write without response procedure. + + :"request": + + Use Write with response procedure. + + :"reliable": + + Use Reliable Write procedure. + + :uint16 mtu: + + Exchanged MTU (Server only). + + :object device: + + Device path (Server only). + + :string link: + + Link type (Server only). + + Possible values: + + :"BR/EDR": + :"LE": + + :boolean prepare-authorize: + + True if prepare authorization request. + + Possible Errors: + + :org.bluez.Error.Failed: + + Possible values: string 0x80 - 0x9f + + :org.bluez.Error.InProgress: + :org.bluez.Error.NotPermitted: + :org.bluez.Error.InvalidValueLength: + :org.bluez.Error.NotAuthorized: + :org.bluez.Error.NotSupported: + +fd, uint16 AcquireWrite(dict options) [optional] +```````````````````````````````````````````````` + + Acquire file descriptor and MTU for writing. Only sockets are supported. + Usage of WriteValue will be locked causing it to return NotPermitted + error. + + For server the MTU returned shall be equal or smaller than the + negotiated MTU. + + For client it only works with characteristic that has **WriteAcquired** + property which relies on write-without-response **Flag**. + + To release the lock the client shall close the file descriptor, a HUP + is generated in case the device is disconnected. + + Note: the MTU can only be negotiated once and is symmetric therefore + this method may be delayed in order to have the exchange MTU completed, + because of that the file descriptor is closed during reconnections as + the MTU has to be renegotiated. + + Possible options: + + :object device: + + Object Device (Server only). + + :uint16 mtu: + + Exchanged MTU (Server only). + + :string link: + + Link type (Server only). + + Possible values: + + :"BR/EDR": + :"LE": + + Possible Errors: + + :org.bluez.Error.Failed: + :org.bluez.Error.NotSupported: + +fd, uint16 AcquireNotify(dict options) [optional] +````````````````````````````````````````````````` + + Acquire file descriptor and MTU for notify. Only sockets are support. + + Usage of StartNotify will be locked causing it to return + **org.bluez.Error.NotPermitted**. + + For server the MTU returned shall be equal or smaller than the + negotiated MTU. + + Only works with characteristic that has **NotifyAcquired** property + which relies on **"notify"** **Flag** and no other client have called + **StartNotify()**. + + Notification are enabled during this procedure so **StartNotify()** + shall not be called, any notification will be dispatched via file + descriptor therefore the Value property is not affected during the time + where notify has been acquired. + + To release the lock the client shall close the file descriptor, a HUP is + generated in case the device is disconnected. + + Note: the MTU can only be negotiated once and is symmetric therefore + this method may be delayed in order to have the exchange MTU completed, + because of that the file descriptor is closed during reconnections as + the MTU has to be renegotiated. + + Possible options: + + :object device: + + Object Device (Server only). + + :uint16 mtu: + + Exchanged MTU (Server only). + + :string link: + + Link type (Server only). + + Possible values: + + :"BR/EDR": + :"LE": + + Possible Errors: + + :org.bluez.Error.Failed: + :org.bluez.Error.NotSupported: + :org.bluez.Error.NotPermitted: + +void StartNotify() +`````````````````` + + Starts a notification session from this characteristic if it supports + value notifications or indications. + + Possible Errors: + + :org.bluez.Error.Failed: + :org.bluez.Error.NotPermitted: + :org.bluez.Error.InProgress: + :org.bluez.Error.NotConnected: + :org.bluez.Error.NotSupported: + +void StopNotify() +````````````````` + + Stops or cancel session previously created by **StartNotify()**. + + Note that notifications from a characteristic are shared between + sessions thus calling StopNotify will release a single session. + + Possible Errors: + + :org.bluez.Error.Failed: + +void Confirm() [noreply, optional] (Server only) +```````````````````````````````````````````````` + + + Confirms value was received. + + Possible Errors: + + org.bluez.Error.Failed + +Properties +---------- + +string UUID [read-only] +``````````````````````` + + 128-bit characteristic UUID. + +object Service [read-only] +`````````````````````````` + + Object path of the GATT service the characteristic belongs to. + +array{byte} Value [read-only, optional] +``````````````````````````````````````` + + The cached value of the characteristic. This property gets updated only + after a successful read request and when a notification or indication + is received, upon which a PropertiesChanged signal will be emitted. + +boolean WriteAcquired [read-only, optional] +``````````````````````````````````````````` + + True, if this characteristic has been acquired by any client using + AcquireWrite. + + For client properties is ommited in case 'write-without-response' flag + is not set. + + For server the presence of this property indicates that AcquireWrite is + supported. + +boolean NotifyAcquired [read-only, optional] +```````````````````````````````````````````` + + True, if this characteristic has been acquired by any client using + AcquireNotify. + + For client this properties is ommited in case 'notify' flag is not set. + + For server the presence of this property indicates that AcquireNotify + is supported. + +boolean Notifying [read-only, optional] +``````````````````````````````````````` + + True, if notifications or indications on this characteristic are + currently enabled. + +array{string} Flags [read-only] +``````````````````````````````` + + Defines how the characteristic value can be used. See Core spec + "Table 3.5: Characteristic Properties bit field", and + "Table 3.8: Characteristic Extended Properties bit field". + + The "x-notify" and "x-indicate" flags restrict access to notifications + and indications by imposing write restrictions on a characteristic's + client characteristic configuration descriptor. + + Possible values: + + :"broadcast": + :"read": + :"write-without-response": + :"write": + :"notify": + :"indicate": + :"authenticated-signed-writes": + :"extended-properties": + :"reliable-write": + :"writable-auxiliaries": + :"encrypt-read": + :"encrypt-write": + :"encrypt-notify" (Server only): + :"encrypt-indicate" (Server only): + :"encrypt-authenticated-read": + :"encrypt-authenticated-write": + :"encrypt-authenticated-notify" (Server only): + :"encrypt-authenticated-indicate" (Server only): + :"secure-read" (Server only): + :"secure-write" (Server only): + :"secure-notify" (Server only): + :"secure-indicate" (Server only): + :"authorize": + +uint16 Handle [read-only] (Client Only) +``````````````````````````````````````` + + Characteristic handle. + +uint16 Handle [read-write, optional] (Server Only) +`````````````````````````````````````````````````` + + Characteristic handle. When available in the server it would attempt to + use to allocate into the database which may fail, to auto allocate the + value 0x0000 shall be used which will cause the allocated handle to be + set once registered. + +uint16 MTU [read-only] +`````````````````````` + + Characteristic MTU, this is valid both for **ReadValue()** and + **WriteValue()** but either method can use long procedures when + supported. diff --git a/doc/org.bluez.GattDescriptor.rst b/doc/org.bluez.GattDescriptor.rst new file mode 100644 index 000000000000..94cc8b26af29 --- /dev/null +++ b/doc/org.bluez.GattDescriptor.rst @@ -0,0 +1,167 @@ +======================== +org.bluez.GattDescriptor +======================== + +-------------------------------------------- +BlueZ D-Bus GattDescriptor API documentation +-------------------------------------------- + +:Version: BlueZ +:Date: October 2023 +:Manual section: 5 +:Manual group: Linux System Administration + +Description +=========== + +GATT local/server and remote/client descriptor attribute representation +share the same high-level D-Bus API. + +Local/Server refers to GATT based descriptors exported by a plugin or an +external application. + +Remote/Client refers to GATT descriptors exported by the peer. + +Interface +========= + +Client +------ + +:Service: org.bluez +:Interface: org.bluez.GattDescriptor1 +:Object path: [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/serviceXX/charYYYY/descriptorZZZ + +Server +------ + +:Service: unique name +:Interface: org.bluez.GattDescriptor1 +:Object path: freely definable + +Methods +------- + +array{byte} ReadValue(dict flags) +````````````````````````````````` + + Issues a request to read the value of the descriptor and returns the + value if the operation was successful. + + Possible options: + + :uint16_t offset: + + Read start offset in bytes. + + :object device (server only): + + Device object. + + :string link: + + Link type (Server only). + + Possible values: + + :"BR/EDR": + :"LE": + + Possible Errors: + + :org.bluez.Error.Failed: + :org.bluez.Error.InProgress: + :org.bluez.Error.NotPermitted: + :org.bluez.Error.NotAuthorized: + :org.bluez.Error.NotSupported: + +void WriteValue(array{byte} value, dict flags) +`````````````````````````````````````````````` + + Issues a request to write the value of the descriptor. + + Possible flags: + + :uint16 offset: + + Write start offset in bytes. + + :uint16 mtu: + + Exchanged MTU (Server only). + + :object device: + + Device path (Server only). + + :string link: + + Link type (Server only). + + Possible values: + + :"BR/EDR": + :"LE": + + :boolean prepare-authorize: + + True if prepare authorization request. + + Possible Errors: + + :org.bluez.Error.Failed: + :org.bluez.Error.InProgress: + :org.bluez.Error.NotPermitted: + :org.bluez.Error.InvalidValueLength: + :org.bluez.Error.NotAuthorized: + :org.bluez.Error.NotSupported: + +Properties +---------- + +string UUID [read-only] +``````````````````````` + + 128-bit descriptor UUID. + +object Characteristic [read-only] +````````````````````````````````` + + Object path of the GATT characteristic the descriptor belongs to. + +array{byte} Value [read-only, optional] +``````````````````````````````````````` + + The cached value of the descriptor. This property gets updated only + after a successful read request, upon which a PropertiesChanged signal + will be emitted. + +array{string} Flags [read-only] +``````````````````````````````` + + Defines how the descriptor value can be used. + + Possible values: + + :"read": + :"write": + :"encrypt-read": + :"encrypt-write": + :"encrypt-authenticated-read": + :"encrypt-authenticated-write": + :"secure-read" (Server Only): + :"secure-write" (Server Only): + :"authorize": + +uint16 Handle [read-only] (Client Only) +``````````````````````````````````````` + + Descriptor handle. + +uint16 Handle [read-write, optional] (Server Only) +`````````````````````````````````````````````````` + + Descriptor handle. When available in the server it would attempt to + use to allocate into the database which may fail, to auto allocate the + value 0x0000 shall be used which will cause the allocated handle to be + set once registered. diff --git a/doc/org.bluez.GattManager.rst b/doc/org.bluez.GattManager.rst new file mode 100644 index 000000000000..f98296b89a01 --- /dev/null +++ b/doc/org.bluez.GattManager.rst @@ -0,0 +1,114 @@ +===================== +org.bluez.GattManager +===================== + +----------------------------------------- +BlueZ D-Bus GattManager API documentation +----------------------------------------- + +:Version: BlueZ +:Date: October 2023 +:Manual section: 5 +:Manual group: Linux System Administration + +Description +=========== + +GATT Manager allows external applications to register GATT services and +profiles. + +Registering a profile allows applications to subscribe to *remote/client* +services. + +Registering a service allows applications to publish a *local/server* GATT +service, which then becomes available to remote devices. A GATT service is +represented by a D-Bus object hierarchy where the root node corresponds to a +service and the child nodes represent characteristics and descriptors that +belong to that service. Each node must implement one of +**org.bluez.GattService(5)**, **org.bluez.GattCharacteristic(5)** or +**org.bluez.GattDescriptor(5)** interfaces, based on the attribute it +represents. Each node must also implement the standard D-Bus Properties +interface to expose their properties. These objects collectively represent a +GATT service definition. + +To make service registration simple, **bluetoothd(8)** requires that all objects +that belong to a GATT service be grouped under a D-Bus Object Manager that +solely manages the objects of that service. Hence, the standard +DBus.ObjectManager interface must be available on the root service path. An +example application hierarchy containing two separate GATT services may look +like this: + +.. code-block:: + + -> /com/example + | - org.freedesktop.DBus.ObjectManager + | + -> /com/example/service0 + | | - org.freedesktop.DBus.Properties + | | - org.bluez.GattService1 + | | + | -> /com/example/service0/char0 + | | - org.freedesktop.DBus.Properties + | | - org.bluez.GattCharacteristic1 + | | + | -> /com/example/service0/char1 + | | - org.freedesktop.DBus.Properties + | | - org.bluez.GattCharacteristic1 + | | + | -> /com/example/service0/char1/desc0 + | - org.freedesktop.DBus.Properties + | - org.bluez.GattDescriptor1 + | + -> /com/example/service1 + | - org.freedesktop.DBus.Properties + | - org.bluez.GattService1 + | + -> /com/example/service1/char0 + - org.freedesktop.DBus.Properties + - org.bluez.GattCharacteristic1 + +When a service is registered, **bluetoothd(8)** will automatically obtain +information about all objects using the service's Object Manager. Once a service +has been registered, the objects of a service should not be removed. If +**bluetoothd(8)** receives an InterfacesRemoved signal from a service's Object +Manager, it will immediately unregister the service. Similarly, if the +application disconnects from the bus, all of its registered services will be +automatically unregistered. InterfacesAdded signals will be ignored. + +Interface +========= + +:Service: org.bluez +:Interface: org.bluez.GattManager1 +:Object path: [variable prefix]/{hci0,hci1,...} + +Methods +------- + +void RegisterApplication(object application, dict options) +`````````````````````````````````````````````````````````` + + Registers a local GATT services hierarchy as described above + (GATT Server) and/or GATT profiles (GATT Client). + + The application object path together with the D-Bus system bus + connection ID define the identification of the application registering + a GATT based service (**org.bluez.GattService(5)**) and/or profile + (**org.bluez.GattProfile(5)**). + + Possible errors: + + :org.bluez.Error.InvalidArguments: + :org.bluez.Error.AlreadyExists: + +void UnregisterApplication(object application) +`````````````````````````````````````````````` + + This unregisters the services and/or profiles that has been previously + registered using **RegisterApplication()**. The object path parameter + must match the same value that has been used on registration. + + Possible errors: + + :org.bluez.Error.InvalidArguments: + :org.bluez.Error.DoesNotExist: diff --git a/doc/org.bluez.GattProfile.rst b/doc/org.bluez.GattProfile.rst new file mode 100644 index 000000000000..904301a9773b --- /dev/null +++ b/doc/org.bluez.GattProfile.rst @@ -0,0 +1,46 @@ +===================== +org.bluez.GattProfile +===================== + +----------------------------------------- +BlueZ D-Bus GattProfile API documentation +----------------------------------------- + +:Version: BlueZ +:Date: October 2023 +:Manual section: 5 +:Manual group: Linux System Administration + +Description +=========== + +Local profile (GATT client) instance. By registering this type of object +an application effectively indicates support for a specific GATT profile +and requests automatic connections to be established to devices +supporting it. + +Interface +========= + +:Service: +:Interface: org.bluez.GattProfile1 +:Object path: + +Methods +------- + +void Release() +`````````````` + + This method gets called when the service daemon + unregisters the profile. The profile can use it to do cleanup tasks. + There is no need to unregister the profile, because when this method + gets called it has already been unregistered. + +Properties +---------- + +array{string} UUIDs [read-only] +``````````````````````````````` + + 128-bit GATT service UUIDs to auto connect. diff --git a/doc/org.bluez.GattService.rst b/doc/org.bluez.GattService.rst new file mode 100644 index 000000000000..4a1e81fc9e03 --- /dev/null +++ b/doc/org.bluez.GattService.rst @@ -0,0 +1,79 @@ +===================== +org.bluez.GattService +===================== + +------------------------------------------------- +BlueZ D-Bus GattService API documentation +------------------------------------------------- + +:Version: BlueZ +:Date: October 2023 +:Manual section: 5 +:Manual group: Linux System Administration + +Description +=========== + +GATT local/server and remote/client services share the same high-level D-Bus +API. + +Local/Server refers to GATT based service exported by a plugin or an external +application. + +Remote/Client refers to GATT services exported by the peer. + +Interface +========= + +Client +------ + +:Service: org.bluez +:Interface: org.bluez.GattService1 +:Object path: [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/serviceXX + +Server +------ + +:Service: unique name +:Interface: org.bluez.GattService1 +:Object path: freely definable + +Properties +---------- + +string UUID [read-only] +``````````````````````` + + 128-bit service UUID. + +boolean Primary [read-only] +``````````````````````````` + + Indicates whether or not this GATT service is a primary service. If + false, the service is secondary. + +object Device [read-only, optional] +``````````````````````````````````` + + Object path of the Bluetooth device the service belongs to. Only + present on services from remote devices. + +array{object} Includes [read-only, optional] +```````````````````````````````````````````` + + Array of object paths representing the included services of this + service. + +uint16 Handle [read-only] (client only) +``````````````````````````````````````` + + Service handle. + +uint16 Handle [read-write, optional] (Server Only) +`````````````````````````````````````````````````` + + Service handle. When available in the server it would attempt to use to + allocate into the database which may fail, to auto allocate the value + 0x0000 shall be used which will cause the allocated handle to be set + once registered. From patchwork Mon Oct 9 23:29:31 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luiz Augusto von Dentz X-Patchwork-Id: 13414680 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id D73E9E9413E for ; Mon, 9 Oct 2023 23:29:59 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1379127AbjJIX37 (ORCPT ); Mon, 9 Oct 2023 19:29:59 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:59048 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1379101AbjJIX35 (ORCPT ); Mon, 9 Oct 2023 19:29:57 -0400 Received: from mail-pl1-x629.google.com (mail-pl1-x629.google.com [IPv6:2607:f8b0:4864:20::629]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id AAC47B8 for ; Mon, 9 Oct 2023 16:29:52 -0700 (PDT) Received: by mail-pl1-x629.google.com with SMTP id d9443c01a7336-1c760b34d25so34356755ad.3 for ; Mon, 09 Oct 2023 16:29:52 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1696894191; x=1697498991; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=RPKPTrAFTaG/VuvdOhexMV8R8338ygb3Fefuv4griHI=; b=Pa+3zhcAgob3WgMa3SVOn9Ewbqzx/oazzXZnUmZyspYy30xLbza42/RNJp57+biwP/ 9NwPqvFdzAEICraY2+7Xje5b5LfFFfkLT0Uh+v9a9sO2lC3vkiNXDIcMTTppUwyvAEk7 65nlTpm41gJmmMRWZMx5FwurU0p+hIHOqi+4Wh1EJNq1bBf6ivYbtovqPjil3y4aBSMe BnOHodfWuti7IEjV5Kd8Oz/aqMvJfqIpWZS8/6kD9UwBtJR/9oZQ31Ol1xO0+Bfl+nMQ TY8HyQtZQ6Joqm0fRP3vPkx0/cEYXjkXNZD0ugc0rbGZ88FK46ma1tKhInUnKq2+RkpC oSwg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1696894191; x=1697498991; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=RPKPTrAFTaG/VuvdOhexMV8R8338ygb3Fefuv4griHI=; b=DUsZHX99UZl7ELbE5Und4gI9KDehrE+v3jNnLwcW0Td/+xYCgihl93GffvEAWkJlNs 1GcM6+at6fepZavTp1L7zNvPTb8bBZ4HsxhMxbS2eihNwXGmRoUcImUYlaPAo0CRQy03 sdUlTnJfBI3BGJo78IiV6zmkQ2dnGewWdBbB51MHVkYarYSSLMbA/xU92U5fdy8MiGrV 0OAJL+o4TBmHZ2bLt23Av33sDlUaTZs7tdfqxJe/bEK6v5b9F72RWJyfRoKZ9sqpGnjR Dm/3p03HIUETBFjGvYU953LT6oAlZNhRcTC47hNqGd+J8kFJIMehHkeuGMHhF0SIs1Cm eHjQ== X-Gm-Message-State: AOJu0YzVVO7piX/T50dbhtgUV6DeflthSQ+rnUEeaBwP1ONR2oKncD3M wNYFf1SAbp+N2awjYYPa8vvBPrtzZfdW3VPI X-Google-Smtp-Source: AGHT+IHe0EUo0/U8f2HltUYdGHC7Hg/DxBsV4+OTKMJBrnJnoTA6nIcY18/5f1V0iwROj68mHqnMIQ== X-Received: by 2002:a17:902:da8d:b0:1c0:d17a:bfe9 with SMTP id j13-20020a170902da8d00b001c0d17abfe9mr17394592plx.46.1696894191170; Mon, 09 Oct 2023 16:29:51 -0700 (PDT) Received: from lvondent-mobl4.. (c-98-232-221-87.hsd1.or.comcast.net. [98.232.221.87]) by smtp.gmail.com with ESMTPSA id s20-20020a170902989400b001c5b8087fe5sm10182711plp.94.2023.10.09.16.29.49 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 09 Oct 2023 16:29:50 -0700 (PDT) From: Luiz Augusto von Dentz To: linux-bluetooth@vger.kernel.org Subject: [PATCH v2 09/11] doc/battery-api: Rename to org.bluez.Battery*.rst Date: Mon, 9 Oct 2023 16:29:31 -0700 Message-ID: <20231009232933.500652-9-luiz.dentz@gmail.com> X-Mailer: git-send-email 2.41.0 In-Reply-To: <20231009232933.500652-1-luiz.dentz@gmail.com> References: <20231009232933.500652-1-luiz.dentz@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-bluetooth@vger.kernel.org From: Luiz Augusto von Dentz This renames battery-api.txt to org.bluez.Battery*.rst and generate manpages org.bluez.Battery*.5. --- Makefile.am | 18 ++++--- doc/battery-api.txt | 69 ------------------------ doc/org.bluez.Battery.rst | 39 ++++++++++++++ doc/org.bluez.BatteryProvider.rst | 32 +++++++++++ doc/org.bluez.BatteryProviderManager.rst | 50 +++++++++++++++++ 5 files changed, 133 insertions(+), 75 deletions(-) delete mode 100644 doc/battery-api.txt create mode 100644 doc/org.bluez.Battery.rst create mode 100644 doc/org.bluez.BatteryProvider.rst create mode 100644 doc/org.bluez.BatteryProviderManager.rst diff --git a/Makefile.am b/Makefile.am index 0b62852a7a20..239d2da7bb05 100644 --- a/Makefile.am +++ b/Makefile.am @@ -361,7 +361,9 @@ man_MANS += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \ doc/org.bluez.DeviceSet.5 doc/org.bluez.AgentManager.5 \ doc/org.bluez.Agent.5 doc/org.bluez.ProfileManager.5 \ doc/org.bluez.Profile.5 doc/org.bluez.NetworkServer.5 \ - doc/org.bluez.Network.5 doc/org.bluez.Input.5 + doc/org.bluez.Network.5 doc/org.bluez.Input.5 \ + doc/org.bluez.BatteryProviderManager.5 \ + doc/org.bluez.BatteryProvider.5 doc/org.bluez.Battery.5 man_MANS += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \ doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \ doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \ @@ -378,7 +380,9 @@ manual_pages += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \ doc/org.bluez.DeviceSet.5 doc/org.bluez.AgentManager.5 \ doc/org.bluez.Agent.5 doc/org.bluez.ProfileManager.5 \ doc/org.bluez.Profile.5 doc/org.bluez.NetworkServer.5 \ - doc/org.bluez.Network.5 doc/org.bluez.Input.5 + doc/org.bluez.Network.5 doc/org.bluez.Input.5\ + doc/org.bluez.BatteryProviderManager.5 \ + doc/org.bluez.BatteryProvider.5 doc/org.bluez.Battery.5 manual_pages += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \ doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \ doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \ @@ -429,10 +433,12 @@ EXTRA_DIST += doc/mgmt-api.txt \ doc/sap-api.txt EXTRA_DIST += doc/org.bluez.Adapter.rst doc/org.bluez.Device.rst \ - doc/org.bluez.DeviceSet.rst doc/org.bluez.AgentManager.rst \ - doc/org.bluez.Agent.rst doc/org.bluez.ProfileManager.rst \ - doc/org.bluez.Profile.rst doc/org.bluez.NetworkServer.rst \ - doc/org.bluez.Network.rst doc/org.bluez.Input.rst + doc/org.bluez.DeviceSet.rst doc/org.bluez.AgentManager.rst \ + doc/org.bluez.Agent.rst doc/org.bluez.ProfileManager.rst \ + doc/org.bluez.Profile.rst doc/org.bluez.NetworkServer.rst \ + doc/org.bluez.Network.rst doc/org.bluez.Input.rst \ + doc/org.bluez.BatteryProviderManager.rst \ + doc/org.bluez.BatteryProvider.rst doc/org.bluez.Battery.rst EXTRA_DIST += doc/org.bluez.Media.rst doc/org.bluez.MediaControl.rst \ doc/org.bluez.MediaPlayer.rst doc/org.bluez.MediaFolder.rst \ diff --git a/doc/battery-api.txt b/doc/battery-api.txt deleted file mode 100644 index c03d64fc64b6..000000000000 --- a/doc/battery-api.txt +++ /dev/null @@ -1,69 +0,0 @@ -BlueZ D-Bus Battery API description -*********************************** - - -Battery hierarchy -================= - -Service org.bluez -Interface org.bluez.Battery1 -Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX - -Properties byte Percentage [readonly] - - The percentage of battery left as an unsigned 8-bit integer. - - string Source [readonly, optional] - - Describes where the battery information comes from - This property is informational only and may be useful - for debugging purposes. - Providers from BatteryProvider1 may make use of this - property to indicate where the battery report comes from - (e.g. "HFP 1.7", "HID", or the profile UUID). - - -Battery Provider Manager hierarchy -================================== -A battery provider starts by registering itself as a battery provider with the -RegisterBatteryProvider method passing an object path as the provider ID. Then, -it can start exposing org.bluez.BatteryProvider1 objects having the path -starting with the given provider ID. It can also remove objects at any time. -The objects and their properties exposed by battery providers will be reflected -on org.bluez.Battery1 interface. - -BlueZ will stop monitoring these exposed and removed objects after -UnregisterBatteryProvider is called for that provider ID. - -Service org.bluez -Interface org.bluez.BatteryProviderManager1 -Object path /org/bluez/{hci0,hci1,...} - -Methods void RegisterBatteryProvider(object provider) - - This registers a battery provider. A registered - battery provider can then expose objects with - org.bluez.BatteryProvider1 interface described below. - - void UnregisterBatteryProvider(object provider) - - This unregisters a battery provider. After - unregistration, the BatteryProvider1 objects provided - by this client are ignored by BlueZ. - - -Battery Provider hierarchy -========================== - -Service -Interface org.bluez.BatteryProvider1 -Object path {provider_root}/{unique battery object path} - -Properties Objects provided on this interface contain the same properties - as org.bluez.Battery1 interface. Additionally, this interface - needs to have the Device property indicating the object path - of the device this battery provides. - - object Device [readonly] - - The object path of the device that has this battery. diff --git a/doc/org.bluez.Battery.rst b/doc/org.bluez.Battery.rst new file mode 100644 index 000000000000..d7e903c496ec --- /dev/null +++ b/doc/org.bluez.Battery.rst @@ -0,0 +1,39 @@ +================= +org.bluez.Battery +================= + +------------------------------------- +BlueZ D-Bus Battery API documentation +------------------------------------- + +:Version: BlueZ +:Date: October 2023 +:Manual section: 5 +:Manual group: Linux System Administration + +Interface +========= + +:Service: org.bluez +:Interface: org.bluez.Battery1 +:Object path: [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX + +Properties +---------- + +byte Percentage [readonly] +`````````````````````````` + + The percentage of battery left as an unsigned 8-bit integer. + +string Source [readonly, optional] +`````````````````````````````````` + + Describes where the battery information comes from. + + This property is informational only and may be useful for debugging + purposes. + + Providers from **org.bluez.BatteryProvider(5)** may make use + of this property to indicate where the battery report comes from + (e.g. "HFP 1.7", "HID", or the profile UUID). diff --git a/doc/org.bluez.BatteryProvider.rst b/doc/org.bluez.BatteryProvider.rst new file mode 100644 index 000000000000..b8d8b1c2ddd0 --- /dev/null +++ b/doc/org.bluez.BatteryProvider.rst @@ -0,0 +1,32 @@ +========================= +org.bluez.BatteryProvider +========================= + +--------------------------------------------- +BlueZ D-Bus BatteryProvider API documentation +--------------------------------------------- + +:Version: BlueZ +:Date: October 2023 +:Manual section: 5 +:Manual group: Linux System Administration + +Interface +========= + +:Service: +:Interface: org.bluez.BatteryProvider1 +:Object path: {provider_root}/{unique battery object path} + +Properties +---------- + +Objects provided on this interface contain the same properties as +**org.bluez.Battery(5)** interface. Additionally, this interface needs to have +the Device property indicating the object path of the device this battery +provides. + +object Device [readonly] +```````````````````````` + + The object path of the device that has this battery. diff --git a/doc/org.bluez.BatteryProviderManager.rst b/doc/org.bluez.BatteryProviderManager.rst new file mode 100644 index 000000000000..ab5cf2d4cadc --- /dev/null +++ b/doc/org.bluez.BatteryProviderManager.rst @@ -0,0 +1,50 @@ +================================ +org.bluez.BatteryProviderManager +================================ + +---------------------------------------------------- +BlueZ D-Bus BatteryProviderManager API documentation +---------------------------------------------------- + +:Version: BlueZ +:Date: October 2023 +:Manual section: 5 +:Manual group: Linux System Administration + +Description +============ + +A battery provider starts by registering itself as a battery provider with the +**RegisterBatteryProvider()** method passing an object path as the provider ID. +Then, it can start exposing **org.bluez.BatteryProvider(5)** objects having the +path starting with the given provider ID. It can also remove objects at any +time. +The objects and their properties exposed by battery providers will be reflected +on **org.bluez.Battery(5)** interface. + +**bluetoothd(8)** will stop monitoring these exposed and removed objects after +UnregisterBatteryProvider is called for that provider ID. + +Interface +========= + +:Service: org.bluez +:Interface: org.bluez.BatteryProviderManager1 +:Object path: /org/bluez/{hci0,hci1,...} + +Methods +------- + +void RegisterBatteryProvider(object provider) +````````````````````````````````````````````` + + Registers a battery provider. A registered battery provider can then + expose objects with **org.bluez.BatteryProvider(5)** interface. + +void UnregisterBatteryProvider(object provider) +``````````````````````````````````````````````` + + Unregisters a battery provider previously registered with + **RegisterBatteryProvider()**. After unregistration, the + **org.bluez.BatteryProvider(5)** objects provided by this client are + ignored by **bluetoothd(8)**. From patchwork Mon Oct 9 23:29:32 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luiz Augusto von Dentz X-Patchwork-Id: 13414682 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id D619EE9413E for ; Mon, 9 Oct 2023 23:30:03 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1379133AbjJIXaC (ORCPT ); Mon, 9 Oct 2023 19:30:02 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:59976 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1379118AbjJIX36 (ORCPT ); Mon, 9 Oct 2023 19:29:58 -0400 Received: from mail-pl1-x62a.google.com (mail-pl1-x62a.google.com [IPv6:2607:f8b0:4864:20::62a]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 00268D3 for ; Mon, 9 Oct 2023 16:29:54 -0700 (PDT) Received: by mail-pl1-x62a.google.com with SMTP id d9443c01a7336-1c63164a2b6so44790825ad.0 for ; Mon, 09 Oct 2023 16:29:54 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1696894193; x=1697498993; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=MbKjzGfYFvrYz69Oh9xHak9Tm1bwzVG1Okvcmnq9mbQ=; b=C55mzXCywGd+3OSClnkH3A6lUYFvmeLO4zn8NACyrfl3K4vEb/AxvBvSQZhjb/2Tcc WrO+SvmXsnsYKOpIbrSqJi3F++BXH4pA0a8fGKMrUkYbHsbAC6WvtZ7O56vaGMlBQJu5 lZF+evLc6zoXcYVF6tXvgMxtxOAkugRAK+bZ2jxHcHKbO25m8Y5vdXXJYFfNxVmpgxy2 sm9Q4DoqMTZBXkKsLvkPQgxL7Zc5Mhu75qncX366wVSIfZHvnNKItBIklhpSKaHzS3Gi m2cu3TJg+ZxNE8IV9izbfvSvts+PbXCdCQ/IYmTsnDnsPtqXP+v1SZKo2GLvqHq2cyUT PBag== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1696894193; x=1697498993; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=MbKjzGfYFvrYz69Oh9xHak9Tm1bwzVG1Okvcmnq9mbQ=; b=nKp10qDC3dg1QCCc6PoQofccQ1fEHIQ5VuaK47eARZI7SjM6ciZVQYL2e1GyLUOwxl J8Rbwzn5ELBy2RGhs90wJCKC1yAHiRa0WMlwCUHb8Zb8jJ78ONc23enIq/EPpHJ9kL/U jZfLEbql9WWVJYyyOlDnWlYI4/mrHtFPKVGehpS9d8LBiIin7BeXMgFBV5TiFi+HJE/s u0AagnQUi64oKXAk5A+5Xy49piiWAQm9CLvkBaV19T8pgBlJF4krylbo3qYjNzY6kHyF /Chsm6pikw+/toPtu1jVte8F6/AKgpgmnFIhAIW6yUIX22sDN60R5RWC10uhOVlXw23I 7/mg== X-Gm-Message-State: AOJu0Yy6+qg6+VPjnPUWYqqaXBO/5vB0Vq/ebDGXkJ4SphAUdm6NR8kW yqwbr6xcJIyzFA2kbbY6OI0tzX4emD+g1YsS X-Google-Smtp-Source: AGHT+IGFdZgVfENn8XCUK4IvKjVqEiiYcmmlWqCnKO6pp6tmA/FEiw1qrynQb3HdHIXidDfGha5RrQ== X-Received: by 2002:a17:902:c404:b0:1c9:9fa6:ce5b with SMTP id k4-20020a170902c40400b001c99fa6ce5bmr4945303plk.16.1696894193172; Mon, 09 Oct 2023 16:29:53 -0700 (PDT) Received: from lvondent-mobl4.. (c-98-232-221-87.hsd1.or.comcast.net. [98.232.221.87]) by smtp.gmail.com with ESMTPSA id s20-20020a170902989400b001c5b8087fe5sm10182711plp.94.2023.10.09.16.29.51 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 09 Oct 2023 16:29:51 -0700 (PDT) From: Luiz Augusto von Dentz To: linux-bluetooth@vger.kernel.org Subject: [PATCH v2 10/11] doc/advertisement-monitor-api: Rename to org.bluez.AdvertisementMonitor*.rst Date: Mon, 9 Oct 2023 16:29:32 -0700 Message-ID: <20231009232933.500652-10-luiz.dentz@gmail.com> X-Mailer: git-send-email 2.41.0 In-Reply-To: <20231009232933.500652-1-luiz.dentz@gmail.com> References: <20231009232933.500652-1-luiz.dentz@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-bluetooth@vger.kernel.org From: Luiz Augusto von Dentz This renames advertisement-monitor-api.txt to org.bluez.AdvertisementMonitor*.rst and generate manpages org.bluez.AdvertisementMonitor*.5. --- Makefile.am | 12 +- doc/advertisement-monitor-api.txt | 187 ------------------ doc/org.bluez.AdvertisementMonitor.rst | 153 ++++++++++++++ doc/org.bluez.AdvertisementMonitorManager.rst | 90 +++++++++ 4 files changed, 252 insertions(+), 190 deletions(-) delete mode 100644 doc/advertisement-monitor-api.txt create mode 100644 doc/org.bluez.AdvertisementMonitor.rst create mode 100644 doc/org.bluez.AdvertisementMonitorManager.rst diff --git a/Makefile.am b/Makefile.am index 239d2da7bb05..ae44937a50e1 100644 --- a/Makefile.am +++ b/Makefile.am @@ -373,7 +373,9 @@ man_MANS += doc/org.bluez.GattManager.5 doc/org.bluez.GattProfile.5 \ doc/org.bluez.GattCharacteristic.5 \ doc/org.bluez.GattDescriptor.5 \ doc/org.bluez.LEAdvertisingManager.5 \ - doc/org.bluez.LEAdvertisement.5 + doc/org.bluez.LEAdvertisement.5 \ + doc/org.bluez.AdvertisementMonitorManager.5 \ + doc/org.bluez.AdvertisementMonitor.5 endif manual_pages += src/bluetoothd.8 manual_pages += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \ @@ -392,7 +394,9 @@ manual_pages += doc/org.bluez.GattManager.5 doc/org.bluez.GattProfile.5 \ doc/org.bluez.GattCharacteristic.5 \ doc/org.bluez.GattDescriptor.5 \ doc/org.bluez.LEAdvertisingManager.5 \ - doc/org.bluez.LEAdvertisement.5 + doc/org.bluez.LEAdvertisement.5 \ + doc/org.bluez.AdvertisementMonitorManager.5 \ + doc/org.bluez.AdvertisementMonitor.5 EXTRA_DIST += src/genbuiltin src/bluetooth.conf \ src/main.conf profiles/network/network.conf \ @@ -450,7 +454,9 @@ EXTRA_DIST += doc/org.bluez.GattManager.rst doc/org.bluez.GattProfile.rst\ doc/org.bluez.GattCharacteristic.rst \ doc/org.bluez.GattDescriptor.rst \ doc/org.bluez.LEAdvertisingManager.rst \ - doc/org.bluez.LEAdvertisement.rst + doc/org.bluez.LEAdvertisement.rst \ + doc/org.bluez.AdvertisementMonitorManager.rst \ + doc/org.bluez.AdvertisementMonitor.rst EXTRA_DIST += doc/obex-api.txt doc/obex-agent-api.txt diff --git a/doc/advertisement-monitor-api.txt b/doc/advertisement-monitor-api.txt deleted file mode 100644 index 9189f2cceb96..000000000000 --- a/doc/advertisement-monitor-api.txt +++ /dev/null @@ -1,187 +0,0 @@ -BlueZ D-Bus Advertisement Monitor API Description -************************************************* - -This API allows an client to specify a job of monitoring advertisements by -registering the root of hierarchy and then exposing advertisement monitors -under the root with filtering conditions, thresholds of RSSI and timers -of RSSI thresholds. - -Once a monitoring job is activated by BlueZ, the client can expect to get -notified on the targeted advertisements no matter if there is an ongoing -discovery session (a discovery session is started/stopped with methods in -org.bluez.Adapter1 interface). - -Advertisement Monitor hierarchy -=============================== -Service org.bluez -Interface org.bluez.AdvertisementMonitor1 [experimental] -Object path freely definable - -Methods void Release() [noreply] - - This gets called as a signal for a client to perform - clean-up when (1)a monitor cannot be activated after it - was exposed or (2)a monitor has been deactivated. - - void Activate() [noreply] - - After a monitor was exposed, this gets called as a - signal for client to get acknowledged when a monitor - has been activated, so the client can expect to receive - calls on DeviceFound() or DeviceLost(). - - void DeviceFound(object device) [noreply] - - This gets called to notify the client of finding the - targeted device. Once receiving the call, the client - should start to monitor the corresponding device to - retrieve the changes on RSSI and advertisement content. - - void DeviceLost(object device) [noreply] - - This gets called to notify the client of losing the - targeted device. Once receiving this call, the client - should stop monitoring the corresponding device. - -Properties string Type [read-only] - - The type of the monitor. See SupportedMonitorTypes in - org.bluez.AdvertisementMonitorManager1 for the available - options. - - Int16 RSSILowThreshold [read-only, optional] - - Used in conjunction with RSSILowTimeout to determine - whether a device becomes out-of-range. Valid range is - -127 to 20 (dBm), while 127 indicates unset. - - Int16 RSSIHighThreshold [read-only, optional] - - Used in conjunction with RSSIHighTimeout to determine - whether a device becomes in-range. Valid range is - -127 to 20 (dBm), while 127 indicates unset. - - Uint16 RSSILowTimeout [read-only, optional] - - The time it takes to consider a device as out-of-range. - If this many seconds elapses without receiving any - signal at least as strong as RSSILowThreshold, a - currently in-range device will be considered as - out-of-range (lost). Valid range is 1 to 300 (seconds), - while 0 indicates unset. - - Uint16 RSSIHighTimeout [read-only, optional] - - The time it takes to consider a device as in-range. - If this many seconds elapses while we continuously - receive signals at least as strong as RSSIHighThreshold, - a currently out-of-range device will be considered as - in-range (found). Valid range is 1 to 300 (seconds), - while 0 indicates unset. - - Uint16 RSSISamplingPeriod [read-only, optional] - - Grouping rules on how to propagate the received - advertisement packets to the client. Valid range is 0 to - 255 while 256 indicates unset. - - The meaning of this property is as follows: - 0: - All advertisement packets from in-range devices - would be propagated. - 255: - Only the first advertisement packet of in-range - devices would be propagated. If the device - becomes lost, then the first packet when it is - found again will also be propagated. - 1 to 254: - Advertisement packets would be grouped into - 100ms * N time period. Packets in the same group - will only be reported once, with the RSSI value - being averaged out. - - Currently this is unimplemented in user space, so the - value is only used to be forwarded to the kernel. - - array{(uint8, uint8, array{byte})} Patterns [read-only, optional] - - If the Type property is set to "or_patterns", then this - property must exist and have at least one entry in the - array. - - The structure of a pattern contains the following: - uint8 start_position - The index in an AD data field where the search - should start. The beginning of an AD data field - is index 0. - uint8 AD_data_type - See https://www.bluetooth.com/specifications/ - assigned-numbers/generic-access-profile/ for - the possible allowed value. - array{byte} content_of_pattern - This is the value of the pattern. The maximum - length of the bytes is 31. - -Advertisement Monitor Manager hierarchy -======================================= -Service org.bluez -Interface org.bluez.AdvertisementMonitorManager1 [experimental] -Object path /org/bluez/{hci0,hci1,...} - -Methods void RegisterMonitor(object application) - - 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 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 - -Properties array{string} SupportedMonitorTypes [read-only] - - This lists the supported types of advertisement - monitors. An application should check this before - instantiate and expose an object of - org.bluez.AdvertisementMonitor1. - - Possible values for monitor types: - - "or_patterns" - Patterns with logic OR applied. With this type, - property "Patterns" must exist and has at least - one pattern. - - array{string} SupportedFeatures [read-only] - - This lists the features of advertisement monitoring - supported by BlueZ. - - Possible values for features: - - "controller-patterns" - If the controller is capable of performing - advertisement monitoring by patterns, BlueZ - would offload the patterns to the controller to - reduce power consumption. diff --git a/doc/org.bluez.AdvertisementMonitor.rst b/doc/org.bluez.AdvertisementMonitor.rst new file mode 100644 index 000000000000..98852ac68b59 --- /dev/null +++ b/doc/org.bluez.AdvertisementMonitor.rst @@ -0,0 +1,153 @@ +============================== +org.bluez.AdvertisementMonitor +============================== + +-------------------------------------------------- +BlueZ D-Bus AdvertisementMonitor API documentation +-------------------------------------------------- + +:Version: BlueZ +:Date: October 2023 +:Manual section: 5 +:Manual group: Linux System Administration + +Description +=========== + +This API allows an client to specify a job of monitoring advertisements by +registering the root of hierarchy and then exposing advertisement monitors +under the root with filtering conditions, thresholds of RSSI and timers +of RSSI thresholds. + +Once a monitoring job is activated by **bluetoothd(8)**, the client can expect +to get notified on the targeted advertisements no matter if there is an ongoing +discovery session (see **StartDiscovery()** in **org.bluez.Adapter(5)**). + +Interface +========= + +:Service: org.bluez +:Interface: org.bluez.AdvertisementMonitor1 [experimental] +:Object path: freely definable + +Methods +------- + +void Release() [noreply] +```````````````````````` + + This gets called as a signal for a client to perform clean-up when: + + - Monitor cannot be activated after it was exposed + - Monitor has been deactivated. + +void Activate() [noreply] +````````````````````````` + + After a monitor was exposed, this gets called as a signal for client to + get acknowledged when a monitor has been activated, so the client can + expect to receive calls on **DeviceFound()** or **DeviceLost()**. + +void DeviceFound(object device) [noreply] +````````````````````````````````````````` + + This gets called to notify the client of finding the targeted device. + Once receiving the call, the client should start to monitor the + corresponding device to retrieve the changes on RSSI and advertisement + content. + +void DeviceLost(object device) [noreply] +```````````````````````````````````````` + + This gets called to notify the client of losing the targeted device. + Once receiving this call, the client should stop monitoring the + corresponding device. + +Properties +---------- + +string Type [read-only] +``````````````````````` + + The type of the monitor. See **SupportedMonitorTypes** in + **org.bluez.AdvertisementMonitorManager(5)** for the available options. + +int16 RSSILowThreshold [read-only, optional] +```````````````````````````````````````````` + + Used in conjunction with **RSSILowTimeout** to determine whether a + device becomes out-of-range. Valid range is -127 to 20 (dBm), while 127 + indicates unset. + +int16 RSSIHighThreshold [read-only, optional] +````````````````````````````````````````````` + + Used in conjunction with RSSIHighTimeout to determine whether a device + becomes in-range. Valid range is -127 to 20 (dBm), while 127 indicates + unset. + +uint16 RSSILowTimeout [read-only, optional] +``````````````````````````````````````````` + + The time it takes to consider a device as out-of-range. If this many + seconds elapses without receiving any signal at least as strong as + **RSSILowThreshold**, a currently in-range device will be considered as + out-of-range (lost). Valid range is 1 to 300 (seconds), while 0 + indicates unset. + +uint16 RSSIHighTimeout [read-only, optional] +```````````````````````````````````````````` + + The time it takes to consider a device as in-range. If this many + seconds elapses while we continuouslyreceive signals at least as strong + as **RSSIHighThreshold**, a currently out-of-range device will be + considered as in-range (found). Valid range is 1 to 300 (seconds), + while 0 indicates unset. + +uint16 RSSISamplingPeriod [read-only, optional] +``````````````````````````````````````````````` + + Grouping rules on how to propagate the received advertisement packets + to the client. + + Possible values: + + :0: + All advertisement packets from in-range devices would be + propagated. + + :255: + Only the first advertisement packet of in-range devices would + be propagated. If the device becomes lost, then the first + packet when it is found again will also be propagated. + + :1 to 254: + Advertisement packets would be grouped into 100ms * N time + period. Packets in the same group will only be reported once, + with the RSSI value being averaged out. + + Currently this is unimplemented in user space, so the value is only + used to be forwarded to the kernel. + +array{(uint8, uint8, array{byte})} Patterns [read-only, optional] +````````````````````````````````````````````````````````````````` + + If the **Type** property is set to **"or_patterns"**, then this + property must exist and have at least one entry in the array. + + The structure of a pattern contains the following: + + :uint8 start_position: + + The index in an AD data field where the search hould start. The + beginning of an AD data field is index 0. + + :uint8 AD_data_type: + + See https://www.bluetooth.com/specifications/assigned-numbers/ + generic-access-profile/ for the possible allowed value. + + :array{byte} content_of_pattern: + + This is the value of the pattern. The maximum length of the + bytes is 31. diff --git a/doc/org.bluez.AdvertisementMonitorManager.rst b/doc/org.bluez.AdvertisementMonitorManager.rst new file mode 100644 index 000000000000..3775a483543c --- /dev/null +++ b/doc/org.bluez.AdvertisementMonitorManager.rst @@ -0,0 +1,90 @@ +===================================== +org.bluez.AdvertisementMonitorManager +===================================== + +--------------------------------------------------------- +BlueZ D-Bus AdvertisementMonitorManager API documentation +--------------------------------------------------------- + +:Version: BlueZ +:Date: October 2023 +:Manual section: 5 +:Manual group: Linux System Administration + +Interface +========= + +Service org.bluez +Interface org.bluez.AdvertisementMonitorManager1 [experimental] +Object path /org/bluez/{hci0,hci1,...} + +Methods +------- + +void RegisterMonitor(object application) +```````````````````````````````````````` + + Registers the root path of a hierarchy of advertisement monitors + implementing **org.bluez.AdvertisementMonitor(5)**. + + The application object path together with the D-Bus ystem 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) +`````````````````````````````````````````` + + Unregisters a hierarchy of advertisement monitors that has been + previously registered with **RegisterMonitor()**. 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: + +Properties +---------- + +array{string} SupportedMonitorTypes [read-only] +``````````````````````````````````````````````` + + This lists the supported types of advertisement monitors. An application + should check this before instantiate and expose an object of + **org.bluez.AdvertisementMonitor(5)**. + + Possible values: + + :"or_patterns": + + Patterns with logic OR applied. With this type, property + **Patterns** must exist and has at least one pattern. + +array{string} SupportedFeatures [read-only] +``````````````````````````````````````````` + + This lists the features of advertisement monitoring supported by + **bluetoothd(8)**. + + Possible values: + + :"controller-patterns": + + If the controller is capable of performing advertisement + monitoring by patterns, **bluetoothd(8)** would offload the + patterns to the controller to reduce power consumption. From patchwork Mon Oct 9 23:29:33 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luiz Augusto von Dentz X-Patchwork-Id: 13414684 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 7E5B2E95A8D for ; Mon, 9 Oct 2023 23:30:04 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1379075AbjJIXaE (ORCPT ); Mon, 9 Oct 2023 19:30:04 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:59922 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1379129AbjJIX37 (ORCPT ); Mon, 9 Oct 2023 19:29:59 -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 BDB29DE for ; Mon, 9 Oct 2023 16:29:56 -0700 (PDT) Received: by mail-pf1-x431.google.com with SMTP id d2e1a72fcca58-690bccb0d8aso3880822b3a.0 for ; Mon, 09 Oct 2023 16:29:56 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1696894195; x=1697498995; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=rBUIXIG+BJH55FBylamGiHVWsy/rkPIgFVY7SqMzynU=; b=XdSmYqP4RFgFcbHx0pDs1FAKR5egOZL2QjY4YxbnKQdXuR1MfbhYkh/YU6wKE0IECs XKMg/zpHjtHRgaPKEIwgFnTllD1vUxizi6eBik6Cvfe3o1e2zAbGj5f+dJNQWdLVVbl2 w7YnlFrAApNEICz3yN5YN+s0qMrioxKvZoF8cEiqzTNoZ8ijKzYvMYnysLKROJ6xMJV8 SLsjes/j0LWYp+mcMYEm/x1sxLQuEUOXVGL3TRWo7ej8GN8v3yIP/giUk/EMgCjJCZer ughujcpey4ymimLRzrIuvPGvA4eK7lYmaPiP8hMwxcXkqMc4FkcLRXgv6u1Mr/5Cy1LQ EFqA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1696894195; x=1697498995; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=rBUIXIG+BJH55FBylamGiHVWsy/rkPIgFVY7SqMzynU=; b=a5pgvIbRGK8DmGPa3SgjNPXySA/fj1zQj/jSPpzLwrupBO2KybgWF+Uw2CjfcMThtp o9a2LvS6N6iYNNL04Y5gzue7P07fU1cuPjQUDY6pcU23cJaNV4knPh0MGSpK6WsDn5ko tPHbzFk2i1VX+8Pj16MermweFhF6gioOcO9DciHqk5kiTQMA2SfZdngimw/ev4uzoJZc kZTG9UtrZpCI22/w+wJSkgT48CUXQi5/qGc3c3PQsifiZIrmw9ipXYGRfMI2ANKwQqvO w2v08+XWAkHiufsctnjWpfNXA9sMGCtX4mgnYu50mTkBCzKG6VSlDxNwpiIGYiaIDZVT IuFw== X-Gm-Message-State: AOJu0Yz2JNZ4a44NWphGeHywGCN/3/RrT5CteymOk4yLK/1Mj0J63b76 S/gHVtQ8X7uOw/sQ8Mk+y8HGhubCgKT2HaB5 X-Google-Smtp-Source: AGHT+IEf2u6xpkbNeVPlrVh9jRBokOH8OeYhcTopvz0F6b4GoXk6GlFWzVoJEdhtH/LzDZAaDRBAHA== X-Received: by 2002:a05:6a20:ce90:b0:15e:a8:6bb4 with SMTP id if16-20020a056a20ce9000b0015e00a86bb4mr13596164pzb.8.1696894195258; Mon, 09 Oct 2023 16:29:55 -0700 (PDT) Received: from lvondent-mobl4.. (c-98-232-221-87.hsd1.or.comcast.net. [98.232.221.87]) by smtp.gmail.com with ESMTPSA id s20-20020a170902989400b001c5b8087fe5sm10182711plp.94.2023.10.09.16.29.53 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 09 Oct 2023 16:29:54 -0700 (PDT) From: Luiz Augusto von Dentz To: linux-bluetooth@vger.kernel.org Subject: [PATCH v2 11/11] doc/admin-policy-api: Rename to org.bluez.AdminPolicy*.rst Date: Mon, 9 Oct 2023 16:29:33 -0700 Message-ID: <20231009232933.500652-11-luiz.dentz@gmail.com> X-Mailer: git-send-email 2.41.0 In-Reply-To: <20231009232933.500652-1-luiz.dentz@gmail.com> References: <20231009232933.500652-1-luiz.dentz@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-bluetooth@vger.kernel.org From: Luiz Augusto von Dentz This renames admin-policy-api.txt to org.bluez.AdminPolicy*.rst and generate manpages org.bluez.AdminPolicy*.5. --- Makefile.am | 12 ++++-- doc/admin-policy-api.txt | 65 ----------------------------- doc/org.bluez.AdminPolicySet.rst | 52 +++++++++++++++++++++++ doc/org.bluez.AdminPolicyStatus.rst | 49 ++++++++++++++++++++++ 4 files changed, 110 insertions(+), 68 deletions(-) delete mode 100644 doc/admin-policy-api.txt create mode 100644 doc/org.bluez.AdminPolicySet.rst create mode 100644 doc/org.bluez.AdminPolicyStatus.rst diff --git a/Makefile.am b/Makefile.am index ae44937a50e1..53dd12615560 100644 --- a/Makefile.am +++ b/Makefile.am @@ -363,7 +363,9 @@ man_MANS += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \ doc/org.bluez.Profile.5 doc/org.bluez.NetworkServer.5 \ doc/org.bluez.Network.5 doc/org.bluez.Input.5 \ doc/org.bluez.BatteryProviderManager.5 \ - doc/org.bluez.BatteryProvider.5 doc/org.bluez.Battery.5 + doc/org.bluez.BatteryProvider.5 doc/org.bluez.Battery.5 \ + doc/org.bluez.AdminPolicySet.5 \ + doc/org.bluez.AdminPolicyStatus.5 man_MANS += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \ doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \ doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \ @@ -384,7 +386,9 @@ manual_pages += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \ doc/org.bluez.Profile.5 doc/org.bluez.NetworkServer.5 \ doc/org.bluez.Network.5 doc/org.bluez.Input.5\ doc/org.bluez.BatteryProviderManager.5 \ - doc/org.bluez.BatteryProvider.5 doc/org.bluez.Battery.5 + doc/org.bluez.BatteryProvider.5 doc/org.bluez.Battery.5 \ + doc/org.bluez.AdminPolicySet.5 \ + doc/org.bluez.AdminPolicyStatus.5 manual_pages += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \ doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \ doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \ @@ -442,7 +446,9 @@ EXTRA_DIST += doc/org.bluez.Adapter.rst doc/org.bluez.Device.rst \ doc/org.bluez.Profile.rst doc/org.bluez.NetworkServer.rst \ doc/org.bluez.Network.rst doc/org.bluez.Input.rst \ doc/org.bluez.BatteryProviderManager.rst \ - doc/org.bluez.BatteryProvider.rst doc/org.bluez.Battery.rst + doc/org.bluez.BatteryProvider.rst doc/org.bluez.Battery.rst \ + doc/org.bluez.AdminPolicySet.rst \ + doc/org.bluez.AdminPolicyStatus.rst EXTRA_DIST += doc/org.bluez.Media.rst doc/org.bluez.MediaControl.rst \ doc/org.bluez.MediaPlayer.rst doc/org.bluez.MediaFolder.rst \ diff --git a/doc/admin-policy-api.txt b/doc/admin-policy-api.txt deleted file mode 100644 index 3f116901dbd7..000000000000 --- a/doc/admin-policy-api.txt +++ /dev/null @@ -1,65 +0,0 @@ -BlueZ D-Bus Admin Policy API description -*********************************** - -This API provides methods to control the behavior of bluez as an administrator. - -Interface AdminPolicySet1 provides methods to set policies. Once the policy is -set successfully, it will affect all clients and stay persistently even after -restarting Bluetooth Daemon. The only way to clear it is to overwrite the -policy with the same method. - -Interface AdminPolicyStatus1 provides readonly properties to indicate the -current values of admin policy. - - -Admin Policy Set hierarchy -================= - -Service org.bluez -Interface org.bluez.AdminPolicySet1 -Object path [variable prefix]/{hci0,hci1,...} - -Methods void SetServiceAllowList(array{string} UUIDs) - - This method sets the service allowlist by specifying - service UUIDs. - - When SetServiceAllowList is called, bluez will block - incoming and outgoing connections to the service not in - UUIDs for all of the clients. - - Any subsequent calls to this method will supersede any - previously set allowlist values. Calling this method - with an empty array will allow any service UUIDs to be - used. - - The default value is an empty array. - - Possible errors: org.bluez.Error.InvalidArguments - org.bluez.Error.Failed - - -Admin Policy Status hierarchy -================= - -Service org.bluez -Interface org.bluez.AdminPolicyStatus1 -Object path [variable prefix]/{hci0,hci1,...} - -Properties array{string} ServiceAllowList [readonly] - - Current value of service allow list. - - - -Admin Policy Status hierarchy -================= - -Service org.bluez -Interface org.bluez.AdminPolicyStatus1 -Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX - -Properties bool IsAffectedByPolicy [readonly] - - Indicate if there is any auto-connect profile in this - device is not allowed by admin policy. diff --git a/doc/org.bluez.AdminPolicySet.rst b/doc/org.bluez.AdminPolicySet.rst new file mode 100644 index 000000000000..7ce4efcfed99 --- /dev/null +++ b/doc/org.bluez.AdminPolicySet.rst @@ -0,0 +1,52 @@ +======================== +org.bluez.AdminPolicySet +======================== + +-------------------------------------------- +BlueZ D-Bus AdminPolicySet API documentation +-------------------------------------------- + +:Version: BlueZ +:Date: October 2023 +:Manual section: 5 +:Manual group: Linux System Administration + +Description +============ + +This API provides methods to control the behavior of **bluetoothd(8)** as an +administrator. + +Interface AdminPolicySet1 provides methods to set policies. Once the policy is +set successfully, it will affect all clients and stay persistently even after +restarting **bluetoothd(8)**. The only way to clear it is to overwrite the +policy with the same method. + +Interface +========= + +:Service: org.bluez +:Interface: org.bluez.AdminPolicySet1 [experimental] +:Object path: [variable prefix]/{hci0,hci1,...} + +Methods +------- + +void SetServiceAllowList(array{string} UUIDs) +````````````````````````````````````````````` + + Sets the service allowlist by specifying service UUIDs. + + When called, **bluetoothd(8)** will block incoming and outgoing + connections to the service not in UUIDs for all of the clients. + + Any subsequent calls to this method will supersede any previously set + allowlist values. Calling this method with an empty array will allow + any service UUIDs to be used. + + The default value is an empty array. + + Possible errors: + + :org.bluez.Error.InvalidArguments: + :org.bluez.Error.Failed: diff --git a/doc/org.bluez.AdminPolicyStatus.rst b/doc/org.bluez.AdminPolicyStatus.rst new file mode 100644 index 000000000000..ad2dc58dec0a --- /dev/null +++ b/doc/org.bluez.AdminPolicyStatus.rst @@ -0,0 +1,49 @@ +=========================== +org.bluez.AdminPolicyStatus +=========================== + +----------------------------------------------- +BlueZ D-Bus AdminPolicyStatus API documentation +----------------------------------------------- + +:Version: BlueZ +:Date: October 2023 +:Manual section: 5 +:Manual group: Linux System Administration + +Description +=========== + +Interface AdminPolicyStatus1 provides readonly properties to indicate the +current values of admin policy affecting the Adapter and Device objects. + +Interface +========= + +Adapter +------- + +:Service: org.bluez +:Interface: org.bluez.AdminPolicyStatus1 [experimental] +:Object path: [variable prefix]/{hci0,hci1,...} + +Device +------ + +:Service: org.bluez +:Interface: org.bluez.AdminPolicyStatus1 [experimental] +:Object path: [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX + +Properties +---------- + +array{string} ServiceAllowList [readonly, adapter-only] +``````````````````````````````````````````````````````` + + Current value of service allow list. + +bool IsAffectedByPolicy [readonly, device-only] +``````````````````````````````````````````````` + + Indicate if there is any auto-connect profile in this device is not + allowed by admin policy.