The latest development version of this page may be more current than this released 3.7.0 version.

Bluetooth standard services

Battery Service

group bt_bas

Battery Service (BAS)

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

Functions

uint8_t bt_bas_get_battery_level(void)

Read battery level value.

Read the characteristic value of the battery level

Returns:: The battery level in percent.

int bt_bas_set_battery_level(uint8_t level)

Update battery level value.

Update the characteristic value of the battery level This will send a GATT notification to all current subscribers.

Parameters:

level – The battery level in percent.

Returns:

Zero in case of success and error code in case of error.

Heart Rate Service

group bt_hrs

Heart Rate Service (HRS)

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

Functions

int bt_hrs_cb_register(struct bt_hrs_cb *cb)

Heart rate service callback register.

This function will register callbacks that will be called in certain events related to Heart rate service.

Parameters:

cb – Pointer to callbacks structure. Must point to memory that remains valid until unregistered.

Returns:

0 on success

Returns:

-EINVAL in case cb is NULL

int bt_hrs_cb_unregister(struct bt_hrs_cb *cb)

Heart rate service callback unregister.

This function will unregister callback from Heart rate service.

Parameters:

cb – Pointer to callbacks structure

Returns:

0 on success

Returns:

-EINVAL in case cb is NULL

Returns:

-ENOENT in case the cb was not found in registered callbacks

int bt_hrs_notify(uint16_t heartrate)

Notify heart rate measurement.

This will send a GATT notification to all current subscribers.

Parameters:

heartrate – The heartrate measurement in beats per minute.

Returns:

Zero in case of success and error code in case of error.

struct bt_hrs_cb

#include <hrs.h>

Heart rate service callback structure.

Public Members

void (*ntf_changed)(bool enabled)

Heart rate notifications changed.

Param enabled:: Flag that is true if notifications were enabled, false if they were disabled.

Immediate Alert Service

group bt_ias

Immediate Alert Service (IAS)

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

Defines

BT_IAS_CB_DEFINE(_name)

Register a callback structure for immediate alert events.

Parameters:

_name – Name of callback structure.

Enums

enum bt_ias_alert_lvl

Values:

enumerator BT_IAS_ALERT_LVL_NO_ALERT: No alerting should be done on device.

enumerator BT_IAS_ALERT_LVL_MILD_ALERT: Device shall alert.

enumerator BT_IAS_ALERT_LVL_HIGH_ALERT: Device should alert in strongest possible way.

Functions

int bt_ias_local_alert_stop(void)

Method for stopping alert locally.

Returns:: Zero in case of success and error code in case of error.

int bt_ias_client_alert_write(struct bt_conn *conn, enum bt_ias_alert_lvl)

Set alert level.

Parameters:

conn – Bluetooth connection object
bt_ias_alert_lvl – Level of alert to write

Returns:

Zero in case of success and error code in case of error.

int bt_ias_discover(struct bt_conn *conn)

Discover Immediate Alert Service.

Parameters:

conn – Bluetooth connection object

Returns:

Zero in case of success and error code in case of error.

int bt_ias_client_cb_register(const struct bt_ias_client_cb *cb)

Register Immediate Alert Client callbacks.

Parameters:

cb – The callback structure

Returns:

Zero in case of success and error code in case of error.

struct bt_ias_cb

#include <ias.h>

Immediate Alert Service callback structure.

Public Members

void (*no_alert)(void)

Callback function to stop alert.

This callback is called when peer commands to disable alert.

void (*mild_alert)(void)

Callback function for alert level value.

This callback is called when peer commands to alert.

void (*high_alert)(void)

Callback function for alert level value.

This callback is called when peer commands to alert in the strongest possible way.

struct bt_ias_client_cb

#include <ias.h>

Public Members

void (*discover)(struct bt_conn *conn, int err)

Callback function for bt_ias_discover.

This callback is called when discovery procedure is complete.

Param conn:: Bluetooth connection object.
Param err:: 0 on success, ATT error or negative errno otherwise

Object Transfer Service

group bt_ots

Object Transfer Service (OTS)

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

Defines

BT_OTS_OBJ_ID_SIZE: Size of OTS object ID (in bytes).

BT_OTS_OBJ_ID_MIN: Minimum allowed value for object ID (except ID for directory listing)

BT_OTS_OBJ_ID_MAX: Maximum allowed value for object ID (except ID for directory listing)

OTS_OBJ_ID_DIR_LIST: ID of the Directory Listing Object.

BT_OTS_OBJ_ID_MASK: Mask for OTS object IDs, preserving the 48 bits.

BT_OTS_OBJ_ID_STR_LEN: Length of OTS object ID string (in bytes).

BT_OTS_OBJ_SET_PROP_DELETE(prop)

Set BT_OTS_OBJ_PROP_DELETE property.

Parameters:

prop – Object properties.

BT_OTS_OBJ_SET_PROP_EXECUTE(prop)

Set BT_OTS_OBJ_PROP_EXECUTE property.

Parameters:

prop – Object properties.

BT_OTS_OBJ_SET_PROP_READ(prop)

Set BT_OTS_OBJ_PROP_READ property.

Parameters:

prop – Object properties.

BT_OTS_OBJ_SET_PROP_WRITE(prop)

Set BT_OTS_OBJ_PROP_WRITE property.

Parameters:

prop – Object properties.

BT_OTS_OBJ_SET_PROP_APPEND(prop)

Set BT_OTS_OBJ_PROP_APPEND property.

Parameters:

prop – Object properties.

BT_OTS_OBJ_SET_PROP_TRUNCATE(prop)

Set BT_OTS_OBJ_PROP_TRUNCATE property.

Parameters:

prop – Object properties.

BT_OTS_OBJ_SET_PROP_PATCH(prop)

Set BT_OTS_OBJ_PROP_PATCH property.

Parameters:

prop – Object properties.

BT_OTS_OBJ_SET_PROP_MARKED(prop)

Set BT_OTS_OBJ_SET_PROP_MARKED property.

Parameters:

prop – Object properties.

BT_OTS_OBJ_GET_PROP_DELETE(prop)

Get BT_OTS_OBJ_PROP_DELETE property.

Parameters:

prop – Object properties.

BT_OTS_OBJ_GET_PROP_EXECUTE(prop)

Get BT_OTS_OBJ_PROP_EXECUTE property.

Parameters:

prop – Object properties.

BT_OTS_OBJ_GET_PROP_READ(prop)

Get BT_OTS_OBJ_PROP_READ property.

Parameters:

prop – Object properties.

BT_OTS_OBJ_GET_PROP_WRITE(prop)

Get BT_OTS_OBJ_PROP_WRITE property.

Parameters:

prop – Object properties.

BT_OTS_OBJ_GET_PROP_APPEND(prop)

Get BT_OTS_OBJ_PROP_APPEND property.

Parameters:

prop – Object properties.

BT_OTS_OBJ_GET_PROP_TRUNCATE(prop)

Get BT_OTS_OBJ_PROP_TRUNCATE property.

Parameters:

prop – Object properties.

BT_OTS_OBJ_GET_PROP_PATCH(prop)

Get BT_OTS_OBJ_PROP_PATCH property.

Parameters:

prop – Object properties.

BT_OTS_OBJ_GET_PROP_MARKED(prop)

Get BT_OTS_OBJ_PROP_MARKED property.

Parameters:

prop – Object properties.

BT_OTS_OACP_SET_FEAT_CREATE(feat)

Set BT_OTS_OACP_SET_FEAT_CREATE feature.

Parameters:

feat – OTS features.

BT_OTS_OACP_SET_FEAT_DELETE(feat)

Set BT_OTS_OACP_FEAT_DELETE feature.

Parameters:

feat – OTS features.

BT_OTS_OACP_SET_FEAT_CHECKSUM(feat)

Set BT_OTS_OACP_FEAT_CHECKSUM feature.

Parameters:

feat – OTS features.

BT_OTS_OACP_SET_FEAT_EXECUTE(feat)

Set BT_OTS_OACP_FEAT_EXECUTE feature.

Parameters:

feat – OTS features.

BT_OTS_OACP_SET_FEAT_READ(feat)

Set BT_OTS_OACP_FEAT_READ feature.

Parameters:

feat – OTS features.

BT_OTS_OACP_SET_FEAT_WRITE(feat)

Set BT_OTS_OACP_FEAT_WRITE feature.

Parameters:

feat – OTS features.

BT_OTS_OACP_SET_FEAT_APPEND(feat)

Set BT_OTS_OACP_FEAT_APPEND feature.

Parameters:

feat – OTS features.

BT_OTS_OACP_SET_FEAT_TRUNCATE(feat)

Set BT_OTS_OACP_FEAT_TRUNCATE feature.

Parameters:

feat – OTS features.

BT_OTS_OACP_SET_FEAT_PATCH(feat)

Set BT_OTS_OACP_FEAT_PATCH feature.

Parameters:

feat – OTS features.

BT_OTS_OACP_SET_FEAT_ABORT(feat)

Set BT_OTS_OACP_FEAT_ABORT feature.

Parameters:

feat – OTS features.

BT_OTS_OACP_GET_FEAT_CREATE(feat)

Get BT_OTS_OACP_FEAT_CREATE feature.

Parameters:

feat – OTS features.

BT_OTS_OACP_GET_FEAT_DELETE(feat)

Get BT_OTS_OACP_FEAT_DELETE feature.

Parameters:

feat – OTS features.

BT_OTS_OACP_GET_FEAT_CHECKSUM(feat)

Get BT_OTS_OACP_FEAT_CHECKSUM feature.

Parameters:

feat – OTS features.

BT_OTS_OACP_GET_FEAT_EXECUTE(feat)

Get BT_OTS_OACP_FEAT_EXECUTE feature.

Parameters:

feat – OTS features.

BT_OTS_OACP_GET_FEAT_READ(feat)

Get BT_OTS_OACP_FEAT_READ feature.

Parameters:

feat – OTS features.

BT_OTS_OACP_GET_FEAT_WRITE(feat)

Get BT_OTS_OACP_FEAT_WRITE feature.

Parameters:

feat – OTS features.

BT_OTS_OACP_GET_FEAT_APPEND(feat)

Get BT_OTS_OACP_FEAT_APPEND feature.

Parameters:

feat – OTS features.

BT_OTS_OACP_GET_FEAT_TRUNCATE(feat)

Get BT_OTS_OACP_FEAT_TRUNCATE feature.

Parameters:

feat – OTS features.

BT_OTS_OACP_GET_FEAT_PATCH(feat)

Get BT_OTS_OACP_FEAT_PATCH feature.

Parameters:

feat – OTS features.

BT_OTS_OACP_GET_FEAT_ABORT(feat)

Get BT_OTS_OACP_FEAT_ABORT feature.

Parameters:

feat – OTS features.

BT_OTS_OLCP_SET_FEAT_GO_TO(feat)

Set BT_OTS_OLCP_FEAT_GO_TO feature.

Parameters:

feat – OTS features.

BT_OTS_OLCP_SET_FEAT_ORDER(feat)

Set BT_OTS_OLCP_FEAT_ORDER feature.

Parameters:

feat – OTS features.

BT_OTS_OLCP_SET_FEAT_NUM_REQ(feat)

Set BT_OTS_OLCP_FEAT_NUM_REQ feature.

Parameters:

feat – OTS features.

BT_OTS_OLCP_SET_FEAT_CLEAR(feat)

Set BT_OTS_OLCP_FEAT_CLEAR feature.

Parameters:

feat – OTS features.

BT_OTS_OLCP_GET_FEAT_GO_TO(feat)

Get BT_OTS_OLCP_GET_FEAT_GO_TO feature.

Parameters:

feat – OTS features.

BT_OTS_OLCP_GET_FEAT_ORDER(feat)

Get BT_OTS_OLCP_GET_FEAT_ORDER feature.

Parameters:

feat – OTS features.

BT_OTS_OLCP_GET_FEAT_NUM_REQ(feat)

Get BT_OTS_OLCP_GET_FEAT_NUM_REQ feature.

Parameters:

feat – OTS features.

BT_OTS_OLCP_GET_FEAT_CLEAR(feat)

Get BT_OTS_OLCP_GET_FEAT_CLEAR feature.

Parameters:

feat – OTS features.

BT_OTS_DATE_TIME_FIELD_SIZE

BT_OTS_STOP

BT_OTS_CONTINUE

Typedefs

typedef int (*bt_ots_client_dirlisting_cb)(struct bt_ots_obj_metadata *meta)

Directory listing object metadata callback.

If a directory listing is decoded using bt_ots_client_decode_dirlisting(), this callback will be called for each object in the directory listing.

Param meta:: The metadata of the decoded object
Return:: int BT_OTS_STOP or BT_OTS_CONTINUE. BT_OTS_STOP can be used to stop the decoding.

Enums

enum [anonymous]

Properties of an OTS object.

Values:

enumerator BT_OTS_OBJ_PROP_DELETE = 0: Bit 0 Deletion of this object is permitted.

enumerator BT_OTS_OBJ_PROP_EXECUTE = 1: Bit 1 Execution of this object is permitted.

enumerator BT_OTS_OBJ_PROP_READ = 2: Bit 2 Reading this object is permitted.

enumerator BT_OTS_OBJ_PROP_WRITE = 3: Bit 3 Writing data to this object is permitted.

enumerator BT_OTS_OBJ_PROP_APPEND = 4

Bit 4 Appending data to this object is permitted.

   Appending data increases its Allocated Size.

enumerator BT_OTS_OBJ_PROP_TRUNCATE = 5: Bit 5 Truncation of this object is permitted.

enumerator BT_OTS_OBJ_PROP_PATCH = 6

Bit 6 Patching this object is permitted.

    Patching this object overwrites some of
    the object's existing contents.

enumerator BT_OTS_OBJ_PROP_MARKED = 7: Bit 7 This object is a marked object.

enum [anonymous]

Object Action Control Point Feature bits.

Values:

enumerator BT_OTS_OACP_FEAT_CREATE = 0: Bit 0 OACP Create Op Code Supported.

enumerator BT_OTS_OACP_FEAT_DELETE = 1: Bit 1 OACP Delete Op Code Supported

enumerator BT_OTS_OACP_FEAT_CHECKSUM = 2: Bit 2 OACP Calculate Checksum Op Code Supported.

enumerator BT_OTS_OACP_FEAT_EXECUTE = 3: Bit 3 OACP Execute Op Code Supported.

enumerator BT_OTS_OACP_FEAT_READ = 4: Bit 4 OACP Read Op Code Supported.

enumerator BT_OTS_OACP_FEAT_WRITE = 5: Bit 5 OACP Write Op Code Supported.

enumerator BT_OTS_OACP_FEAT_APPEND = 6: Bit 6 Appending Additional Data to Objects Supported

enumerator BT_OTS_OACP_FEAT_TRUNCATE = 7: Bit 7 Truncation of Objects Supported.

enumerator BT_OTS_OACP_FEAT_PATCH = 8: Bit 8 Patching of Objects Supported

enumerator BT_OTS_OACP_FEAT_ABORT = 9: Bit 9 OACP Abort Op Code Supported.

enum bt_ots_oacp_write_op_mode

Values:

enumerator BT_OTS_OACP_WRITE_OP_MODE_NONE = 0

enumerator BT_OTS_OACP_WRITE_OP_MODE_TRUNCATE = BIT(1)

enum [anonymous]

Object List Control Point Feature bits.

Values:

enumerator BT_OTS_OLCP_FEAT_GO_TO = 0: Bit 0 OLCP Go To Op Code Supported.

enumerator BT_OTS_OLCP_FEAT_ORDER = 1: Bit 1 OLCP Order Op Code Supported.

enumerator BT_OTS_OLCP_FEAT_NUM_REQ = 2: Bit 2 OLCP Request Number of Objects Op Code Supported.

enumerator BT_OTS_OLCP_FEAT_CLEAR = 3: Bit 3 OLCP Clear Marking Op Code Supported.

enum [anonymous]

Object metadata request bit field values.

Values:

enumerator BT_OTS_METADATA_REQ_NAME = BIT(0): Request object name.

enumerator BT_OTS_METADATA_REQ_TYPE = BIT(1): Request object type.

enumerator BT_OTS_METADATA_REQ_SIZE = BIT(2): Request object size.

enumerator BT_OTS_METADATA_REQ_CREATED = BIT(3): Request object first created time.

enumerator BT_OTS_METADATA_REQ_MODIFIED = BIT(4): Request object last modified time.

enumerator BT_OTS_METADATA_REQ_ID = BIT(5): Request object ID.

enumerator BT_OTS_METADATA_REQ_PROPS = BIT(6): Request object properties.

enumerator BT_OTS_METADATA_REQ_ALL = 0x7F: Request all object metadata.

Functions

int bt_ots_obj_add(struct bt_ots *ots, const struct bt_ots_obj_add_param *param)

Add an object to the OTS instance.

This function adds an object to the OTS database. When the object is being added, a callback obj_created() is called to notify the user about a new object ID.

Parameters:

ots – OTS instance.
param – Object addition parameters.

Returns:

ID of created object in case of success.

Returns:

negative value in case of error.

int bt_ots_obj_delete(struct bt_ots *ots, uint64_t id)

Delete an object from the OTS instance.

This function deletes an object from the OTS database. When the object is deleted a callback obj_deleted() is called to notify the user about this event. At this point, it is possible to free allocated buffer for object data.

Parameters:

ots – OTS instance.
id – ID of the object to be deleted (uint48).

Returns:

0 in case of success or negative value in case of error.

void *bt_ots_svc_decl_get(struct bt_ots *ots)

Get the service declaration attribute.

This function is enabled for CONFIG_BT_OTS_SECONDARY_SVC configuration. The first service attribute can be included in any other GATT service.

Parameters:

ots – OTS instance.

Returns:

The first OTS attribute instance.

int bt_ots_init(struct bt_ots *ots, struct bt_ots_init_param *ots_init)

Initialize the OTS instance.

Parameters:

ots – OTS instance.
ots_init – OTS initialization descriptor.

Returns:

0 in case of success or negative value in case of error.

struct bt_ots *bt_ots_free_instance_get(void)

Get a free instance of OTS from the pool.

Returns:: OTS instance in case of success or NULL in case of error.

int bt_ots_client_register(struct bt_ots_client *ots_inst)

Register an Object Transfer Service Instance.

Register an Object Transfer Service instance discovered on the peer. Call this function when an OTS instance is discovered (discovery is to be handled by the higher layer).

Parameters:

ots_inst – [in] Discovered OTS instance.

Returns:

int 0 if success, ERRNO on failure.

int bt_ots_client_unregister(uint8_t index)

Unregister an Object Transfer Service Instance.

Unregister an Object Transfer Service instance when disconnect from the peer. Call this function when an ACL using OTS instance is disconnected.

Parameters:

index – [in] Index of OTS instance.

Returns:

int 0 if success, ERRNO on failure.

uint8_t bt_ots_client_indicate_handler(struct bt_conn *conn, struct bt_gatt_subscribe_params *params, const void *data, uint16_t length)

OTS Indicate Handler function.

Set this function as callback for indicate handler when discovering OTS.

Parameters:

conn – Connection object. May be NULL, indicating that the peer is being unpaired.
params – Subscription parameters.
data – Attribute value data. If NULL then subscription was removed.
length – Attribute value length.

int bt_ots_client_read_feature(struct bt_ots_client *otc_inst, struct bt_conn *conn)

Read the OTS feature characteristic.

Parameters:

otc_inst – Pointer to the OTC instance.
conn – Pointer to the connection object.

Returns:

int 0 if success, ERRNO on failure.

int bt_ots_client_select_id(struct bt_ots_client *otc_inst, struct bt_conn *conn, uint64_t obj_id)

Select an object by its Object ID.

Parameters:

otc_inst – Pointer to the OTC instance.
conn – Pointer to the connection object.
obj_id – Object’s ID.

Returns:

int 0 if success, ERRNO on failure.

int bt_ots_client_select_first(struct bt_ots_client *otc_inst, struct bt_conn *conn)

Select the first object.

Parameters:

otc_inst – Pointer to the OTC instance.
conn – Pointer to the connection object.

Returns:

int 0 if success, ERRNO on failure.

int bt_ots_client_select_last(struct bt_ots_client *otc_inst, struct bt_conn *conn)

Select the last object.

Parameters:

otc_inst – Pointer to the OTC instance.
conn – Pointer to the connection object.

Returns:

int 0 if success, ERRNO on failure.

int bt_ots_client_select_next(struct bt_ots_client *otc_inst, struct bt_conn *conn)

Select the next object.

Parameters:

otc_inst – Pointer to the OTC instance.
conn – Pointer to the connection object.

Returns:

int 0 if success, ERRNO on failure.

int bt_ots_client_select_prev(struct bt_ots_client *otc_inst, struct bt_conn *conn)

Select the previous object.

Parameters:

otc_inst – Pointer to the OTC instance.
conn – Pointer to the connection object.

Returns:

int 0 if success, ERRNO on failure.

int bt_ots_client_read_object_metadata(struct bt_ots_client *otc_inst, struct bt_conn *conn, uint8_t metadata)

Read the metadata of the current object.

The metadata are returned in the obj_metadata_read() callback.

Parameters:

otc_inst – Pointer to the OTC instance.
conn – Pointer to the connection object.
metadata – Bitfield (BT_OTS_METADATA_REQ_*) of the metadata to read.

Returns:

int 0 if success, ERRNO on failure.

int bt_ots_client_read_object_data(struct bt_ots_client *otc_inst, struct bt_conn *conn)

Read the data of the current selected object.

This will trigger an OACP read operation for the current size of the object with a 0 offset and then expect receiving the content via the L2CAP CoC.

The data of the object are returned in the obj_data_read() callback.

Parameters:

otc_inst – Pointer to the OTC instance.
conn – Pointer to the connection object.

Returns:

int 0 if success, ERRNO on failure.

int bt_ots_client_write_object_data(struct bt_ots_client *otc_inst, struct bt_conn *conn, const void *buf, size_t len, off_t offset, enum bt_ots_oacp_write_op_mode mode)

Write the data of the current selected object.

This will trigger an OACP write operation for the current object with a specified offset and then expect transferring the content via the L2CAP CoC.

The length of the data written to object is returned in the obj_data_written() callback.

Parameters:

otc_inst – Pointer to the OTC instance.
conn – Pointer to the connection object.
buf – Pointer to the data buffer to be written.
len – Size of data.
offset – Offset to write, usually 0.
mode – Mode Parameter for OACP Write Op Code. See bt_ots_oacp_write_op_mode.

Returns:

int 0 if success, ERRNO on failure.

int bt_ots_client_get_object_checksum(struct bt_ots_client *otc_inst, struct bt_conn *conn, off_t offset, size_t len)

Get the checksum of the current selected object.

This will trigger an OACP calculate checksum operation for the current object with a specified offset and length.

The checksum goes to OACP IND and obj_checksum_calculated() callback.

Parameters:

otc_inst – Pointer to the OTC instance.
conn – Pointer to the connection object.
offset – Offset to calculate, usually 0.
len – Len of data to calculate checksum for. May be less than the current object’s size, but shall not be larger.

Returns:

int 0 if success, ERRNO on failure.

int bt_ots_client_decode_dirlisting(uint8_t *data, uint16_t length, bt_ots_client_dirlisting_cb cb)

Decode Directory Listing object into object metadata.

If the Directory Listing object contains multiple objects, then the callback will be called for each of them.

Parameters:

data – The data received for the directory listing object.
length – Length of the data.
cb – The callback that will be called for each object.

static inline int bt_ots_obj_id_to_str(uint64_t obj_id, char *str, size_t len)

Converts binary OTS Object ID to string.

Parameters:

obj_id – Object ID.
str – Address of user buffer with enough room to store formatted string containing binary Object ID.
len – Length of data to be copied to user string buffer. Refer to BT_OTS_OBJ_ID_STR_LEN about recommended value.

Returns:

Number of successfully formatted bytes from binary ID.

void bt_ots_metadata_display(struct bt_ots_obj_metadata *metadata, uint16_t count)

Displays one or more object metadata as text with LOG_INF.

Parameters:

metadata – Pointer to the first (or only) metadata in an array.
count – Number of metadata objects to display information of.

struct bt_ots_obj_type: #include <ots.h>

Type of an OTS object.

struct bt_ots_obj_size

#include <ots.h>

Descriptor for OTS Object Size parameter.

Public Members

uint32_t cur: Current Size.

uint32_t alloc: Allocated Size.

struct bt_ots_feat: #include <ots.h>

Features of the OTS.

struct bt_ots_date_time: #include <ots.h>

Date and Time structure.

struct bt_ots_obj_metadata

#include <ots.h>

Metadata of an OTS object.

Used by the server as a descriptor for OTS object initialization. Used by the client to present object metadata to the application.

Public Members

struct bt_ots_obj_type type: Object Type.

struct bt_ots_obj_size size: Object Size.

uint32_t props: Object Properties.

struct bt_ots_obj_add_param

#include <ots.h>

Descriptor for OTS object addition.

Public Members

uint32_t size: Object size to allocate.

struct bt_ots_obj_type type: Object type.

struct bt_ots_obj_created_desc

#include <ots.h>

Descriptor for OTS created object.

Descriptor for OTS object created by the application. This descriptor is returned by bt_ots_cb::obj_created callback which contains further documentation on distinguishing between server and client object creation.

Public Members

char *name

Object name.

The object name as a NULL terminated string.

When the server creates a new object the name shall be > 0 and <= BT_OTS_OBJ_MAX_NAME_LEN When the client creates a new object the name shall be an empty string

struct bt_ots_obj_size size

Object size.

bt_ots_obj_size::alloc shall be >= bt_ots_obj_add_param::size

When the server creates a new object bt_ots_obj_size::cur shall be <= bt_ots_obj_add_param::size When the client creates a new object bt_ots_obj_size::cur shall be 0

uint32_t props: Object properties.

struct bt_ots_cb

#include <ots.h>

OTS callback structure.

Public Members

int (*obj_created)(struct bt_ots *ots, struct bt_conn *conn, uint64_t id, const struct bt_ots_obj_add_param *add_param, struct bt_ots_obj_created_desc *created_desc)

Object created callback.

This callback is called whenever a new object is created. Application can reject this request by returning an error when it does not have necessary resources to hold this new object. This callback is also triggered when the server creates a new object with bt_ots_obj_add() API.

Param ots:: OTS instance.
Param conn:: The connection that is requesting object creation or NULL if object is created by bt_ots_obj_add().
Param id:: Object ID.
Param add_param:: Object creation requested parameters.
Param created_desc:: Created object descriptor that shall be filled by the receiver of this callback.
Return:: 0 in case of success or negative value in case of error.
Return:: -ENOTSUP if object type is not supported
Return:: -ENOMEM if no available space for new object.
Return:: -EINVAL if an invalid parameter is provided
Return:: other negative values are treated as a generic operation failure

int (*obj_deleted)(struct bt_ots *ots, struct bt_conn *conn, uint64_t id)

Object deleted callback.

This callback is called whenever an object is deleted. It is also triggered when the server deletes an object with bt_ots_obj_delete() API.

Param ots:: OTS instance.
Param conn:: The connection that deleted the object or NULL if this request came from the server.
Param id:: Object ID.
Retval When:: an error is indicated by using a negative value, the object delete procedure is aborted and a corresponding failed status is returned to the client.
Return:: 0 in case of success.
Return:: -EBUSY if the object is locked. This is generally not expected to be returned by the application as the OTS layer tracks object accesses. An object locked status is returned to the client.
Return:: Other negative values in case of error. A generic operation failed status is returned to the client.

void (*obj_selected)(struct bt_ots *ots, struct bt_conn *conn, uint64_t id)

Object selected callback.

This callback is called on successful object selection.

Param ots:: OTS instance.
Param conn:: The connection that selected new object.
Param id:: Object ID.

ssize_t (*obj_read)(struct bt_ots *ots, struct bt_conn *conn, uint64_t id, void **data, size_t len, off_t offset)

Object read callback.

This callback is called multiple times during the Object read operation. OTS module will keep requesting successive Object fragments from the application until the read operation is completed. The end of read operation is indicated by NULL data parameter.

Param ots:: OTS instance.
Param conn:: The connection that read object.
Param id:: Object ID.
Param data:: In: NULL once the read operations is completed. Out: Next chunk of data to be sent.
Param len:: Remaining length requested by the client.
Param offset:: Object data offset.
Return:: Data length to be sent via data parameter. This value shall be smaller or equal to the len parameter.
Return:: Negative value in case of an error.

ssize_t (*obj_write)(struct bt_ots *ots, struct bt_conn *conn, uint64_t id, const void *data, size_t len, off_t offset, size_t rem)

Object write callback.

This callback is called multiple times during the Object write operation. OTS module will keep providing successive Object fragments to the application until the write operation is completed. The offset and length of each write fragment is validated by the OTS module to be within the allocated size of the object. The remaining length indicates data length remaining to be written and will decrease each write iteration until it reaches 0 in the last write fragment.

Param ots:: OTS instance.
Param conn:: The connection that wrote object.
Param id:: Object ID.
Param data:: Next chunk of data to be written.
Param len:: Length of the current chunk of data in the buffer.
Param offset:: Object data offset.
Param rem:: Remaining length in the write operation.
Return:: Number of bytes written in case of success, if the number of bytes written does not match len, -EIO is returned to the L2CAP layer.
Return:: A negative value in case of an error.
Return:: -EINPROGRESS has a special meaning and is unsupported at the moment. It should not be returned.

void (*obj_name_written)(struct bt_ots *ots, struct bt_conn *conn, uint64_t id, const char *cur_name, const char *new_name)

Object name written callback.

This callback is called when the object name is written. This is a notification to the application that the object name will be updated by the OTS service implementation.

Param ots:: OTS instance.
Param conn:: The connection that wrote object name.
Param id:: Object ID.
Param cur_name:: Current object name.
Param new_name:: New object name.

int (*obj_cal_checksum)(struct bt_ots *ots, struct bt_conn *conn, uint64_t id, off_t offset, size_t len, void **data)

Object Calculate checksum callback.

This callback is called when the OACP Calculate Checksum procedure is performed. Because object data is opaque to OTS, the application is the only one who knows where data is and should return pointer of actual object data.

Param ots:: [in] OTS instance.
Param conn:: [in] The connection that wrote object.
Param id:: [in] Object ID.
Param offset:: [in] The first octet of the object contents need to be calculated.
Param len:: [in] The length number of octets object name.
Param data:: [out] Pointer of actual object data.
Return:: 0 to accept, or any negative value to reject.

struct bt_ots_init_param: #include <ots.h>

Descriptor for OTS initialization.

struct bt_ots_client: #include <ots.h>

OTS client instance.

struct bt_ots_client_cb

#include <ots.h>

OTS client callback structure.

Public Members

void (*obj_selected)(struct bt_ots_client *ots_inst, struct bt_conn *conn, int err)

Callback function when a new object is selected.

Called when the a new object is selected and the current object has changed. The cur_object in ots_inst will have been reset, and metadata should be read again with bt_ots_client_read_object_metadata().

Param ots_inst:: Pointer to the OTC instance.
Param conn:: The connection to the peer device.
Param err:: Error code (bt_ots_olcp_res_code).

int (*obj_data_read)(struct bt_ots_client *ots_inst, struct bt_conn *conn, uint32_t offset, uint32_t len, uint8_t *data_p, bool is_complete)

Callback function for the data of the selected object.

Called when the data of the selected object are read using bt_ots_client_read_object_data().

Param ots_inst:: Pointer to the OTC instance.
Param conn:: The connection to the peer device.
Param offset:: Offset of the received data.
Param len:: Length of the received data.
Param data_p:: Pointer to the received data.
Param is_complete:: Indicate if the whole object has been received.
Return:: int BT_OTS_STOP or BT_OTS_CONTINUE. BT_OTS_STOP can be used to stop reading.

void (*obj_metadata_read)(struct bt_ots_client *ots_inst, struct bt_conn *conn, int err, uint8_t metadata_read)

Callback function for metadata of the selected object.

Called when metadata of the selected object are read using bt_ots_client_read_object_metadata(). Not all of the metadata may have been initialized.

Param ots_inst:: Pointer to the OTC instance.
Param conn:: The connection to the peer device.
Param err:: Error value. 0 on success, GATT error or ERRNO on fail.
Param metadata_read:: Bitfield of the metadata that was successfully read.

void (*obj_data_written)(struct bt_ots_client *ots_inst, struct bt_conn *conn, size_t len)

Callback function for the data of the write object.

Called when the data of the selected object is written using bt_ots_client_write_object_data().

Param ots_inst:: Pointer to the OTC instance.
Param conn:: The connection to the peer device.
Param len:: Length of the written data.

void (*obj_checksum_calculated)(struct bt_ots_client *ots_inst, struct bt_conn *conn, int err, uint32_t checksum)

Callback function when checksum indication is received.

Called when the oacp_ind_handler received response of OP BT_GATT_OTS_OACP_PROC_CHECKSUM_CALC.

Param ots_inst:: Pointer to the OTC instance.
Param conn:: The connection to the peer device.
Param err:: Error code (bt_gatt_ots_oacp_res_code).
Param checksum:: Checksum if error code is BT_GATT_OTS_OACP_RES_SUCCESS, otherwise 0.