Bluetooth® OPP API

[中文]

Overview

OPP (Object Push Profile) enables pushing objects such as vCards and other files between Bluetooth devices over OBEX. It is commonly used for contact exchange, file sharing, and similar one-way object transfer scenarios. The OPP API provides functionality for both server and client roles.

Application Examples

API Reference

Header File

  • components/bt/host/bluedroid/api/include/api/esp_opp_api.h

  • This header file can be included with:

    #include "esp_opp_api.h"

  • This header file is a part of the API provided by the bt component. To declare that your component depends on bt, add the following to your CMakeLists.txt:

    REQUIRES bt

    or

    PRIV_REQUIRES bt

Functions

esp_err_t esp_opp_server_register_callback(esp_opp_server_callback_t callback)

This function is called to register a user callback for OPP server.

Parameters:

callback -- [in] pointer to the user callback function.

Returns:

  • ESP_OK: success

  • other: failed

esp_err_t esp_opp_client_register_callback(esp_opp_client_callback_t callback)

This function is called to register a user callback for OPP client.

Parameters:

callback -- [in] pointer to the user callback function.

Returns:

  • ESP_OK: success

  • other: failed

esp_err_t esp_opp_server_init(void)

This function is called to initialize OPP server.

Acquires the shared OPP VFS (read side). When the operation is completed, the callback function will be called with ESP_OPP_SERVER_INIT_EVT. This function should be called after esp_bluedroid_enable() and esp_opp_server_register_callback() complete successfully.

Returns:

  • ESP_OK: success

  • other: failed

esp_err_t esp_opp_server_deinit(void)

This function is called to deinitialize OPP server.

Active server connections are closed first. When the operation is completed, the callback function will be called with ESP_OPP_SERVER_DEINIT_EVT. This function should be called after esp_opp_server_init() completes successfully.

Finish all OPP VFS read/write and close() every OPP fd before calling this function.

Returns:

  • ESP_OK: success

  • other: failed

esp_err_t esp_opp_server_start(const esp_opp_server_cfg_t *cfg)

This function creates an OPP server and starts listening for inbound connections.

When the server is started successfully, the callback is called with ESP_OPP_SERVER_START_EVT. When an inbound connection is established or released, the callback is called with ESP_OPP_SERVER_CONNECTION_STATE_EVT. This function should be called after esp_opp_server_init() completes successfully.

Parameters:

cfg -- [in] OPP server configuration.

Returns:

  • ESP_OK: success

  • other: failed

esp_err_t esp_opp_server_stop(void)

This function stops the OPP server.

When the operation is completed, the callback function will be called with ESP_OPP_SERVER_STOP_EVT. This function should be called after esp_opp_server_start() completes successfully.

Returns:

  • ESP_OK: success

  • other: failed

esp_err_t esp_opp_server_accept(esp_opp_conn_hdl_t handle)

Accept a pending incoming object.

Call this when ESP_OPP_SERVER_INCOMING_OBJECT_EVT reports needs_accept == true (auto_accept is false and this is the first object on the connection). The first PUT is held without an OBEX response until accept, reject, or the stack accept timeout (~30s). Accept also authorizes further objects on the same connection and unblocks body delivery from the peer. When the operation is completed, the callback is called with ESP_OPP_SERVER_ACCEPT_EVT (status, handle, fd). After a successful accept, read(fd) until EOF (0), then close(fd).

Parameters:

handle -- [in] Connection handle from ESP_OPP_SERVER_INCOMING_OBJECT_EVT.

Returns:

  • ESP_OK: request posted; result is in ESP_OPP_SERVER_ACCEPT_EVT

  • other: failed

esp_err_t esp_opp_server_reject(esp_opp_conn_hdl_t handle)

Reject a pending incoming object and close the connection.

Sends OBEX Forbidden and cancels the whole batch on that connection (subsequent objects are not received).

Parameters:

handle -- [in] Connection handle from ESP_OPP_SERVER_INCOMING_OBJECT_EVT.

Returns:

  • ESP_OK: success

  • other: failed

esp_err_t esp_opp_server_cancel(esp_opp_conn_hdl_t handle)

Cancel the current incoming object transfer on the server connection.

Parameters:

handle -- [in] Connection handle.

Returns:

  • ESP_OK: success

  • other: failed

esp_err_t esp_opp_client_init(void)

This function is called to initialize OPP client.

Acquires the shared OPP VFS (write side). When the operation is completed, the callback function will be called with ESP_OPP_CLIENT_INIT_EVT. This function should be called after esp_bluedroid_enable() and esp_opp_client_register_callback() complete successfully.

Returns:

  • ESP_OK: success

  • other: failed

esp_err_t esp_opp_client_deinit(void)

This function is called to deinitialize OPP client.

Active client connections are closed first. When the operation is completed, the callback function will be called with ESP_OPP_CLIENT_DEINIT_EVT. This function should be called after esp_opp_client_init() completes successfully.

Finish all OPP VFS read/write and close() every OPP fd before calling this function.

Returns:

  • ESP_OK: success

  • other: failed

esp_err_t esp_opp_client_connect(const esp_opp_client_connect_param_t *param)

This function connects OPP client to a remote OPP server.

When the connection is established or failed, the callback is called with ESP_OPP_CLIENT_CONNECTION_STATE_EVT. This function should be called after esp_opp_client_init() completes successfully.

Parameters:

param -- [in] Connect parameters including peer address and security.

Returns:

  • ESP_OK: success

  • other: failed

esp_err_t esp_opp_client_disconnect(esp_opp_conn_hdl_t handle)

This function disconnects the OPP client from the remote OPP server.

When the operation is completed, the callback function will be called with ESP_OPP_CLIENT_CONNECTION_STATE_EVT. This function should be called after a successful connection.

Parameters:

handle -- [in] Connection handle from ESP_OPP_CLIENT_CONNECTION_STATE_EVT.

Returns:

  • ESP_OK: success

  • other: failed

esp_err_t esp_opp_client_open_object(const esp_opp_client_object_cfg_t *cfg)

Open a VFS write fd for pushing one object on an OPP client connection.

When the operation is completed, the callback is called with ESP_OPP_CLIENT_OPEN_EVT (status, handle, fd). On success, write the object body with write(fd), then close(fd) to send End-of-Body. The total bytes written must equal cfg->len. Transfer completion is reported by ESP_OPP_CLIENT_TRANSFER_COMPLETE_EVT.

After each OBEX CONNECT/PUT/DISCONNECT request, the stack waits up to ~30s for the peer response (Continue/OK). No response aborts the transfer (if any) and closes the connection. Waiting for the application to write(fd) does not consume that timeout.

Parameters:

cfg -- [in] Object metadata and connection handle.

Returns:

  • ESP_OK: request posted; result is in ESP_OPP_CLIENT_OPEN_EVT

  • other: failed

esp_err_t esp_opp_client_cancel(esp_opp_conn_hdl_t handle)

Cancel the current outgoing object transfer on the client connection.

Parameters:

handle -- [in] Connection handle.

Returns:

  • ESP_OK: success

  • other: failed

esp_err_t esp_opp_get_profile_status(esp_opp_profile_status_t *profile_status)

This function is used to get the status of OPP.

Parameters:

profile_status -- [out] OPP status

Returns:

  • ESP_OK: success

  • other: failed

Unions

union esp_opp_server_param_t
#include <esp_opp_api.h>

OPP server callback parameters.

Public Members

struct esp_opp_server_param_t::opp_server_init_evt_param init

OPP server callback param of ESP_OPP_SERVER_INIT_EVT

struct esp_opp_server_param_t::opp_server_deinit_evt_param deinit

OPP server callback param of ESP_OPP_SERVER_DEINIT_EVT

struct esp_opp_server_param_t::opp_server_start_evt_param start

OPP server callback param of ESP_OPP_SERVER_START_EVT

struct esp_opp_server_param_t::opp_server_stop_evt_param stop

OPP server callback param of ESP_OPP_SERVER_STOP_EVT

struct esp_opp_server_param_t::opp_server_conn_evt_param conn

OPP server callback param of ESP_OPP_SERVER_CONNECTION_STATE_EVT

struct esp_opp_server_param_t::opp_server_incoming_object_evt_param incoming

OPP server callback param of ESP_OPP_SERVER_INCOMING_OBJECT_EVT

struct esp_opp_server_param_t::opp_server_accept_evt_param accept

OPP server callback param of ESP_OPP_SERVER_ACCEPT_EVT

struct esp_opp_server_param_t::opp_server_progress_evt_param progress

OPP server callback param of ESP_OPP_SERVER_PROGRESS_EVT

struct esp_opp_server_param_t::opp_server_complete_evt_param complete

OPP server callback param of ESP_OPP_SERVER_TRANSFER_COMPLETE_EVT

struct opp_server_accept_evt_param
#include <esp_opp_api.h>

ESP_OPP_SERVER_ACCEPT_EVT.

Public Members

esp_bt_status_t status

status

esp_opp_conn_hdl_t handle

Connection handle

int fd

VFS read file descriptor; -1 on failure

struct opp_server_complete_evt_param
#include <esp_opp_api.h>

ESP_OPP_SERVER_TRANSFER_COMPLETE_EVT.

Public Members

esp_opp_conn_hdl_t handle

Connection handle

esp_bt_status_t status

Transfer result

uint32_t transferred

Bytes received when transfer ended

struct opp_server_conn_evt_param
#include <esp_opp_api.h>

ESP_OPP_SERVER_CONNECTION_STATE_EVT.

Public Members

esp_opp_conn_hdl_t handle

Connection handle

esp_opp_connection_state_t state

Connection state

esp_bt_status_t status

status

esp_bd_addr_t bd_addr

Peer Bluetooth device address

struct opp_server_deinit_evt_param
#include <esp_opp_api.h>

ESP_OPP_SERVER_DEINIT_EVT.

Public Members

esp_bt_status_t status

status

struct opp_server_incoming_object_evt_param
#include <esp_opp_api.h>

ESP_OPP_SERVER_INCOMING_OBJECT_EVT.

Public Members

esp_opp_conn_hdl_t handle

Connection handle

const char *name

Object name; valid only during the callback

const char *type

Object MIME type; may be NULL

uint32_t len

Declared object length; 0 if unknown

int fd

VFS fd for reading the object body; -1 if needs_accept (fd is delivered in ESP_OPP_SERVER_ACCEPT_EVT)

bool needs_accept

true: call esp_opp_server_accept/reject; false: already authorized, read(fd) directly

struct opp_server_init_evt_param
#include <esp_opp_api.h>

ESP_OPP_SERVER_INIT_EVT.

Public Members

esp_bt_status_t status

status

struct opp_server_progress_evt_param
#include <esp_opp_api.h>

ESP_OPP_SERVER_PROGRESS_EVT.

Public Members

esp_opp_conn_hdl_t handle

Connection handle

uint32_t transferred

Bytes received so far

uint32_t total

Declared total length; 0 if unknown

struct opp_server_start_evt_param
#include <esp_opp_api.h>

ESP_OPP_SERVER_START_EVT.

Public Members

esp_bt_status_t status

status

uint8_t scn

RFCOMM server channel; 0 if start failed

struct opp_server_stop_evt_param
#include <esp_opp_api.h>

ESP_OPP_SERVER_STOP_EVT.

Public Members

esp_bt_status_t status

status

union esp_opp_client_param_t
#include <esp_opp_api.h>

OPP client callback parameters.

Public Members

struct esp_opp_client_param_t::opp_client_init_evt_param init

OPP client callback param of ESP_OPP_CLIENT_INIT_EVT

struct esp_opp_client_param_t::opp_client_deinit_evt_param deinit

OPP client callback param of ESP_OPP_CLIENT_DEINIT_EVT

struct esp_opp_client_param_t::opp_client_conn_evt_param conn

OPP client callback param of ESP_OPP_CLIENT_CONNECTION_STATE_EVT

struct esp_opp_client_param_t::opp_client_open_evt_param open

OPP client callback param of ESP_OPP_CLIENT_OPEN_EVT

struct esp_opp_client_param_t::opp_client_progress_evt_param progress

OPP client callback param of ESP_OPP_CLIENT_PROGRESS_EVT

struct esp_opp_client_param_t::opp_client_complete_evt_param complete

OPP client callback param of ESP_OPP_CLIENT_TRANSFER_COMPLETE_EVT

struct opp_client_complete_evt_param
#include <esp_opp_api.h>

ESP_OPP_CLIENT_TRANSFER_COMPLETE_EVT.

Public Members

esp_opp_conn_hdl_t handle

Connection handle

esp_bt_status_t status

Transfer result

uint32_t transferred

Bytes sent when transfer ended

struct opp_client_conn_evt_param
#include <esp_opp_api.h>

ESP_OPP_CLIENT_CONNECTION_STATE_EVT.

Public Members

esp_opp_conn_hdl_t handle

Connection handle

esp_opp_connection_state_t state

Connection state

esp_bt_status_t status

status

esp_bd_addr_t bd_addr

Peer Bluetooth device address

struct opp_client_deinit_evt_param
#include <esp_opp_api.h>

ESP_OPP_CLIENT_DEINIT_EVT.

Public Members

esp_bt_status_t status

status

struct opp_client_init_evt_param
#include <esp_opp_api.h>

ESP_OPP_CLIENT_INIT_EVT.

Public Members

esp_bt_status_t status

status

struct opp_client_open_evt_param
#include <esp_opp_api.h>

ESP_OPP_CLIENT_OPEN_EVT.

Public Members

esp_bt_status_t status

status

esp_opp_conn_hdl_t handle

Connection handle

int fd

VFS write file descriptor; -1 on failure

struct opp_client_progress_evt_param
#include <esp_opp_api.h>

ESP_OPP_CLIENT_PROGRESS_EVT.

Public Members

esp_opp_conn_hdl_t handle

Connection handle

uint32_t transferred

Bytes sent so far

uint32_t total

Declared total length

Structures

struct esp_opp_profile_status_t

OPP profile status parameters.

Public Members

bool opp_server_inited

OPP server initialization

bool opp_client_inited

OPP client initialization

uint8_t conn_num

Number of connections

struct esp_opp_server_cfg_t

OPP server start configuration parameters.

Public Members

esp_bt_sec_t sec_mask

Security setting mask.

Note

Suggest using one of:

  • ESP_BT_SEC_NONE

  • ESP_BT_SEC_AUTHENTICATE

  • (ESP_BT_SEC_AUTHENTICATE | ESP_BT_SEC_ENCRYPT)

uint16_t mtu

Preferred OBEX packet length, range: ESP_OPP_MTU_MIN ～ ESP_OPP_MTU_MAX; 0 means transport default

const char *service_name

SDP service name; NULL uses stack default

const uint8_t *supported_formats

Supported formats list for SDP; NULL means any type

uint8_t supported_formats_len

Number of bytes in supported_formats

bool auto_accept

true: accept every object automatically. false: accept once per OBEX connection (first object needs esp_opp_server_accept; later objects on the same connection are auto-accepted)

struct esp_opp_client_connect_param_t

OPP client connect parameters.

Public Members

esp_bd_addr_t bd_addr

Remote device Bluetooth address

esp_bt_sec_t sec_mask

Security setting mask.

Note

Suggest using one of:

  • ESP_BT_SEC_NONE

  • ESP_BT_SEC_AUTHENTICATE

  • (ESP_BT_SEC_AUTHENTICATE | ESP_BT_SEC_ENCRYPT)

uint16_t mtu

Preferred OBEX packet length, range: ESP_OPP_MTU_MIN ～ ESP_OPP_MTU_MAX; 0 means transport default

struct esp_opp_client_object_cfg_t

OPP client object open parameters.

After ESP_OPP_CLIENT_OPEN_EVT reports success, write object body bytes with write(fd), then close(fd) to finish the object (End-of-Body). The number of bytes written must equal len.

Public Members

esp_opp_conn_hdl_t handle

Connection handle from CONNECTION_STATE_EVT

const char *name

Object name; ASCII is encoded as OBEX UTF-16BE

const char *type

MIME type, for example text/x-vcard; may be NULL

uint32_t len

Declared object length (OBEX Length header)

Macros

ESP_OPP_INVALID_HANDLE

Invalid OPP connection handle

ESP_OPP_MAX_NAME_LEN

Maximum object name length (ASCII bytes)

ESP_OPP_MAX_TYPE_LEN

Maximum MIME type length

ESP_OPP_MTU_MIN

Minimal MTU can be used in OPP connection

ESP_OPP_MTU_MAX

Maximum MTU can be used in OPP connection

ESP_OPP_FORMAT_VCARD_2_1

OPP supported formats for SDP (GOEP Supported Formats List).

vCard 2.1

ESP_OPP_FORMAT_VCARD_3_0

vCard 3.0

ESP_OPP_FORMAT_VCAL_1_0

vCal 1.0

ESP_OPP_FORMAT_ICAL_2_0

iCal 2.0

ESP_OPP_FORMAT_VNOTE

vNote

ESP_OPP_FORMAT_VMESSAGE

vMessage

ESP_OPP_FORMAT_ANY

Any type of object

ESP_BT_STATUS_OPP_NOT_FOUND

OPP profile error code.

OPP: requested object/connection not found

ESP_BT_STATUS_OPP_ABORTED

OPP: transfer aborted (local cancel or response timeout)

ESP_BT_STATUS_OPP_SDP_FAIL

OPP: operation failed during SDP

ESP_BT_STATUS_OPP_OBEX_FAIL

OPP: operation failed during OBEX/GOEP

ESP_BT_STATUS_OPP_FORBIDDEN

OPP: operation refused (OBEX Forbidden)

Type Definitions

typedef uint16_t esp_opp_conn_hdl_t

OPP connection handle

typedef void (*esp_opp_server_callback_t)(esp_opp_server_cb_event_t event, esp_opp_server_param_t *param)

OPP server callback function type.

Param event:

[in] Event type

Param param:

[in] Pointer to callback parameter

typedef void (*esp_opp_client_callback_t)(esp_opp_client_cb_event_t event, esp_opp_client_param_t *param)

OPP client callback function type.

Param event:

[in] Event type

Param param:

[in] Pointer to callback parameter

Enumerations

enum esp_opp_server_cb_event_t

OPP server callback events.

Values:

enumerator ESP_OPP_SERVER_INIT_EVT

When OPP server is initialized, the event comes

enumerator ESP_OPP_SERVER_DEINIT_EVT

When OPP server is deinitialized, the event comes

enumerator ESP_OPP_SERVER_START_EVT

When OPP server starts listening, the event comes

enumerator ESP_OPP_SERVER_STOP_EVT

When OPP server stops listening, the event comes

enumerator ESP_OPP_SERVER_CONNECTION_STATE_EVT

When inbound OPP connection state changes, the event comes

enumerator ESP_OPP_SERVER_INCOMING_OBJECT_EVT

When a peer starts pushing an object, the event comes

enumerator ESP_OPP_SERVER_ACCEPT_EVT

When esp_opp_server_accept completes, the event comes

enumerator ESP_OPP_SERVER_PROGRESS_EVT

When incoming object transfer progress updates, the event comes

enumerator ESP_OPP_SERVER_TRANSFER_COMPLETE_EVT

When an incoming object transfer finishes, the event comes

enum esp_opp_client_cb_event_t

OPP client callback events.

Values:

enumerator ESP_OPP_CLIENT_INIT_EVT

When OPP client is initialized, the event comes

enumerator ESP_OPP_CLIENT_DEINIT_EVT

When OPP client is deinitialized, the event comes

enumerator ESP_OPP_CLIENT_CONNECTION_STATE_EVT

When outbound OPP connection state changes, the event comes

enumerator ESP_OPP_CLIENT_OPEN_EVT

When esp_opp_client_open_object completes, the event comes

enumerator ESP_OPP_CLIENT_PROGRESS_EVT

When outgoing object transfer progress updates, the event comes

enumerator ESP_OPP_CLIENT_TRANSFER_COMPLETE_EVT

When an outgoing object transfer finishes, the event comes

enum esp_opp_connection_state_t

OPP connection state.

Values:

enumerator ESP_OPP_DISCONNECTED

Connection closed

enumerator ESP_OPP_CONNECTED

Connection established

Was this page helpful?