API Reference

General

group otslib

Object Transfer Service.

Defines

OTSLIB_ACTION_FEATURE_CREATE

Action Feature Create.

OTSLIB_ACTION_FEATURE_DELETE

Action Feature Delete.

OTSLIB_ACTION_FEATURE_CHECKSUM

Action Feature Calculate Checksum.

OTSLIB_ACTION_FEATURE_EXECUTE

Action Feature Execute.

OTSLIB_ACTION_FEATURE_READ

Action Feature Read.

OTSLIB_ACTION_FEATURE_WRITE

Action Feature Write.

OTSLIB_ACTION_FEATURE_APPEND

Action Feature Appending Additional Data.

OTSLIB_ACTION_FEATURE_TRUNCATE

Action Feature Truncate.

OTSLIB_ACTION_FEATURE_PATCH

Action Feature Patch.

OTSLIB_ACTION_FEATURE_ABORT

Action Feature Abort.

OTSLIB_LIST_FEATURE_GOTO

List Feature Go To.

OTSLIB_LIST_FEATURE_ORDER

List Feature Order.

OTSLIB_LIST_FEATURE_NUMBER_OBJECTS

List Feature Request Number of Objects.

OTSLIB_LIST_FEATURE_CLEAR_MARKING

List Feature Clear Marking.

Functions

int otslib_open(gatt_connection_t *connection, const char *dst, void **adapter)

Open otslib Adapter.

Open an otslib adapter that can bue used for further interactions with otslib. It is responsibility of the user to close the adapter using otslib_close to prevent a resource leak.

Parameters

  • connection – connection handle provided by gattlib

  • dst – bluetooth address of the device to open an adapter for

  • adapter – [out] opened adapter

Return values

  • -EINVAL – if any of the input parameters are NULL if the provided device address by dst is invalid

  • -ENOMEM – if could not allocate memory for the adapter

  • 0 – when successful

int otslib_close(void *adapter)

Close otslib Adapter.

Close an otslib adapter previously opened by otslib_open. All allocated resources for this adapter are freed.

Parameters

adapter – an otslib adapter

Return values

  • -EINVAL – if adapter is NULL

  • 0 – when successful

Returns

other negative values for other errors

int otslib_action_features(void *adapter, unsigned long *features)

Read Action Features.

Read’s the action features of the OTS service represented by adapter.

Parameters

  • adapter – otslib adapter

  • features – [out] OTSLIB_ACTION_FEATURE_ bitmask of action features

Return values

  • -EINVAL – if the input parameters are NULL

  • 0 – when successful

Returns

other negative values for other errors

int otslib_list_features(void *adapter, unsigned long *features)

Read List Features.

Read’s the list features of the OTS service represented by adapter.

Parameters

  • adapter – otslib adapter

  • features – [out] OTSLIB_LIST_FEATURE_ bitmask of list features

Return values

  • -EINVAL – if the input parameters are NULL

  • 0 – when successful

Returns

other negative values for other errors

struct otslib_object_metadata
#include <otslib.h>

Object Metadata.

Actions

group otslib_action

Action.

Defines

OTSLIB_WRITE_MODE_TRUNCATE

Truncate Write Mode.

Functions

int otslib_create(void *adapter, size_t size, uuid_t *type)

Create Object.

Create an object with allocated size of size and type of type. The type is a generic bluetooth UUID type that supports 16-bit, 32-bit, and 128-bit UUIDs. However, only 16-bit and 128-bit UUIDs are valid for an OTS object type.

Note

Further to the above limitation, currently only 16-byte UUID types are supported.

Parameters

  • adapter – otslib adapter

  • size – object size to create

  • type – object type to create

Return values

  • -EINVAL – if adapter or type are NULL if the server does not support the objet type

  • -ENOTSUP – if type is not a 16-bit UUID if the server does not support object creation

  • -ENOSPC – if the server did not have sufficient resources

  • 0 – when successful

Returns

other negative values for other errors

int otslib_delete(void *adapter)

Delete Object.

Delete the currently selected object.

Parameters

adapter – otslib adapter

Return values

  • -EINVAL – if adapter is NULL

  • -ENOTSUP – if the server does not support delete

  • -ENOENT – if no object is currently selected

  • -EPERM – if the current object does not permit deletion

  • -EBUSY – if the object is currently busy

  • 0 – when successful

Returns

other negative values for other errors

int otslib_read(void *adapter, off_t offset, size_t length, void **buffer)

Read Object.

Read length at offset from the currently selected object.

Parameters

  • adapter – otslib adapter

  • offset – byte offset to read from

  • length – number of bytes to read

  • buffer – [out] pointer to the buffer containing the read data. it is the responsibility of the caller to free this buffer using free().

Return values

  • -EINVAL – if adapter or buffer are NULL

  • -ENOMEM – if buffer memory could not be allocated

  • -ENOTSUP – if the server does not support read

  • -ENOENT – if no object is currently selected

  • -EPERM – if the current object does not permit read

  • -EBADR – if the offset and length result in an invalid read operation

  • -EBUSY – if the object is currently busy

  • -EIO – if the read was unexpectedly terminated

Returns

number of bytes read on success

Returns

other negative values for other errors

int otslib_write(void *adapter, off_t offset, size_t length, unsigned char mode, void *buffer)

Write Object.

Write length at offset to the currently selected object.

Parameters

  • adapter – otslib_adapter

  • offset – byte offset to write to

  • length – number of bytes to write

  • mode – write mode bitmask constructed from OTSLIB_WRITE_MODE_* defines

  • buffer – [out] pointer to the buffer containing the write data.

Return values

  • -EINVAL – if adapter or buffer are NULL

  • -ENOTSUP – if the server does not support write

  • -ENOENT – if no object is currently selected

  • -EPERM – if the current object does not permit write if the patching or truncation was attempted but they are not permitted

  • -EBADR – if the offset and length result in an invalid write operation

  • -EBUSY – if the object is currently busy

Returns

number of bytes read on success

Returns

other negative values for other errors

List

group otslib_list

List.

Functions

int otslib_first(void *adapter)

Select the first object.

Parameters

adapter – an otslib adapter

Return values

  • -EINVAL – if adapter is invalid

  • 0 – when successful

  • other – negative values for other errors

int otslib_last(void *adapter)

Select the last object.

Parameters

adapter – an otslib adapter

Return values

  • -EINVAL – if adapter is invalid

  • 0 – when successful

  • other – negative values for other errors

int otslib_previous(void *adapter)

Select the previous object.

Parameters

adapter – an otslib adapter

Return values

  • -EINVAL – if adapter is invalid

  • 0 – when successful

  • other – negative values for other errors

int otslib_next(void *adapter)

Select the next object.

Parameters

adapter – an otslib adapter

Return values

  • -EINVAL – if adapter is invalid

  • 0 – when successful

  • other – negative values for other errors

int otslib_goto(void *adapter, uint64_t id)

Select the object with specified ID.

Parameters

  • adapter – an otslib adapter

  • id – object ID to select

Return values

  • -EINVAL – if adapter or id is invalid

  • 0 – when successful

  • other – negative values for other errors

Metadata

group otslib_metadata

Metadata.

Defines

OTSLIB_OBJECT_PROPERTY_DELETE

Object Property Delete.

OTSLIB_OBJECT_PROPERTY_EXECUTE

Object Property Execute.

OTSLIB_OBJECT_PROPERTY_READ

Object Property Read.

OTSLIB_OBJECT_PROPERTY_WRITE

Object Property Write.

OTSLIB_OBJECT_PROPERTY_APPEND

Object Property Append.

OTSLIB_OBJECT_PROPERTY_TRUNCATE

Object Property Truncate.

OTSLIB_OBJECT_PROPERTY_PATCH

Object Property Patch.

OTSLIB_OBJECT_PROPERTY_MARK

Object Property Mark.

Functions

int otslib_get_name(void *adapter, char **name)

Get Object Name.

The object name returned is dynamically allocated, it is the caller’s responsibility to free the memory when no longer needed to prevent a resource leak.

Parameters

  • adapter – otslib adapter

  • name – [out] object’s name

Returns

-EINVAL if adapter or name is NULL

Returns

-ENOMEM if could not allocate memory for name

Returns

0 when successful

Returns

other negative values for other errors

int otslib_set_name(void *adapter, const char *name)

Set Object Name.

Parameters

  • adapter – otslib adapter

  • name – object name to set

Returns

-EINVAL if adapter or name is NULL, or name length is too long

Returns

0 when successful

Returns

other negative values for other errors

int otslib_type(void *adapter, uuid_t *uuid)

Get Object Type.

Parameters

  • adapter – otslib adapter

  • uuid – [out] type uuid

Returns

-EINVAL if adapter or uuid is NULL

Returns

0 when successful

Returns

other negative values for other errors

int otslib_size(void *adapter, size_t *current, size_t *allocated)

Get Object Size.

Parameters

  • adapter – otslib adapter

  • current – [out] object’s current size

  • allocated – [out] object’s allocated size

Returns

-EINVAL if adapter is NULL or both current and allocated are NULL

Returns

-EIO if object size could not be read

Returns

0 when successful

Returns

other negative values for other errors

int otslib_id(void *adapter, unsigned long long *id)

Get Object ID.

Parameters

  • adapter – otslib adapter

  • id – [out] object’s ID

Returns

-EINVAL if adapter or id is NULL

Returns

-EIO if object ID could not be read

Returns

0 when successful

Returns

other negative values for other errors

int otslib_properties(void *adapter, unsigned long *properties)

Get Object Properties.

Parameters

  • adapter – otslib adapter

  • properties – [out] OTSLIB_OBJECT_PROPERTY_ bitmask of object’s properties

Returns

-EINVAL if adapter or properties is NULL

Returns

-EIO if object properties could not be read

Returns

0 when successful

Returns

other negative values for other errors

Directory Listing

group otslib_directory

Directory.

Defines

OTSLIB_OBJECT_ID_DIRECTORY_LISTING

Directory Listing Object ID.

OTSLIB_DIRECTORY_FLAG_OBJ_TYPE_UUID128

Directory Record UUID128 Type Flag.

OTSLIB_DIRECTORY_FLAG_CURRENT_SIZE

Directory Record Current Size Present Flag.

OTSLIB_DIRECTORY_FLAG_ALLOCATED_SIZE

Directory Record Allocated Size Present Flag.

OTSLIB_DIRECTORY_FLAG_FIRST_CREATED

Directory Record First Created Present Flag.

OTSLIB_DIRECTORY_FLAG_LAST_MODIFIED

Directory Record Last Modified Present Flag.

OTSLIB_DIRECTORY_FLAG_PROPERTIES

Directory Record Properties Present Flag.

OTSLIB_DIRECTORY_FLAG_EXTENDED

Directory Record Extended Fields Present Flag.

Functions

int otslib_directory_read(void *adapter, void **buffer)

Read Directory Listing Object.

Read the Directory Listing Object and return the contents in buffer.

Parameters

  • adapter – otslib adapter

  • buffer – [out] pointer to the buffer containing the read data. it is the responsibility of the caller to free this buffer using free().

Return values

  • -EINVAL – if adapter or buffer are NULL

  • other – negative values for other errors

  • size – of the directory listing object in buffer on success

int otslib_directory_for_each(void *buffer, size_t length, void *user_data, int (*callback)(const struct otslib_object_metadata *metadata, void *user_data))

Iterate Over Directory Listing Entries.

Iterate over the Directory Listing Entries and call the user provided callback for each entry. Iteration is stopped if the user provided callback returns a value other than 0.

Parameters

  • buffer – the entire Directory Listing Object buffer read by otslib_directory_read

  • length – the size of the Directory Listing Object in the buffer as returned by otslib_directory_read

  • user_data – arbitrary user data to be passed to the callback

  • callback – user callback to be called for each entry

Return values

-EINVAL – if adapter or buffer are NULL

Returns

other negative values for other errors

Returns

0 on success