Object Transfer Service

[中文]

The Object Transfer Service provides management and control features supporting bulk data transfers which occur via a separate L2CAP connection-oriented channel.

Examples

bluetooth/ble_services/ble_ots.

API Reference

Header File

Functions

esp_err_t esp_ble_ots_get_feature(esp_ble_ots_feature_t *out_val)

Read the value of OTS Feature Characteristic.

Parameters

out_val – [out] The pointer to store the OTS Feature Value.

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong parameter

esp_err_t esp_ble_ots_set_feature(esp_ble_ots_feature_t *in_val)

Set the value of OTS Feature Characteristic.

Parameters

in_val – [in] The pointer to store OTS Feature value.

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong initialization

esp_err_t esp_ble_ots_get_name(uint8_t *out_buf, size_t buf_len, size_t *out_len)

Read the value of Object Name Characteristic.

Parameters

  • out_buf – [out] The pointer to store the Object Name.

  • buf_len – [in] Maximum length of the output buffer.

  • out_len – [out] The pointer to store the actual length of the Object Name (can be NULL if not needed).

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong parameter

esp_err_t esp_ble_ots_set_name(const uint8_t *in_val, size_t in_len)

Set the Object Name Characteristic value.

Parameters

  • in_val – [in] The pointer to the Object Name data.

  • in_len – [in] The length of the Object Name data.

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong initialization

esp_err_t esp_ble_ots_get_type(uint16_t *out_val)

Read the value of Object Type Characteristic value.

Parameters

out_val – [out] The pointer to store the Object Type.

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong parameter

esp_err_t esp_ble_ots_set_type(uint16_t *in_val)

Set the Object Type Characteristic value.

Parameters

in_val – [in] The pointer to store Object Type.

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong initialization

esp_err_t esp_ble_ots_get_size(esp_ble_ots_size_t *out_val)

Read the value of Object Size Characteristic value.

Parameters

out_val – [out] The pointer to store the Object Size.

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong parameter

esp_err_t esp_ble_ots_set_size(esp_ble_ots_size_t *in_val)

Set the Object Size Characteristic value.

Parameters

in_val – [in] The pointer to store Object Size.

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong initialization

esp_err_t esp_ble_ots_get_first_create_time(esp_ble_ots_utc_t *out_val)

Read the value of Object First Create Characteristic value.

Parameters

out_val – [out] The pointer to store the Object First Create Time.

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong parameter

esp_err_t esp_ble_ots_set_first_create_time(esp_ble_ots_utc_t *in_val)

Set the Object First Create Characteristic value.

Parameters

in_val – [in] The pointer to store the Object First Create Time.

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong initialization

esp_err_t esp_ble_ots_get_last_modify_time(esp_ble_ots_utc_t *out_val)

Read the value of Object Last Modify Characteristic value.

Parameters

out_val – [out] The pointer to store the Object Last Modify Time.

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong parameter

esp_err_t esp_ble_ots_set_last_modify_time(esp_ble_ots_utc_t *in_val)

Set the Object Last Modify Characteristic value.

Parameters

in_val – [in] The pointer to store the Object Last Modify Time.

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong initialization

esp_err_t esp_ble_ots_get_id(esp_ble_ots_id_t *out_val)

Read the value of Object ID value.

Parameters

out_val – [out] The pointer to store the Object ID.

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong parameter

esp_err_t esp_ble_ots_set_id(esp_ble_ots_id_t *in_val)

Set the Object ID value.

Parameters

in_val – [in] The pointer to store the Object ID.

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong initialization

esp_err_t esp_ble_ots_get_prop(esp_ble_ots_prop_t *out_val)

Read the value of Object Properties value.

Parameters

out_val – [out] The pointer to store the Object Properties.

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong parameter

esp_err_t esp_ble_ots_set_prop(esp_ble_ots_prop_t *in_val)

Set the Object Properties value.

Parameters

in_val – [in] The pointer to store the Object Properties.

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong initialization

esp_err_t esp_ble_ots_get_oacp(esp_ble_ots_oacp_t *out_val)

Read the value of Object Action Control Point value.

Parameters

out_val – [out] The pointer to store the Object Action Control Point.

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong parameter

esp_err_t esp_ble_ots_set_oacp(esp_ble_ots_oacp_t *in_val, bool need_send)

Set the Object Action Control Point value.

Parameters

  • in_val – [in] The pointer to store the Object Action Control Point value

  • need_send – [in] If set to true, the OACP Value will send to remote client.

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong initialization

esp_err_t esp_ble_ots_get_olcp(esp_ble_ots_olcp_t *out_val)

Read the value of Object List Control Point value.

Parameters

out_val – [out] The pointer to store the Object List Control Point.

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong parameter

esp_err_t esp_ble_ots_set_olcp(esp_ble_ots_olcp_t *in_val, bool need_send)

Set the Object List Control Point value.

Parameters

  • in_val – [in] The pointer to store the Object List Control Point value

  • need_send – [in] If set to true, the OLCP Value will send to remote client.

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong initialization

esp_err_t esp_ble_ots_get_filter(esp_ble_ots_filter_t *out_val)

Read the value of Object Filter value.

Parameters

out_val – [out] The pointer to store the Object Filter.

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong parameter

esp_err_t esp_ble_ots_set_filter(esp_ble_ots_filter_t *in_val)

Set the value of Object Filter value.

Parameters

in_val – [in] The pointer to store the Object Filter.

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong initialization

esp_err_t esp_ble_ots_get_change(esp_ble_ots_change_t *out_val)

Read the value of Object Change value.

Parameters

out_val – [out] The pointer to store the Object Change.

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong parameter

esp_err_t esp_ble_ots_set_change(esp_ble_ots_change_t *in_val, bool need_send)

Set the Object Change value.

Parameters

  • in_val – [in] The pointer to store the Object Change.

  • need_send – [in] If set to true, the Object Change value will send to remote client.

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong initialization

esp_err_t esp_ble_ots_init(void)

Initialization Object Transfer Service.

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong initialization

  • ESP_ERR_NO_MEM if failed to create mutex

  • ESP_FAIL on error

esp_err_t esp_ble_ots_deinit(void)

Deinitialization Object Transfer Service.

Returns

  • ESP_OK on successful

  • ESP_ERR_INVALID_ARG on wrong deinitialization

  • ESP_FAIL on error

Structures

struct esp_ble_ots_feature_t

OTS Feature Characteristic.

Public Members

uint32_t create_op

Create Op Code Supported. 0: False, 1: True

uint32_t delete_op

Delete Op Code Supported. 0: False, 1: True

uint32_t calculate_op

Calculate Checksum Op Code Supported. 0: False, 1: True

uint32_t execute_op

Execute Op Code Supported. 0: False, 1: True

uint32_t read_op

Read Op Code Supported. 0: False, 1: True

uint32_t write_op

Write Op Code Supported. 0: False, 1: True

uint32_t appending_op

Appending Op Code Supported. 0: False, 1: True

uint32_t truncation_op

Truncation Op Code Supported. 0: False, 1: True

uint32_t patching_op

Patching Op Code Supported. 0: False, 1: True

uint32_t abort_op

Abort Op Code Supported. 0: False, 1: True

struct esp_ble_ots_feature_t::[anonymous] oacp

The structure of the OACP Features field

uint32_t goto_op

Go to Op Code Supported. 0: False, 1: True

uint32_t order_op

Order Op Code Supported. 0: False, 1: True

uint32_t req_num_op

Request Number of Objects Op Code Supported. 0: False, 1: True

uint32_t clear_mark_op

Clear Marking Op Code Supported. 0: False, 1: True

struct esp_ble_ots_feature_t::[anonymous] olcp

The structure of the OLCP Features field

struct esp_ble_ots_size_t

Object Size Characteristic.

Public Members

uint32_t current_size

Current Object Size

uint32_t allocated_size

Allocated Object Size

struct esp_ble_ots_utc_t

UTC.

Public Members

uint16_t year

Year as defined by the Gregorian calendar, Valid range 1582 to 9999

uint8_t month

Month of the year as defined by the Gregorian calendar, Valid range 1 (January) to 12 (December)

uint8_t day

Day of the month as defined by the Gregorian calendar, Valid range 1 to 31

uint8_t hours

Number of hours past midnight, Valid range 0 to 23

uint8_t minutes

Number of minutes since the start of the hour. Valid range 0 to 59

uint8_t seconds

Number of seconds since the start of the minute. Valid range 0 to 59

struct esp_ble_ots_id_t

Object ID.

Public Members

uint8_t id[6]

Allocated ID. Valid range 0x000000000100 to 0xffffffffffff

struct esp_ble_ots_prop_t

Object Properties Characteristic.

Public Members

uint32_t delete_prop

Deletion of this object is permitted. 0: False, 1: True

uint32_t execute_prop

Execute of this object is permitted. 0: False, 1: True

uint32_t read_prop

Reading of this object is permitted. 0: False, 1: True

uint32_t write_prop

Writing of this object is permitted. 0: False, 1: True

uint32_t append_prop

Appending of this object is permitted. 0: False, 1: True

uint32_t truncate_prop

Truncation of this object is permitted. 0: False, 1: True

uint32_t patch_prop

Patching of this object is permitted. 0: False, 1: True

uint32_t mark_prop

This object is a marked object. 0: False, 1: True

struct esp_ble_ots_oacp_t

Object Action Control Point (OACP)

Public Members

uint8_t op_code

OACP op code

uint8_t parameter[20]

OACP parameter

struct esp_ble_ots_olcp_t

Object List Control Point (OLCP)

Public Members

uint8_t op_code

OLCP op code

uint8_t parameter[6]

OLCP parameter

struct esp_ble_ots_olcp_rsp_t

Object List Control Point (OLCP) Response Value.

Public Members

uint8_t req_code

OLCP op code

uint8_t rsp_code

OLCP rsp op code

uint8_t rsp_parameter[6]

OLCP rsp parameter

struct esp_ble_ots_filter_t

Object List Filter Characteristic.

Public Members

uint8_t filter

Object filter type

uint8_t filter_parameter[BLE_OTS_ATT_VAL_LEN]

Object filter parameter

struct esp_ble_ots_change_t

Object Change Characteristic.

Public Members

uint8_t flag

Flag fields

uint8_t object_id[6]

Object ID

Macros

BLE_OTS_ATT_VAL_LEN

Attribute value length

BLE_OTS_UUID16
BLE_OTS_CHR_UUID16_OTS_FEATURE
BLE_OTS_CHR_UUID16_OBJECT_NAME
BLE_OTS_CHR_UUID16_OBJECT_TYPE
BLE_OTS_CHR_UUID16_OBJECT_SIZE
BLE_OTS_CHR_UUID16_OBJECT_FIRST_CREATED
BLE_OTS_CHR_UUID16_OBJECT_LAST_MODIFIED
BLE_OTS_CHR_UUID16_OBJECT_ID
BLE_OTS_CHR_UUID16_OBJECT_PROP
BLE_OTS_CHR_UUID16_OBJECT_ACTION_CONTROL_POINT
BLE_OTS_CHR_UUID16_OBJECT_LIST_CONTROL_POINT
BLE_OTS_CHR_UUID16_OBJECT_LIST_FILTER
BLE_OTS_CHR_UUID16_OBJECT_CHANGED
BLE_OTS_OACP_CREATE
BLE_OTS_OACP_DELETE
BLE_OTS_OACP_CALCULATE_CHECKSUM
BLE_OTS_OACP_EXECUTE
BLE_OTS_OACP_READ
BLE_OTS_OACP_WRITE
BLE_OTS_OACP_ABORT
BLE_OTS_OACP_RESPONSE
BLE_OTS_OACP_RSP_SUCCESS
BLE_OTS_OACP_RSP_NOT_SUPPORT
BLE_OTS_OACP_RSP_INVALID_PARAMETER
BLE_OTS_OACP_RSP_INSUFFICIENT_RESOURCES
BLE_OTS_OACP_RSP_INVALID_OBJECT
BLE_OTS_OACP_RSP_CHANNEL_UNAVAILABLE
BLE_OTS_OACP_RSP_UNSUPPORT_TYPE
BLE_OTS_OACP_RSP_NOT_PERMIT
BLE_OTS_OACP_RSP_OBJECT_LOCK
BLE_OTS_OACP_RSP_OPERATION_FAIL
BLE_OTS_OLCP_FIRST
BLE_OTS_OLCP_LAST
BLE_OTS_OLCP_PREVIOUS
BLE_OTS_OLCP_NEXT
BLE_OTS_OLCP_GO_TO
BLE_OTS_OLCP_ORDER
BLE_OTS_OLCP_REQ_NUM_OF_OBJ
BLE_OTS_OLCP_CLEAR_MARK
BLE_OTS_OLCP_RESPONSE
BLE_OTS_OLCP_SORT_BY_NAME_ASCENDING
BLE_OTS_OLCP_SORT_BY_TYPE_ASCENDING
BLE_OTS_OLCP_SORT_BY_SIZE_ASCENDING
BLE_OTS_OLCP_SORT_BY_FIRST_CREATE_TIME_ASCENDING
BLE_OTS_OLCP_SORT_BY_LAST_MODIFY_TIME_ASCENDING
BLE_OTS_OLCP_SORT_BY_NAME_DESCENDING
BLE_OTS_OLCP_SORT_BY_TYPE_DESCENDING
BLE_OTS_OLCP_SORT_BY_SIZE_DESCENDING
BLE_OTS_OLCP_SORT_BY_FIRST_CREATE_TIME_DESCENDING
BLE_OTS_OLCP_SORT_BY_LAST_MODIFY_TIME_DESCENDING
BLE_OTS_OLCP_RSP_SUCCESS
BLE_OTS_OLCP_RSP_NOT_SUPPORT
BLE_OTS_OLCP_RSP_INVALID_PARAMETER
BLE_OTS_OLCP_RSP_OPERATION_FAIL
BLE_OTS_OLCP_RSP_OUT_OF_BOUNDS
BLE_OTS_OLCP_RSP_TOO_MANY_OBJECTS
BLE_OTS_OLCP_RSP_NO_OBJECT
BLE_OTS_OLCP_RSP_OBJECT_ID_NOT_FOUND
BLE_OTS_FILTER_NAME_START
BLE_OTS_FILTER_NAME_END
BLE_OTS_FILTER_NAME_CONTAIN
BLE_OTS_FILTER_NAME_EXACTLY
BLE_OTS_FILTER_OBJ_TYPE
BLE_OTS_FILTER_CREATE_TIME
BLE_OTS_FILTER_MODIFY_TIME
BLE_OTS_FILTER_CURRENT_SIZE
BLE_OTS_FILTER_ALLOC_SIZE
BLE_OTS_FILTER_MARK_OBJECT
BLE_OTS_OBJ_CHG_SRC
BLE_OTS_OBJ_CHG_CONTENT
BLE_OTS_OBJ_CHG_METADATA
BLE_OTS_OBJ_CHG_CREATION
BLE_OTS_OBJ_CHG_DELETION

Provide feedback about this document