LCOV - code coverage report
Current view: top level - zephyr/bluetooth/audio - csip.h Coverage Total Hit
Test: new.info Lines: 100.0 % 72 72
Test Date: 2025-09-05 20:47:19

            Line data    Source code
       1            1 : /**
       2              :  * @file
       3              :  * @brief Bluetooth Coordinated Set Identification Profile (CSIP) APIs.
       4              :  */
       5              : 
       6              : /*
       7              :  * Copyright (c) 2021-2024 Nordic Semiconductor ASA
       8              :  *
       9              :  * SPDX-License-Identifier: Apache-2.0
      10              :  */
      11              : 
      12              : #ifndef ZEPHYR_SUBSYS_BLUETOOTH_AUDIO_CSIP_H_
      13              : #define ZEPHYR_SUBSYS_BLUETOOTH_AUDIO_CSIP_H_
      14              : 
      15              : /**
      16              :  * @brief Coordinated Set Identification Profile (CSIP)
      17              :  *
      18              :  * @defgroup bt_csip Coordinated Set Identification Profile (CSIP)
      19              :  *
      20              :  * @since 3.0
      21              :  * @version 0.8.0
      22              :  *
      23              :  * @ingroup bluetooth
      24              :  * @{
      25              :  *
      26              :  * The Coordinated Set Identification Profile (CSIP) provides procedures to discover and coordinate
      27              :  * sets of devices.
      28              :  */
      29              : 
      30              : #include <stdbool.h>
      31              : #include <stddef.h>
      32              : #include <stdint.h>
      33              : 
      34              : #include <zephyr/autoconf.h>
      35              : #include <zephyr/bluetooth/addr.h>
      36              : #include <zephyr/bluetooth/bluetooth.h>
      37              : #include <zephyr/bluetooth/conn.h>
      38              : #include <zephyr/bluetooth/gap.h>
      39              : #include <zephyr/kernel.h>
      40              : #include <zephyr/sys/slist.h>
      41              : 
      42              : #ifdef __cplusplus
      43              : extern "C" {
      44              : #endif
      45              : 
      46              : /** Recommended timer for member discovery */
      47            1 : #define BT_CSIP_SET_COORDINATOR_DISCOVER_TIMER_VALUE        K_SECONDS(10)
      48              : 
      49              : /**
      50              :  * Defines the maximum number of Coordinated Set Identification service instances for the
      51              :  * Coordinated Set Identification Set Coordinator
      52              :  */
      53              : #if defined(CONFIG_BT_CSIP_SET_COORDINATOR)
      54              : #define BT_CSIP_SET_COORDINATOR_MAX_CSIS_INSTANCES CONFIG_BT_CSIP_SET_COORDINATOR_MAX_CSIS_INSTANCES
      55              : #else
      56            1 : #define BT_CSIP_SET_COORDINATOR_MAX_CSIS_INSTANCES 0
      57              : #endif /* CONFIG_BT_CSIP_SET_COORDINATOR */
      58              : 
      59              : /** Accept the request to read the SIRK as plaintext */
      60            1 : #define BT_CSIP_READ_SIRK_REQ_RSP_ACCEPT        0x00
      61              : /** Accept the request to read the SIRK, but return encrypted SIRK */
      62            1 : #define BT_CSIP_READ_SIRK_REQ_RSP_ACCEPT_ENC    0x01
      63              : /** Reject the request to read the SIRK */
      64            1 : #define BT_CSIP_READ_SIRK_REQ_RSP_REJECT        0x02
      65              : /** SIRK is available only via an OOB procedure */
      66            1 : #define BT_CSIP_READ_SIRK_REQ_RSP_OOB_ONLY      0x03
      67              : 
      68              : /** Size of the Set Identification Resolving Key (SIRK) */
      69            1 : #define BT_CSIP_SIRK_SIZE 16
      70              : 
      71              : /** Size of the Resolvable Set Identifier (RSI) */
      72            1 : #define BT_CSIP_RSI_SIZE                        6
      73              : 
      74              : /* Coordinate Set Identification Service Error codes */
      75              : /** Service is already locked */
      76            1 : #define BT_CSIP_ERROR_LOCK_DENIED               0x80
      77              : /** Service is not locked */
      78            1 : #define BT_CSIP_ERROR_LOCK_RELEASE_DENIED       0x81
      79              : /** Invalid lock value */
      80            1 : #define BT_CSIP_ERROR_LOCK_INVAL_VALUE          0x82
      81              : /** SIRK only available out-of-band */
      82            1 : #define BT_CSIP_ERROR_SIRK_OOB_ONLY             0x83
      83              : /** Client is already owner of the lock */
      84            1 : #define BT_CSIP_ERROR_LOCK_ALREADY_GRANTED      0x84
      85              : 
      86              : /**
      87              :  * @brief Helper to declare bt_data array including RSI
      88              :  *
      89              :  * This macro is mainly for creating an array of struct bt_data
      90              :  * elements which is then passed to e.g. @ref bt_le_ext_adv_start().
      91              :  *
      92              :  * @param _rsi Pointer to the RSI value
      93              :  */
      94            1 : #define BT_CSIP_DATA_RSI(_rsi) BT_DATA(BT_DATA_CSIS_RSI, _rsi, BT_CSIP_RSI_SIZE)
      95              : 
      96              : /** @brief Opaque Coordinated Set Identification Service instance. */
      97              : struct bt_csip_set_member_svc_inst;
      98              : 
      99              : /** Callback structure for the Coordinated Set Identification Service */
     100            1 : struct bt_csip_set_member_cb {
     101              :         /**
     102              :          * @brief Callback whenever the lock changes on the server.
     103              :          *
     104              :          * @param conn      The connection to the client that changed the lock.
     105              :          *                  NULL if server changed it, either by calling
     106              :          *                  bt_csip_set_member_lock() or by timeout.
     107              :          * @param svc_inst  Pointer to the Coordinated Set Identification
     108              :          *                  Service.
     109              :          * @param locked    Whether the lock was locked or released.
     110              :          *
     111              :          */
     112            1 :         void (*lock_changed)(struct bt_conn *conn,
     113              :                              struct bt_csip_set_member_svc_inst *svc_inst,
     114              :                              bool locked);
     115              : 
     116              :         /**
     117              :          * @brief Request from a peer device to read the sirk.
     118              :          *
     119              :          * If this callback is not set, all clients will be allowed to read
     120              :          * the SIRK unencrypted.
     121              :          *
     122              :          * @param conn      The connection to the client that requested to read
     123              :          *                  the SIRK.
     124              :          * @param svc_inst  Pointer to the Coordinated Set Identification
     125              :          *                  Service.
     126              :          *
     127              :          * @return A BT_CSIP_READ_SIRK_REQ_RSP_* response code.
     128              :          */
     129            1 :         uint8_t (*sirk_read_req)(struct bt_conn *conn,
     130              :                                  struct bt_csip_set_member_svc_inst *svc_inst);
     131              : };
     132              : 
     133              : /** Register structure for Coordinated Set Identification Service */
     134            1 : struct bt_csip_set_member_register_param {
     135              :         /**
     136              :          * @brief Size of the set.
     137              :          *
     138              :          * If set to 0, the set size characteristic won't be initialized.
     139              :          */
     140            1 :         uint8_t set_size;
     141              : 
     142              :         /**
     143              :          * @brief The unique Set Identity Resolving Key (SIRK)
     144              :          *
     145              :          * This shall be unique between different sets, and shall be the same
     146              :          * for each set member for each set.
     147              :          */
     148            1 :         uint8_t sirk[BT_CSIP_SIRK_SIZE];
     149              : 
     150              :         /**
     151              :          * @brief Boolean to set whether the set is lockable by clients
     152              :          *
     153              :          * Setting this to false will disable the lock characteristic.
     154              :          */
     155            1 :         bool lockable;
     156              : 
     157              :         /**
     158              :          * @brief Rank of this device in this set.
     159              :          *
     160              :          * If the lockable parameter is set to true, this shall be > 0 and
     161              :          * <= to the set_size. If the lockable parameter is set to false, this
     162              :          * may be set to 0 to disable the rank characteristic.
     163              :          */
     164            1 :         uint8_t rank;
     165              : 
     166              :         /** Pointer to the callback structure. */
     167            1 :         struct bt_csip_set_member_cb *cb;
     168              : 
     169              : #if CONFIG_BT_CSIP_SET_MEMBER_MAX_INSTANCE_COUNT > 1 || defined(__DOXYGEN__)
     170              :         /**
     171              :          * @brief Parent service pointer
     172              :          *
     173              :          * Mandatory parent service pointer if this CSIS instance is included
     174              :          * by another service. All CSIS instances when
     175              :          * @kconfig{CONFIG_BT_CSIP_SET_MEMBER_MAX_INSTANCE_COUNT} is above 1
     176              :          * shall be included by another service, as per the
     177              :          * Coordinated Set Identification Profile (CSIP).
     178              :          */
     179            1 :         const struct bt_gatt_service *parent;
     180              : #endif /* CONFIG_BT_CSIP_SET_MEMBER_MAX_INSTANCE_COUNT > 1 */
     181              : };
     182              : 
     183              : /**
     184              :  * @brief Get the service declaration attribute.
     185              :  *
     186              :  * The first service attribute can be included in any other GATT service.
     187              :  *
     188              :  * @param svc_inst   Pointer to the Coordinated Set Identification Service.
     189              :  *
     190              :  * @return The first CSIS attribute instance.
     191              :  */
     192            1 : void *bt_csip_set_member_svc_decl_get(const struct bt_csip_set_member_svc_inst *svc_inst);
     193              : 
     194              : /**
     195              :  * @brief Register a Coordinated Set Identification Service instance.
     196              :  *
     197              :  * This will register and enable the service and make it discoverable by
     198              :  * clients.
     199              :  *
     200              :  * This shall only be done as a server.
     201              :  *
     202              :  * @param      param     Coordinated Set Identification Service register
     203              :  *                       parameters.
     204              :  * @param[out] svc_inst  Pointer to the registered Coordinated Set
     205              :  *                       Identification Service.
     206              :  *
     207              :  * @return 0 if success, errno on failure.
     208              :  */
     209            1 : int bt_csip_set_member_register(const struct bt_csip_set_member_register_param *param,
     210              :                                 struct bt_csip_set_member_svc_inst **svc_inst);
     211              : 
     212              : /**
     213              :  * @brief Unregister a Coordinated Set Identification Service instance.
     214              :  *
     215              :  * This will unregister and disable the service instance.
     216              :  *
     217              :  * @param svc_inst  Pointer to the registered Coordinated Set Identification Service.
     218              :  *
     219              :  * @return 0 if success, errno on failure.
     220              :  */
     221            1 : int bt_csip_set_member_unregister(struct bt_csip_set_member_svc_inst *svc_inst);
     222              : 
     223              : /**
     224              :  * @brief Set the SIRK of a service instance
     225              :  *
     226              :  * @param svc_inst  Pointer to the registered Coordinated Set Identification Service.
     227              :  * @param sirk      The new SIRK.
     228              :  */
     229            1 : int bt_csip_set_member_sirk(struct bt_csip_set_member_svc_inst *svc_inst,
     230              :                             const uint8_t sirk[BT_CSIP_SIRK_SIZE]);
     231              : 
     232              : /**
     233              :  * @brief Set a new size and rank for a service instance
     234              :  *
     235              :  * This function can be used to dynamically change the size and rank of a service instance.
     236              :  * It is important to note that a set cannot have multiple devices with the same rank in a set,
     237              :  * and it is up to the caller of this function to ensure that.
     238              :  * Similarly, it is important that the size is updated on all devices in the set at the same time.
     239              :  *
     240              :  * If @kconfig{CONFIG_BT_CSIP_SET_MEMBER_SIZE_NOTIFIABLE} is enabled, this will also send a
     241              :  * notification to all connected or bonded clients.
     242              :  *
     243              :  * @param svc_inst The service instance.
     244              :  * @param size The new set size.
     245              :  * @param rank The new rank. Ignored if the @p svc_inst is not lockable.
     246              :  *
     247              :  * @retval -EINVAL @p svc_inst is NULL, @p size is less than 1, @p rank is less than 1 or higher
     248              :  *                 than @p size for a lockable @p svc_inst.
     249              :  * @retval -EALREADY @p size and @p rank are already the provided values.
     250              :  * @retval 0 Success.
     251              :  */
     252            1 : int bt_csip_set_member_set_size_and_rank(struct bt_csip_set_member_svc_inst *svc_inst, uint8_t size,
     253              :                                          uint8_t rank);
     254              : 
     255              : /** Struct to hold information about a service instance */
     256            1 : struct bt_csip_set_member_set_info {
     257              :         /** The 16-octet SIRK */
     258            1 :         uint8_t sirk[BT_CSIP_SIRK_SIZE];
     259              : 
     260              :         /** The set size */
     261            1 :         uint8_t set_size;
     262              : 
     263              :         /**
     264              :          * @brief The rank
     265              :          *
     266              :          * May be 0 if the set is not lockable
     267              :          */
     268            1 :         uint8_t rank;
     269              : 
     270              :         /** Whether the set is lockable  */
     271            1 :         bool lockable: 1;
     272              : 
     273              :         /** Whether the set is currently locked */
     274            1 :         bool locked: 1;
     275              : 
     276              :         /**
     277              :          * @brief The address of the client that currently holds the lock
     278              :          *
     279              :          * Will be @ref BT_ADDR_LE_NONE if the server holds the lock
     280              :          */
     281            1 :         bt_addr_le_t lock_client_addr;
     282              : };
     283              : 
     284              : /**
     285              :  * @brief Get information about a service instances
     286              :  *
     287              :  * @param svc_inst The service instance.
     288              :  * @param info Pointer to a struct to store the information in.
     289              :  *
     290              :  * @retval -EINVAL @p svc_inst or @p info is NULL.
     291              :  * @retval 0 Success.
     292              :  */
     293            1 : int bt_csip_set_member_get_info(const struct bt_csip_set_member_svc_inst *svc_inst,
     294              :                                 struct bt_csip_set_member_set_info *info);
     295              : 
     296              : /**
     297              :  * @brief Generate the Resolvable Set Identifier (RSI) value.
     298              :  *
     299              :  * This will generate RSI for given @p svc_inst instance.
     300              :  *
     301              :  * @param svc_inst  Pointer to the Coordinated Set Identification Service.
     302              :  * @param rsi       Pointer to the 6-octet newly generated RSI data in little-endian.
     303              :  *
     304              :  * @return int          0 if on success, errno on error.
     305              :  */
     306            1 : int bt_csip_set_member_generate_rsi(const struct bt_csip_set_member_svc_inst *svc_inst,
     307              :                                     uint8_t rsi[BT_CSIP_RSI_SIZE]);
     308              : 
     309              : /**
     310              :  * @brief Locks a specific Coordinated Set Identification Service instance on the server.
     311              :  *
     312              :  * @param svc_inst  Pointer to the Coordinated Set Identification Service.
     313              :  * @param lock      If true lock the set, if false release the set.
     314              :  * @param force     This argument only have meaning when @p lock is false
     315              :  *                  (release) and will force release the lock, regardless of who
     316              :  *                  took the lock.
     317              :  *
     318              :  * @return 0 on success, GATT error on error.
     319              :  */
     320            1 : int bt_csip_set_member_lock(struct bt_csip_set_member_svc_inst *svc_inst,
     321              :                             bool lock, bool force);
     322              : 
     323              : /** Information about a specific set */
     324            1 : struct bt_csip_set_coordinator_set_info {
     325              :         /**
     326              :          * @brief The 16 octet set Set Identity Resolving Key (SIRK)
     327              :          *
     328              :          * The SIRK may not be exposed by the server over Bluetooth, and
     329              :          * may require an out-of-band solution.
     330              :          */
     331            1 :         uint8_t sirk[BT_CSIP_SIRK_SIZE];
     332              : 
     333              :         /**
     334              :          * @brief The size of the set
     335              :          *
     336              :          * Will be 0 if not exposed by the server.
     337              :          */
     338            1 :         uint8_t set_size;
     339              : 
     340              :         /**
     341              :          * @brief The rank of the set on the remote device
     342              :          *
     343              :          * Will be 0 if not exposed by the server.
     344              :          */
     345            1 :         uint8_t rank;
     346              : 
     347              :         /** Whether or not the set can be locked on this device */
     348            1 :         bool lockable;
     349              : };
     350              : 
     351              : /**
     352              :  * @brief Struct representing a coordinated set instance on a remote device
     353              :  *
     354              :  * The values in this struct will be populated during discovery of sets
     355              :  * (bt_csip_set_coordinator_discover()).
     356              :  */
     357            1 : struct bt_csip_set_coordinator_csis_inst {
     358              :         /** Information about the coordinated set */
     359            1 :         struct bt_csip_set_coordinator_set_info info;
     360              : 
     361              :         /** Internally used pointer value */
     362            1 :         void *svc_inst;
     363              : };
     364              : 
     365              : /** Struct representing a remote device as a set member */
     366            1 : struct bt_csip_set_coordinator_set_member {
     367              :         /** Array of Coordinated Set Identification Service instances for the remote device */
     368            1 :         struct bt_csip_set_coordinator_csis_inst insts[BT_CSIP_SET_COORDINATOR_MAX_CSIS_INSTANCES];
     369              : };
     370              : 
     371              : /**
     372              :  * @typedef bt_csip_set_coordinator_discover_cb
     373              :  * @brief Callback for discovering Coordinated Set Identification Services.
     374              :  *
     375              :  * @param conn      Pointer to the remote device.
     376              :  * @param member    Pointer to the set member.
     377              :  * @param err       0 on success, or an errno value on error.
     378              :  * @param set_count Number of sets on the member.
     379              :  */
     380            1 : typedef void (*bt_csip_set_coordinator_discover_cb)(
     381              :         struct bt_conn *conn,
     382              :         const struct bt_csip_set_coordinator_set_member *member,
     383              :         int err, size_t set_count);
     384              : 
     385              : /**
     386              :  * @brief Initialise the csip_set_coordinator instance for a connection. This will do a
     387              :  * discovery on the device and prepare the instance for following commands.
     388              :  *
     389              :  * @param conn Pointer to remote device to perform discovery on.
     390              :  *
     391              :  * @return int Return 0 on success, or an errno value on error.
     392              :  */
     393            1 : int bt_csip_set_coordinator_discover(struct bt_conn *conn);
     394              : 
     395              : /**
     396              :  * @brief Get the set member from a connection pointer
     397              :  *
     398              :  * Get the Coordinated Set Identification Profile Set Coordinator pointer from a connection pointer.
     399              :  * Only Set Coordinators that have been initiated via bt_csip_set_coordinator_discover() can be
     400              :  * retrieved.
     401              :  *
     402              :  * @param conn     Connection pointer.
     403              :  *
     404              :  * @retval Pointer to a Coordinated Set Identification Profile Set Coordinator instance
     405              :  * @retval NULL if @p conn is NULL or if the connection has not done discovery yet
     406              :  */
     407              : struct bt_csip_set_coordinator_set_member *
     408            1 : bt_csip_set_coordinator_set_member_by_conn(const struct bt_conn *conn);
     409              : 
     410              : /**
     411              :  * @typedef bt_csip_set_coordinator_lock_set_cb
     412              :  * @brief Callback for locking a set across one or more devices
     413              :  *
     414              :  * @param err       0 on success, or an errno value on error.
     415              :  */
     416            1 : typedef void (*bt_csip_set_coordinator_lock_set_cb)(int err);
     417              : 
     418              : /**
     419              :  * @typedef bt_csip_set_coordinator_lock_changed_cb
     420              :  * @brief Callback when the lock value on a set of a connected device changes.
     421              :  *
     422              :  * @param inst    The Coordinated Set Identification Service instance that was
     423              :  *                changed.
     424              :  * @param locked  Whether the lock is locked or release.
     425              :  *
     426              :  * @return int Return 0 on success, or an errno value on error.
     427              :  */
     428            1 : typedef void (*bt_csip_set_coordinator_lock_changed_cb)(
     429              :         struct bt_csip_set_coordinator_csis_inst *inst, bool locked);
     430              : 
     431              : /**
     432              :  * @typedef bt_csip_set_coordinator_sirk_changed_cb
     433              :  * @brief Callback when the SIRK value of a set of a connected device changes.
     434              :  *
     435              :  * @param inst    The Coordinated Set Identification Service instance that was changed.
     436              :  *                The new SIRK can be accessed via the @p inst.info.
     437              :  */
     438            1 : typedef void (*bt_csip_set_coordinator_sirk_changed_cb)(
     439              :         struct bt_csip_set_coordinator_csis_inst *inst);
     440              : 
     441              : /**
     442              :  * @typedef bt_csip_set_coordinator_size_changed_cb
     443              :  * @brief Callback when the size of a set of a connected device changes.
     444              :  *
     445              :  * Since all devices in a set shall have the same set size value.
     446              :  * Each connected device may send the same new size set in a notification,
     447              :  * assuming that the remote device supports notifications of the set size.
     448              :  *
     449              :  * The rank of each device in the set may also change as part of this, so it is advisable to call
     450              :  * bt_csip_set_coordinator_discover() to rediscover and read the characteristic values of the sets
     451              :  * on each device.
     452              :  *
     453              :  * @param inst    The Coordinated Set Identification Service instance that was changed.
     454              :  *                The new size is stored in the @p inst->info.size.
     455              :  */
     456            1 : typedef void (*bt_csip_set_coordinator_size_changed_cb)(
     457              :         struct bt_conn *conn, const struct bt_csip_set_coordinator_csis_inst *inst);
     458              : 
     459              : /**
     460              :  * @typedef bt_csip_set_coordinator_ordered_access_cb_t
     461              :  * @brief Callback for bt_csip_set_coordinator_ordered_access()
     462              :  *
     463              :  * If any of the set members supplied to bt_csip_set_coordinator_ordered_access() is
     464              :  * in the locked state, this will be called with @p locked true and @p member
     465              :  * will be the locked member, and the ordered access procedure is cancelled.
     466              :  * Likewise, if any error occurs, the procedure will also be aborted.
     467              :  *
     468              :  * @param set_info  Pointer to the a specific set_info struct.
     469              :  * @param err       Error value. 0 on success, GATT error or errno on fail.
     470              :  * @param locked    Whether the lock is locked or release.
     471              :  * @param member    The locked member if @p locked is true, otherwise NULL.
     472              :  */
     473            1 : typedef void (*bt_csip_set_coordinator_ordered_access_cb_t)(
     474              :         const struct bt_csip_set_coordinator_set_info *set_info,
     475              :         int err, bool locked,
     476              :         struct bt_csip_set_coordinator_set_member *member);
     477              : 
     478              : /**
     479              :  * @brief Struct to hold the Coordinated Set Identification Profile Set Coordinator callbacks
     480              :  *
     481              :  * These can be registered for usage with bt_csip_set_coordinator_register_cb().
     482              :  */
     483            1 : struct bt_csip_set_coordinator_cb {
     484              :         /** Callback when discovery has finished */
     485            1 :         bt_csip_set_coordinator_discover_cb discover;
     486              :         /** Callback when locking a set has finished */
     487            1 :         bt_csip_set_coordinator_lock_set_cb lock_set;
     488              :         /** Callback when unlocking a set has finished */
     489            1 :         bt_csip_set_coordinator_lock_set_cb release_set;
     490              :         /** Callback when a set's lock state has changed */
     491            1 :         bt_csip_set_coordinator_lock_changed_cb lock_changed;
     492              :         /** Callback when a set's SIRK has changed */
     493            1 :         bt_csip_set_coordinator_sirk_changed_cb sirk_changed;
     494              :         /** Callback when a set's size has changed */
     495            1 :         bt_csip_set_coordinator_size_changed_cb size_changed;
     496              :         /** Callback for the ordered access procedure */
     497            1 :         bt_csip_set_coordinator_ordered_access_cb_t ordered_access;
     498              : 
     499              :         /** @cond INTERNAL_HIDDEN */
     500              :         /** Internally used field for list handling */
     501              :         sys_snode_t _node;
     502              :         /** @endcond */
     503              : };
     504              : 
     505              : /**
     506              :  * @brief Check if advertising data indicates a set member
     507              :  *
     508              :  * @param sirk The SIRK of the set to check against
     509              :  * @param data The advertising data
     510              :  *
     511              :  * @return true if the advertising data indicates a set member, false otherwise
     512              :  */
     513            1 : bool bt_csip_set_coordinator_is_set_member(const uint8_t sirk[BT_CSIP_SIRK_SIZE],
     514              :                                            struct bt_data *data);
     515              : 
     516              : /**
     517              :  * @brief Registers callbacks for csip_set_coordinator.
     518              :  *
     519              :  * @param cb   Pointer to the callback structure.
     520              :  *
     521              :  * @return Return 0 on success, or an errno value on error.
     522              :  */
     523            1 : int bt_csip_set_coordinator_register_cb(struct bt_csip_set_coordinator_cb *cb);
     524              : 
     525              : /**
     526              :  * @brief Callback function definition for bt_csip_set_coordinator_ordered_access()
     527              :  *
     528              :  * @param set_info   Pointer to the a specific set_info struct.
     529              :  * @param members    Array of members ordered by rank. The procedure shall be
     530              :  *                   done on the members in ascending order.
     531              :  * @param count      Number of members in @p members.
     532              :  *
     533              :  * @return true if the procedures can be successfully done, or false to stop the
     534              :  *         procedure.
     535              :  */
     536            1 : typedef bool (*bt_csip_set_coordinator_ordered_access_t)(
     537              :         const struct bt_csip_set_coordinator_set_info *set_info,
     538              :         struct bt_csip_set_coordinator_set_member *members[],
     539              :         size_t count);
     540              : 
     541              : /**
     542              :  * @brief Access Coordinated Set devices in an ordered manner as a client
     543              :  *
     544              :  * This function will read the lock state of all devices and if all devices are
     545              :  * in the unlocked state, then @p cb will be called with the same members as
     546              :  * provided by @p members, but where the members are ordered by rank
     547              :  * (if present). Once this procedure is finished or an error occurs,
     548              :  * @ref bt_csip_set_coordinator_cb.ordered_access will be called.
     549              :  *
     550              :  * This procedure only works if all the members have the lock characteristic,
     551              :  * and all either has rank = 0 or unique ranks.
     552              :  *
     553              :  * If any of the members are in the locked state, the procedure will be
     554              :  * cancelled.
     555              :  *
     556              :  * This can only be done on members that are bonded.
     557              :  *
     558              :  * @param members   Array of set members to access.
     559              :  * @param count     Number of set members in @p members.
     560              :  * @param set_info  Pointer to the a specific set_info struct, as a member may
     561              :  *                  be part of multiple sets.
     562              :  * @param cb        The callback function to be called for each member.
     563              :  */
     564            1 : int bt_csip_set_coordinator_ordered_access(
     565              :         const struct bt_csip_set_coordinator_set_member *members[],
     566              :         uint8_t count,
     567              :         const struct bt_csip_set_coordinator_set_info *set_info,
     568              :         bt_csip_set_coordinator_ordered_access_t cb);
     569              : 
     570              : /**
     571              :  * @brief Lock an array of set members
     572              :  *
     573              :  * The members will be locked starting from lowest rank going up.
     574              :  *
     575              :  * @kconfig_dep{CONFIG_BT_CSIP_SET_COORDINATOR,CONFIG_BT_BONDABLE}
     576              :  *
     577              :  * TODO: If locking fails, the already locked members will not be unlocked.
     578              :  *
     579              :  * @param members   Array of set members to lock.
     580              :  * @param count     Number of set members in @p members.
     581              :  * @param set_info  Pointer to the a specific set_info struct, as a member may
     582              :  *                  be part of multiple sets.
     583              :  *
     584              :  * @return Return 0 on success, or an errno value on error.
     585              :  */
     586            1 : int bt_csip_set_coordinator_lock(const struct bt_csip_set_coordinator_set_member **members,
     587              :                                  uint8_t count,
     588              :                                  const struct bt_csip_set_coordinator_set_info *set_info);
     589              : 
     590              : /**
     591              :  * @brief Release an array of set members
     592              :  *
     593              :  * The members will be released starting from highest rank going down.
     594              :  *
     595              :  * @kconfig_dep{CONFIG_BT_CSIP_SET_COORDINATOR,CONFIG_BT_BONDABLE}
     596              :  *
     597              :  * @param members   Array of set members to lock.
     598              :  * @param count     Number of set members in @p members.
     599              :  * @param set_info  Pointer to the a specific set_info struct, as a member may
     600              :  *                  be part of multiple sets.
     601              :  *
     602              :  * @return Return 0 on success, or an errno value on error.
     603              :  */
     604            1 : int bt_csip_set_coordinator_release(const struct bt_csip_set_coordinator_set_member **members,
     605              :                                     uint8_t count,
     606              :                                     const struct bt_csip_set_coordinator_set_info *set_info);
     607              : 
     608              : #ifdef __cplusplus
     609              : }
     610              : #endif
     611              : 
     612              : /**
     613              :  * @}
     614              :  */
     615              : 
     616              : #endif /* ZEPHYR_SUBSYS_BLUETOOTH_AUDIO_CSIP_H_ */
        

Generated by: LCOV version 2.0-1