/** * @file * @brief Bluetooth Microphone Control Profile (MICP) APIs. */ /* * Copyright (c) 2020-2024 Nordic Semiconductor ASA * * SPDX-License-Identifier: Apache-2.0 */ #ifndef ZEPHYR_INCLUDE_BLUETOOTH_MICP_H_ #define ZEPHYR_INCLUDE_BLUETOOTH_MICP_H_ /** * @brief Microphone Control Profile (MICP) * * @defgroup bt_micp Microphone Control Profile (MICP) * * @since 2.7 * @version 0.8.0 * * @ingroup bluetooth * @{ */ #include #include #include #include #ifdef __cplusplus extern "C" { #endif /** * Defines the maximum number of Microphone Control Service instances for the * Microphone Control Profile Microphone Device */ #if defined(CONFIG_BT_MICP_MIC_DEV) #define BT_MICP_MIC_DEV_AICS_CNT CONFIG_BT_MICP_MIC_DEV_AICS_INSTANCE_COUNT #else #define BT_MICP_MIC_DEV_AICS_CNT 0 #endif /* CONFIG_BT_MICP_MIC_DEV */ /** * @name Application error codes * @{ */ /** Mute/unmute commands are disabled. */ #define BT_MICP_ERR_MUTE_DISABLED 0x80 /** @} */ /** * @name Microphone Control Profile mute states * @{ */ /** The microphone state is unmuted */ #define BT_MICP_MUTE_UNMUTED 0x00 /** The microphone state is muted */ #define BT_MICP_MUTE_MUTED 0x01 /** The microphone state is disabled and cannot be muted or unmuted */ #define BT_MICP_MUTE_DISABLED 0x02 /** @} */ /** @brief Opaque Microphone Controller instance. */ struct bt_micp_mic_ctlr; /** @brief Register parameters structure for Microphone Control Service */ struct bt_micp_mic_dev_register_param { #if defined(CONFIG_BT_MICP_MIC_DEV_AICS) || defined(__DOXYGEN__) /** Register parameter structure for Audio Input Control Services */ struct bt_aics_register_param aics_param[BT_MICP_MIC_DEV_AICS_CNT]; #endif /* CONFIG_BT_MICP_MIC_DEV_AICS */ /** Microphone Control Profile callback structure. */ struct bt_micp_mic_dev_cb *cb; }; /** * @brief Microphone Control Profile included services * * Used for to represent the Microphone Control Profile included service * instances, for either a Microphone Controller or a Microphone Device. * The instance pointers either represent local service instances, * or remote service instances. */ struct bt_micp_included { /** Number of Audio Input Control Service instances */ uint8_t aics_cnt; /** Array of pointers to Audio Input Control Service instances */ struct bt_aics **aics; }; /** * @brief Initialize the Microphone Control Profile Microphone Device * * This will enable the Microphone Control Service instance and make it * discoverable by Microphone Controllers. * * @param param Pointer to an initialization structure. * * @return 0 if success, errno on failure. */ int bt_micp_mic_dev_register(struct bt_micp_mic_dev_register_param *param); /** * @brief Get Microphone Device included services * * Returns a pointer to a struct that contains information about the * Microphone Device included Audio Input Control Service instances. * * Requires that @kconfig{CONFIG_BT_MICP_MIC_DEV_AICS} is enabled. * * @param included Pointer to store the result in. * * @return 0 if success, errno on failure. */ int bt_micp_mic_dev_included_get(struct bt_micp_included *included); /** * @brief Struct to hold the Microphone Device callbacks * * These can be registered for usage with bt_micp_mic_dev_register(). */ struct bt_micp_mic_dev_cb { /** * @brief Callback function for Microphone Device mute. * * Called when the value is read with bt_micp_mic_dev_mute_get(), * or if the value is changed by either the Microphone Device or a * Microphone Controller. * * @param mute The mute setting of the Microphone Control Service. */ void (*mute)(uint8_t mute); }; /** * @brief Unmute the Microphone Device. * * @return 0 on success, GATT error value on fail. */ int bt_micp_mic_dev_unmute(void); /** * @brief Mute the Microphone Device. * * @return 0 on success, GATT error value on fail. */ int bt_micp_mic_dev_mute(void); /** * @brief Disable the mute functionality on the Microphone Device. * * Can be reenabled by called @ref bt_micp_mic_dev_mute or @ref bt_micp_mic_dev_unmute. * * @return 0 on success, GATT error value on fail. */ int bt_micp_mic_dev_mute_disable(void); /** * @brief Read the mute state on the Microphone Device. * * @return 0 on success, GATT error value on fail. */ int bt_micp_mic_dev_mute_get(void); /** * @brief Struct to hold the Microphone Controller callbacks * * These can be registered for usage with bt_micp_mic_ctlr_cb_register(). */ struct bt_micp_mic_ctlr_cb { /** * @brief Callback function for Microphone Control Profile mute. * * Called when the value is read, * or if the value is changed by either the Microphone Device or a * Microphone Controller. * * @param mic_ctlr Microphone Controller instance pointer. * @param err Error value. 0 on success, GATT error or errno on fail. * For notifications, this will always be 0. * @param mute The mute setting of the Microphone Control Service. */ void (*mute)(struct bt_micp_mic_ctlr *mic_ctlr, int err, uint8_t mute); /** * @brief Callback function for bt_micp_mic_ctlr_discover(). * * @param mic_ctlr Microphone Controller instance pointer. * @param err Error value. 0 on success, GATT error or errno on fail. * @param aics_count Number of Audio Input Control Service instances on * peer device. */ void (*discover)(struct bt_micp_mic_ctlr *mic_ctlr, int err, uint8_t aics_count); /** * @brief Callback function for Microphone Control Profile mute/unmute. * * @param mic_ctlr Microphone Controller instance pointer. * @param err Error value. 0 on success, GATT error or errno on fail. */ void (*mute_written)(struct bt_micp_mic_ctlr *mic_ctlr, int err); /** * @brief Callback function for Microphone Control Profile mute/unmute. * * @param mic_ctlr Microphone Controller instance pointer. * @param err Error value. 0 on success, GATT error or errno on fail. */ void (*unmute_written)(struct bt_micp_mic_ctlr *mic_ctlr, int err); #if defined(CONFIG_BT_MICP_MIC_CTLR_AICS) /** Audio Input Control Service client callback */ struct bt_aics_cb aics_cb; #endif /* CONFIG_BT_MICP_MIC_CTLR_AICS */ /** @internal Internally used field for list handling */ sys_snode_t _node; }; /** * @brief Get Microphone Control Profile included services * * Returns a pointer to a struct that contains information about the * Microphone Control Profile included services instances, such as * pointers to the Audio Input Control Service instances. * * Requires that @kconfig{CONFIG_BT_MICP_MIC_CTLR_AICS} is enabled. * * @param mic_ctlr Microphone Controller instance pointer. * @param[out] included Pointer to store the result in. * * @return 0 if success, errno on failure. */ int bt_micp_mic_ctlr_included_get(struct bt_micp_mic_ctlr *mic_ctlr, struct bt_micp_included *included); /** * @brief Get the connection pointer of a Microphone Controller instance * * Get the Bluetooth connection pointer of a Microphone Controller instance. * * @param mic_ctlr Microphone Controller instance pointer. * @param conn Connection pointer. * * @return 0 if success, errno on failure. */ int bt_micp_mic_ctlr_conn_get(const struct bt_micp_mic_ctlr *mic_ctlr, struct bt_conn **conn); /** * @brief Get the volume controller from a connection pointer * * Get the Volume Control Profile Volume Controller pointer from a connection pointer. * Only volume controllers that have been initiated via bt_micp_mic_ctlr_discover() can be * retrieved. * * @param conn Connection pointer. * * @retval Pointer to a Microphone Control Profile Microphone Controller instance * @retval NULL if @p conn is NULL or if the connection has not done discovery yet */ struct bt_micp_mic_ctlr *bt_micp_mic_ctlr_get_by_conn(const struct bt_conn *conn); /** * @brief Discover Microphone Control Service * * This will start a GATT discovery and setup handles and subscriptions. * This shall be called once before any other actions can be executed for the * peer device, and the @ref bt_micp_mic_ctlr_cb.discover callback will notify * when it is possible to start remote operations. * * * @param conn The connection to initialize the profile for. * @param[out] mic_ctlr Valid remote instance object on success. * * @return 0 on success, GATT error value on fail. */ int bt_micp_mic_ctlr_discover(struct bt_conn *conn, struct bt_micp_mic_ctlr **mic_ctlr); /** * @brief Unmute a remote Microphone Device. * * @param mic_ctlr Microphone Controller instance pointer. * * @return 0 on success, GATT error value on fail. */ int bt_micp_mic_ctlr_unmute(struct bt_micp_mic_ctlr *mic_ctlr); /** * @brief Mute a remote Microphone Device. * * @param mic_ctlr Microphone Controller instance pointer. * * @return 0 on success, GATT error value on fail. */ int bt_micp_mic_ctlr_mute(struct bt_micp_mic_ctlr *mic_ctlr); /** * @brief Read the mute state of a remote Microphone Device. * * @param mic_ctlr Microphone Controller instance pointer. * * @return 0 on success, GATT error value on fail. */ int bt_micp_mic_ctlr_mute_get(struct bt_micp_mic_ctlr *mic_ctlr); /** * @brief Registers the callbacks used by Microphone Controller. * * This can only be done as the client. * * @param cb The callback structure. * * @return 0 if success, errno on failure. */ int bt_micp_mic_ctlr_cb_register(struct bt_micp_mic_ctlr_cb *cb); #ifdef __cplusplus } #endif /** * @} */ #endif /* ZEPHYR_INCLUDE_BLUETOOTH_MICP_H_ */