蓝牙® OPP API

[English]

概述

OPP（Object Push Profile，对象推送配置文件）通过 OBEX 在蓝牙设备之间推送 vCard 等对象及其他文件。常用于联系人交换、文件共享及类似的单向对象传输场景。OPP API 同时提供服务器和客户端两种角色的功能。

应用示例

API 参考

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.

参数:

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

返回:

  • 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.

参数:

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

返回:

  • 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.

返回:

  • 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.

返回:

  • 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.

参数:

cfg -- [in] OPP server configuration.

返回:

  • 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.

返回:

  • 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).

参数:

handle -- [in] Connection handle from ESP_OPP_SERVER_INCOMING_OBJECT_EVT.

返回:

  • 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).

参数:

handle -- [in] Connection handle from ESP_OPP_SERVER_INCOMING_OBJECT_EVT.

返回:

  • 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.

参数:

handle -- [in] Connection handle.

返回:

  • 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.

返回:

  • 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.

返回:

  • 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.

参数:

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

返回:

  • 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.

参数:

handle -- [in] Connection handle from ESP_OPP_CLIENT_CONNECTION_STATE_EVT.

返回:

  • 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.

参数:

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

返回:

  • 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.

参数:

handle -- [in] Connection handle.

返回:

  • 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.

参数:

profile_status -- [out] OPP status

返回:

  • 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.

备注

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.

备注

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

此文档对您有帮助吗？