Zephyr API Documentation  2.7.0-rc2
A Scalable Open Source RTOS
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
 

Macros

#define BT_VOCS_ERR_INVALID_COUNTER   0x80
 
#define BT_VOCS_ERR_OP_NOT_SUPPORTED   0x81
 
#define BT_VOCS_ERR_OUT_OF_RANGE   0x82
 
#define BT_VOCS_MIN_OFFSET   -255
 
#define BT_VOCS_MAX_OFFSET   255
 

Typedefs

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

Functions

struct bt_vocs * bt_vocs_free_instance_get (void)
 Get a free service instance of Volume Offset Control Service from the pool. More...
 
voidbt_vocs_svc_decl_get (struct bt_vocs *vocs)
 Get the service declaration attribute. More...
 
int bt_vocs_client_conn_get (const struct bt_vocs *vocs, struct bt_conn **conn)
 Get the connection pointer of a client instance. More...
 
int bt_vocs_register (struct bt_vocs *vocs, const struct bt_vocs_register_param *param)
 Register the Volume Offset Control Service instance. More...
 
int bt_vocs_state_get (struct bt_vocs *inst)
 Read the Volume Offset Control Service offset state. More...
 
int bt_vocs_state_set (struct bt_vocs *inst, int16_t offset)
 Set the Volume Offset Control Service offset state. More...
 
int bt_vocs_location_get (struct bt_vocs *inst)
 Read the Volume Offset Control Service location. More...
 
int bt_vocs_location_set (struct bt_vocs *inst, uint32_t location)
 Set the Volume Offset Control Service location. More...
 
int bt_vocs_description_get (struct bt_vocs *inst)
 Read the Volume Offset Control Service output description. More...
 
int bt_vocs_description_set (struct bt_vocs *inst, const char *description)
 Set the Volume Offset Control Service description. More...
 
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. More...
 
struct bt_vocs * bt_vocs_client_free_instance_get (void)
 Returns a pointer to a Volume Offset Control Service client instance. More...
 
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. More...
 

Detailed Description

Volume Offset Control Service (VOCS)

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.

[Experimental] Users should note that the APIs can change as a part of ongoing development.

Macro Definition Documentation

◆ BT_VOCS_ERR_INVALID_COUNTER

#define BT_VOCS_ERR_INVALID_COUNTER   0x80

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

Volume Offset Control Service Error codes

◆ BT_VOCS_ERR_OP_NOT_SUPPORTED

#define BT_VOCS_ERR_OP_NOT_SUPPORTED   0x81

◆ BT_VOCS_ERR_OUT_OF_RANGE

#define BT_VOCS_ERR_OUT_OF_RANGE   0x82

◆ BT_VOCS_MAX_OFFSET

#define BT_VOCS_MAX_OFFSET   255

◆ BT_VOCS_MIN_OFFSET

#define BT_VOCS_MIN_OFFSET   -255

Typedef Documentation

◆ bt_vocs_description_cb

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

#include <include/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
instThe instance pointer.
errError value. 0 on success, GATT error on positive value or errno on negative value. For notifications, this will always be 0.
descriptionThe description as an UTF-8 encoded string.

◆ bt_vocs_discover_cb

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

#include <include/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
instThe instance pointer.
errError 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 <include/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
instThe instance pointer.
errError value. 0 on success, GATT error on positive value or errno on negative value. For notifications, this will always be 0.
locationThe location value.

◆ bt_vocs_set_offset_cb

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

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

Callback function for setting offset.

Parameters
instThe instance pointer.
errError 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 <include/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
instThe instance pointer.
errError value. 0 on success, GATT error on positive value or errno on negative value. For notifications, this will always be 0.
offsetThe 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 <include/bluetooth/audio/vocs.h>

Registers the callbacks for the Volume Offset Control Service client.

Parameters
instPointer to the Volume Offset Control Service client instance.
cbPointer 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 <include/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
vocsAudio Input Control Service client instance pointer.
connConnection 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 <include/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 <include/bluetooth/audio/vocs.h>

Read the Volume Offset Control Service output description.

The value is returned in the bt_vocs_cb.description callback.

Parameters
instPointer 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 <include/bluetooth/audio/vocs.h>

Set the Volume Offset Control Service description.

Parameters
instPointer to the Volume Offset Control Service instance.
descriptionThe 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 <include/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
connConnection to the peer with the Volume Offset Control Service.
instPointer to the Volume Offset Control Service client instance.
paramPointer 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 <include/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 <include/bluetooth/audio/vocs.h>

Read the Volume Offset Control Service location.

The value is returned in the bt_vocs_cb.location callback.

Parameters
instPointer 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 <include/bluetooth/audio/vocs.h>

Set the Volume Offset Control Service location.

Parameters
instPointer to the Volume Offset Control Service instance.
locationThe 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 <include/bluetooth/audio/vocs.h>

Register the Volume Offset Control Service instance.

Parameters
vocsVolume Offset Control Service instance.
paramVolume 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 <include/bluetooth/audio/vocs.h>

Read the Volume Offset Control Service offset state.

The value is returned in the bt_vocs_cb.state callback.

Parameters
instPointer 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 <include/bluetooth/audio/vocs.h>

Set the Volume Offset Control Service offset state.

Parameters
instPointer to the Volume Offset Control Service instance.
offsetThe 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 <include/bluetooth/audio/vocs.h>

Get the service declaration attribute.

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

Parameters
vocsVolume Offset Control Service instance.
Returns
Pointer to the attributes of the service.