Volume Offset Control Service (VOCS)

Volume Offset Control Service (VOCS) More...

Data Structures
struct	bt_vocs_register_param
	Structure for registering a Volume Offset Control Service instance. More...
struct	bt_vocs_discover_param
	Structure for discovering a Volume Offset Control Service instance. More...
struct	bt_vocs_cb
	Struct to hold the Volume Offset Control Service callbacks. More...

Typedefs
typedef void(*	bt_vocs_state_cb) (struct bt_vocs *inst, int err, int16_t offset)
	Callback function for the offset state.
typedef void(*	bt_vocs_set_offset_cb) (struct bt_vocs *inst, int err)
	Callback function for setting offset.
typedef void(*	bt_vocs_location_cb) (struct bt_vocs *inst, int err, uint32_t location)
	Callback function for the location.
typedef void(*	bt_vocs_description_cb) (struct bt_vocs *inst, int err, char *description)
	Callback function for the description.
typedef void(*	bt_vocs_discover_cb) (struct bt_vocs *inst, int err)
	Callback function for bt_vocs_discover.

Functions
struct bt_vocs *	bt_vocs_free_instance_get (void)
	Get a free service instance of Volume Offset Control Service from the pool.
void *	bt_vocs_svc_decl_get (struct bt_vocs *vocs)
	Get the service declaration attribute.
int	bt_vocs_client_conn_get (const struct bt_vocs *vocs, struct bt_conn **conn)
	Get the connection pointer of a client instance.
int	bt_vocs_register (struct bt_vocs *vocs, const struct bt_vocs_register_param *param)
	Register the Volume Offset Control Service instance.
int	bt_vocs_state_get (struct bt_vocs *inst)
	Read the Volume Offset Control Service offset state.
int	bt_vocs_state_set (struct bt_vocs *inst, int16_t offset)
	Set the Volume Offset Control Service offset state.
int	bt_vocs_location_get (struct bt_vocs *inst)
	Read the Volume Offset Control Service location.
int	bt_vocs_location_set (struct bt_vocs *inst, uint32_t location)
	Set the Volume Offset Control Service location.
int	bt_vocs_description_get (struct bt_vocs *inst)
	Read the Volume Offset Control Service output description.
int	bt_vocs_description_set (struct bt_vocs *inst, const char *description)
	Set the Volume Offset Control Service description.
void	bt_vocs_client_cb_register (struct bt_vocs *inst, struct bt_vocs_cb *cb)
	Registers the callbacks for the Volume Offset Control Service client.
struct bt_vocs *	bt_vocs_client_free_instance_get (void)
	Returns a pointer to a Volume Offset Control Service client instance.
int	bt_vocs_discover (struct bt_conn *conn, struct bt_vocs *inst, const struct bt_vocs_discover_param *param)
	Discover a Volume Offset Control Service.

Volume Offset Control Service Error codes
#define	BT_VOCS_ERR_INVALID_COUNTER   0x80
	The Change_Counter operand value does not match the Change_Counter field value of the Volume Offset State characteristic.
#define	BT_VOCS_ERR_OP_NOT_SUPPORTED   0x81
	An invalid opcode has been used in a control point procedure.
#define	BT_VOCS_ERR_OUT_OF_RANGE   0x82
	An operand value used in a control point procedure is outside the permissible range.

Volume Offset Control Service offset limits
#define	BT_VOCS_MIN_OFFSET   -255
	Minimum offset value.
#define	BT_VOCS_MAX_OFFSET   255
	Maximum offset value.

Detailed Description

Volume Offset Control Service (VOCS)

Since

2.6

Version

0.8.0

The Volume Offset Control Service is a secondary service, and as such should not be used own its own, but rather in the context of another (primary) service.

This API implements both the server and client functionality. Note that the API abstracts away the change counter in the volume offset control state and will automatically handle any changes to that. If out of date, the client implementation will autonomously read the change counter value when executing a write request.

Macro Definition Documentation

BT_VOCS_ERR_INVALID_COUNTER

#define BT_VOCS_ERR_INVALID_COUNTER   0x80

#include <zephyr/bluetooth/audio/vocs.h>

The Change_Counter operand value does not match the Change_Counter field value of the Volume Offset State characteristic.

BT_VOCS_ERR_OP_NOT_SUPPORTED

#define BT_VOCS_ERR_OP_NOT_SUPPORTED   0x81

#include <zephyr/bluetooth/audio/vocs.h>

An invalid opcode has been used in a control point procedure.

BT_VOCS_ERR_OUT_OF_RANGE

#define BT_VOCS_ERR_OUT_OF_RANGE   0x82

#include <zephyr/bluetooth/audio/vocs.h>

An operand value used in a control point procedure is outside the permissible range.

BT_VOCS_MAX_OFFSET

#define BT_VOCS_MAX_OFFSET   255

#include <zephyr/bluetooth/audio/vocs.h>

Maximum offset value.

BT_VOCS_MIN_OFFSET

#define BT_VOCS_MIN_OFFSET   -255

#include <zephyr/bluetooth/audio/vocs.h>

Minimum offset value.

Typedef Documentation

bt_vocs_description_cb

typedef void(* bt_vocs_description_cb) (struct bt_vocs *inst, int err, char *description)

#include <zephyr/bluetooth/audio/vocs.h>

Callback function for the description.

Called when the value is read, or if the value is changed by either the server or client.

Parameters

inst	The instance pointer.
err	Error value. 0 on success, GATT error on positive value or errno on negative value. For notifications, this will always be 0.
description	The description as an UTF-8 encoded string.

bt_vocs_discover_cb

typedef void(* bt_vocs_discover_cb) (struct bt_vocs *inst, int err)

#include <zephyr/bluetooth/audio/vocs.h>

Callback function for bt_vocs_discover.

This callback should be overwritten by the primary service that includes the Volume Control Offset Service client, and should thus not be set by the application.

Parameters

inst	The instance pointer.
err	Error value. 0 on success, GATT error on positive value or errno on negative value. For notifications, this will always be 0.

bt_vocs_location_cb

typedef void(* bt_vocs_location_cb) (struct bt_vocs *inst, int err, uint32_t location)

#include <zephyr/bluetooth/audio/vocs.h>

Callback function for the location.

Called when the value is read, or if the value is changed by either the server or client.

Parameters

inst	The instance pointer.
err	Error value. 0 on success, GATT error on positive value or errno on negative value. For notifications, this will always be 0.
location	The location value.

bt_vocs_set_offset_cb

typedef void(* bt_vocs_set_offset_cb) (struct bt_vocs *inst, int err)

#include <zephyr/bluetooth/audio/vocs.h>

Callback function for setting offset.

Parameters

inst	The instance pointer.
err	Error value. 0 on success, GATT error on positive value or errno on negative value.

bt_vocs_state_cb

typedef void(* bt_vocs_state_cb) (struct bt_vocs *inst, int err, int16_t offset)

#include <zephyr/bluetooth/audio/vocs.h>

Callback function for the offset state.

Called when the value is read, or if the value is changed by either the server or client.

Parameters

inst	The instance pointer.
err	Error value. 0 on success, GATT error on positive value or errno on negative value. For notifications, this will always be 0.
offset	The offset value.

Function Documentation

bt_vocs_client_cb_register()

void bt_vocs_client_cb_register	(	struct bt_vocs *	inst,
		struct bt_vocs_cb *	cb
	)

#include <zephyr/bluetooth/audio/vocs.h>

Registers the callbacks for the Volume Offset Control Service client.

Parameters

inst	Pointer to the Volume Offset Control Service client instance.
cb	Pointer to the callback structure.

bt_vocs_client_conn_get()

int bt_vocs_client_conn_get	(	const struct bt_vocs *	vocs,
		struct bt_conn **	conn
	)

#include <zephyr/bluetooth/audio/vocs.h>

Get the connection pointer of a client instance.

Get the Bluetooth connection pointer of a Audio Input Control Service client instance.

Parameters

vocs	Audio Input Control Service client instance pointer.
conn	Connection pointer.

Returns

0 if success, errno on failure.

bt_vocs_client_free_instance_get()

struct bt_vocs * bt_vocs_client_free_instance_get

(

void

)

#include <zephyr/bluetooth/audio/vocs.h>

Returns a pointer to a Volume Offset Control Service client instance.

Returns

Pointer to the instance, or NULL if no free instances are left.

bt_vocs_description_get()

int bt_vocs_description_get

(

struct bt_vocs *

inst

)

#include <zephyr/bluetooth/audio/vocs.h>

Read the Volume Offset Control Service output description.

The value is returned in the bt_vocs_cb.description callback.

Parameters

inst	Pointer to the Volume Offset Control Service instance.

Returns

0 on success, GATT error value on fail.

bt_vocs_description_set()

int bt_vocs_description_set	(	struct bt_vocs *	inst,
		const char *	description
	)

#include <zephyr/bluetooth/audio/vocs.h>

Set the Volume Offset Control Service description.

Parameters

inst	Pointer to the Volume Offset Control Service instance.
description	The UTF-8 encoded string description to set.

Returns

0 on success, GATT error value on fail.

bt_vocs_discover()

int bt_vocs_discover	(	struct bt_conn *	conn,
		struct bt_vocs *	inst,
		const struct bt_vocs_discover_param *	param
	)

#include <zephyr/bluetooth/audio/vocs.h>

Discover a Volume Offset Control Service.

Attempts to discover a Volume Offset Control Service on a server given the param.

Parameters

conn	Connection to the peer with the Volume Offset Control Service.
inst	Pointer to the Volume Offset Control Service client instance.
param	Pointer to the parameters.

Returns

0 on success, errno on fail.

bt_vocs_free_instance_get()

struct bt_vocs * bt_vocs_free_instance_get

(

void

)

#include <zephyr/bluetooth/audio/vocs.h>

Get a free service instance of Volume Offset Control Service from the pool.

Returns

Volume Offset Control Service instance in case of success or NULL in case of error.

bt_vocs_location_get()

int bt_vocs_location_get

(

struct bt_vocs *

inst

)

#include <zephyr/bluetooth/audio/vocs.h>

Read the Volume Offset Control Service location.

The value is returned in the bt_vocs_cb.location callback.

Parameters

inst	Pointer to the Volume Offset Control Service instance.

Returns

0 on success, GATT error value on fail.

bt_vocs_location_set()

int bt_vocs_location_set	(	struct bt_vocs *	inst,
		uint32_t	location
	)

#include <zephyr/bluetooth/audio/vocs.h>

Set the Volume Offset Control Service location.

Parameters

inst	Pointer to the Volume Offset Control Service instance.
location	The location to set.

Returns

0 on success, GATT error value on fail.

bt_vocs_register()

int bt_vocs_register	(	struct bt_vocs *	vocs,
		const struct bt_vocs_register_param *	param
	)

#include <zephyr/bluetooth/audio/vocs.h>

Register the Volume Offset Control Service instance.

Parameters

vocs	Volume Offset Control Service instance.
param	Volume Offset Control Service register parameters.

Returns

0 if success, errno on failure.

bt_vocs_state_get()

int bt_vocs_state_get

(

struct bt_vocs *

inst

)

#include <zephyr/bluetooth/audio/vocs.h>

Read the Volume Offset Control Service offset state.

The value is returned in the bt_vocs_cb.state callback.

Parameters

inst	Pointer to the Volume Offset Control Service instance.

Returns

0 on success, GATT error value on fail.

bt_vocs_state_set()

int bt_vocs_state_set	(	struct bt_vocs *	inst,
		int16_t	offset
	)

#include <zephyr/bluetooth/audio/vocs.h>

Set the Volume Offset Control Service offset state.

Parameters

inst	Pointer to the Volume Offset Control Service instance.
offset	The offset to set (-255 to 255).

Returns

0 on success, GATT error value on fail.

bt_vocs_svc_decl_get()

void * bt_vocs_svc_decl_get

(

struct bt_vocs *

vocs

)

#include <zephyr/bluetooth/audio/vocs.h>

Get the service declaration attribute.

The first service attribute returned can be included in any other GATT service.

Parameters

vocs	Volume Offset Control Service instance.

Returns

Pointer to the attributes of the service.