|
Zephyr API Documentation 4.5.99
A Scalable Open Source RTOS
|
Object Push Profile (OPP). More...
Data Structures | |
| struct | bt_opp_client_cb |
| OPP Push Client callback operations structure. More... | |
| struct | bt_opp_client |
| OPP Push Client structure. More... | |
| struct | bt_opp_server_cb |
| OPP Push Server callback operations structure. More... | |
| struct | bt_opp_server_transport |
| OPP Push Server transport registration structure. More... | |
| struct | bt_opp_server |
| OPP Push Server structure. More... | |
Macros | |
| #define | BT_OPP_SDP_UUID BT_UUID_DECLARE_16(BT_SDP_OBEX_OBJPUSH_SVCLASS) |
| SDP service class UUID for the Object Push service. | |
| #define | BT_OPP_SDP_ATTR_SUPPORTED_FORMATS BT_SDP_ATTR_SUPPORTED_FORMATS_LIST |
| SDP attribute ID for the Supported Formats List attribute. | |
| #define | BT_OPP_TYPE_VCARD "text/x-vcard" |
| OBEX Type header value for vCard 2.1 / vCard 3.0 objects. | |
| #define | BT_OPP_TYPE_VCAL "text/x-vcalendar" |
| OBEX Type header value for vCalendar 1.0 objects. | |
| #define | BT_OPP_TYPE_ICAL "text/calendar" |
| OBEX Type header value for iCalendar 2.0 objects. | |
| #define | BT_OPP_TYPE_VNOTE "text/x-vnote" |
| OBEX Type header value for vNote objects. | |
| #define | BT_OPP_TYPE_VMESSAGE "text/x-vmsg" |
| OBEX Type header value for vMessage objects. | |
Enumerations | |
| enum | bt_opp_format { BT_OPP_FORMAT_VCARD_2_1 = 0x01 , BT_OPP_FORMAT_VCARD_3_0 = 0x02 , BT_OPP_FORMAT_VCAL_1_0 = 0x03 , BT_OPP_FORMAT_ICAL_2_0 = 0x04 , BT_OPP_FORMAT_VNOTE = 0x05 , BT_OPP_FORMAT_VMESSAGE = 0x06 , BT_OPP_FORMAT_ANY = 0xff } |
| OPP supported object format codes. More... | |
| enum | bt_opp_rsp_code { BT_OPP_RSP_CODE_CONTINUE = BT_OBEX_RSP_CODE_CONTINUE , BT_OPP_RSP_CODE_OK = BT_OBEX_RSP_CODE_OK , BT_OPP_RSP_CODE_SUCCESS = BT_OBEX_RSP_CODE_SUCCESS , BT_OPP_RSP_CODE_BAD_REQ = BT_OBEX_RSP_CODE_BAD_REQ , BT_OPP_RSP_CODE_FORBIDDEN = BT_OBEX_RSP_CODE_FORBIDDEN , BT_OPP_RSP_CODE_NOT_FOUND = BT_OBEX_RSP_CODE_NOT_FOUND , BT_OPP_RSP_CODE_NOT_ACCEPT = BT_OBEX_RSP_CODE_NOT_ACCEPT , BT_OPP_RSP_CODE_PRECON_FAIL = BT_OBEX_RSP_CODE_PRECON_FAIL , BT_OPP_RSP_CODE_ENTITY_TOO_LARGE = BT_OBEX_RSP_CODE_ENTITY_TOO_LARGE , BT_OPP_RSP_CODE_UNSUPP_MEDIA_TYPE = BT_OBEX_RSP_CODE_UNSUPP_MEDIA_TYPE , BT_OPP_RSP_CODE_NOT_IMPL = BT_OBEX_RSP_CODE_NOT_IMPL , BT_OPP_RSP_CODE_INTER_ERROR = BT_OBEX_RSP_CODE_INTER_ERROR , BT_OPP_RSP_CODE_UNAVAIL = BT_OBEX_RSP_CODE_UNAVAIL } |
| OPP response codes. More... | |
Functions | |
| int | bt_opp_client_transport_connect (struct bt_conn *conn, struct bt_opp_client *client, const struct bt_opp_client_cb *cb, uint8_t channel) |
| Connect the Push Client to a Push Server transport. | |
| int | bt_opp_client_transport_disconnect (struct bt_opp_client *client) |
| Disconnect the Push Client transport connection. | |
| struct net_buf * | bt_opp_client_create_pdu (struct bt_opp_client *client, struct net_buf_pool *pool) |
| Allocate a PDU buffer with headroom reserved for OPP Push Client. | |
| int | bt_opp_client_connect (struct bt_opp_client *client, uint16_t mopl, struct net_buf *buf) |
| Establish an OBEX connection with the Push Server. | |
| int | bt_opp_client_disconnect (struct bt_opp_client *client, struct net_buf *buf) |
| Terminate the OBEX connection. | |
| int | bt_opp_client_push (struct bt_opp_client *client, bool final, struct net_buf *buf) |
| Push an object to the Push Server (OBEX PUT). | |
| int | bt_opp_client_pull (struct bt_opp_client *client, struct net_buf *buf) |
| Pull the server's default business card (OBEX GET). | |
| int | bt_opp_client_abort (struct bt_opp_client *client, struct net_buf *buf) |
| Abort the current ongoing operation. | |
| struct net_buf * | bt_opp_server_create_pdu (struct bt_opp_server *server, struct net_buf_pool *pool) |
| Allocate a PDU buffer with headroom reserved for OPP Push Server. | |
| int | bt_opp_server_transport_register (struct bt_opp_server_transport *server) |
| Register an OPP Push Server transport listener. | |
| int | bt_opp_server_register (struct bt_opp_server *server, const struct bt_opp_server_cb *cb) |
| Register a Push Server instance with the OPP subsystem. | |
| int | bt_opp_server_unregister (struct bt_opp_server *server) |
| Release a Push Server instance. | |
| int | bt_opp_server_connect (struct bt_opp_server *server, uint16_t mopl, uint8_t rsp_code, struct net_buf *buf) |
| Send an OBEX CONNECT response from the Push Server. | |
| int | bt_opp_server_disconnect (struct bt_opp_server *server, struct net_buf *buf) |
| Send an OBEX DISCONNECT response from the Push Server. | |
| int | bt_opp_server_push (struct bt_opp_server *server, uint8_t rsp_code, struct net_buf *buf) |
| Send an OBEX PUT response from the Push Server. | |
| int | bt_opp_server_pull (struct bt_opp_server *server, uint8_t rsp_code, struct net_buf *buf) |
| Send an OBEX GET response from the Push Server (business card pull). | |
| int | bt_opp_server_abort (struct bt_opp_server *server, struct net_buf *buf) |
| Send an OBEX ABORT response from the Push Server. | |
Object Push Profile (OPP).
This implementation targets OPP v1.1 (GOEP v1.1 over RFCOMM, IrOBEX 1.2). The APIs below reject a buffer that carries a header the profile excludes, such as Target, Who, Connection ID, or an SRM or reliable-session header.
| #define BT_OPP_SDP_ATTR_SUPPORTED_FORMATS BT_SDP_ATTR_SUPPORTED_FORMATS_LIST |
#include <zephyr/bluetooth/classic/opp.h>
SDP attribute ID for the Supported Formats List attribute.
Mandatory for OPP servers. Contains a sequence of bt_opp_format values describing the object types the server can receive.
| #define BT_OPP_SDP_UUID BT_UUID_DECLARE_16(BT_SDP_OBEX_OBJPUSH_SVCLASS) |
#include <zephyr/bluetooth/classic/opp.h>
SDP service class UUID for the Object Push service.
Use this UUID as the search target when performing SDP discovery for OPP. Defined as OBEXObjectPush (0x1105) in the Bluetooth Assigned Numbers.
| #define BT_OPP_TYPE_ICAL "text/calendar" |
#include <zephyr/bluetooth/classic/opp.h>
OBEX Type header value for iCalendar 2.0 objects.
| #define BT_OPP_TYPE_VCAL "text/x-vcalendar" |
#include <zephyr/bluetooth/classic/opp.h>
OBEX Type header value for vCalendar 1.0 objects.
| #define BT_OPP_TYPE_VCARD "text/x-vcard" |
#include <zephyr/bluetooth/classic/opp.h>
OBEX Type header value for vCard 2.1 / vCard 3.0 objects.
| #define BT_OPP_TYPE_VMESSAGE "text/x-vmsg" |
#include <zephyr/bluetooth/classic/opp.h>
OBEX Type header value for vMessage objects.
| #define BT_OPP_TYPE_VNOTE "text/x-vnote" |
#include <zephyr/bluetooth/classic/opp.h>
OBEX Type header value for vNote objects.
| enum bt_opp_format |
#include <zephyr/bluetooth/classic/opp.h>
OPP supported object format codes.
Defined in OPP Spec v1.1, Table 6.1 (Supported Formats List in SDP). Used when registering a Push Server to advertise supported object types.
| enum bt_opp_rsp_code |
#include <zephyr/bluetooth/classic/opp.h>
OPP response codes.
Mapped from OBEX response codes. These are the values carried by the rsp_code parameter of the OPP operation callbacks and response APIs. A response code received from a remote device is passed on unchecked, so it may also hold a value that bt_obex_rsp_code does not define.
| int bt_opp_client_abort | ( | struct bt_opp_client * | client, |
| struct net_buf * | buf ) |
#include <zephyr/bluetooth/classic/opp.h>
Abort the current ongoing operation.
Sends an OBEX ABORT request to cancel a push or pull operation that is in progress. The bt_opp_client_cb::abort() callback is invoked when the server answers with BT_OPP_RSP_CODE_SUCCESS. On any other answer the stack closes the transport, which only bt_opp_client_cb::transport_disconnected() reports.
| client | Push Client instance. |
| buf | Optional OBEX headers buffer, or NULL. |
| 0 | on success. |
| -EINVAL | Invalid parameter, buf carries a header the profile excludes, or no operation is in progress. |
| -ENOTCONN | OBEX connection is not established. |
| -errno | Error code of the underlying OBEX layer on failure. |
| int bt_opp_client_connect | ( | struct bt_opp_client * | client, |
| uint16_t | mopl, | ||
| struct net_buf * | buf ) |
#include <zephyr/bluetooth/classic/opp.h>
Establish an OBEX connection with the Push Server.
Sends an OBEX CONNECT request. The Target header (BT_OBEX_HEADER_ID_TARGET) shall not be included. The transport must already be connected via bt_opp_client_transport_connect. The bt_opp_client_cb::connect() callback is invoked with the server response.
| client | Push Client instance (transport must be connected). |
| mopl | Maximum OBEX packet length proposed by this client. |
| buf | Optional additional OBEX headers buffer, or NULL. |
| 0 | on success. |
| -EINVAL | Invalid parameter, or buf carries a header the profile excludes, such as Target. |
| -ENOTCONN | Transport is not connected. |
| -EINPROGRESS | The OBEX connection is not disconnected: a CONNECT request is outstanding, or the connection is already established. |
| -errno | Error code of the underlying OBEX layer on failure. |
| struct net_buf * bt_opp_client_create_pdu | ( | struct bt_opp_client * | client, |
| struct net_buf_pool * | pool ) |
#include <zephyr/bluetooth/classic/opp.h>
Allocate a PDU buffer with headroom reserved for OPP Push Client.
The headroom accounts for all lower-layer headers (OBEX, RFCOMM, L2CAP and ACL), so the application can append OBEX headers with the bt_obex_add_header_* helpers right away.
If pool is NULL the buffer is taken from the pool owned by the OPP module. That pool holds two buffers per ACL connection ( CONFIG_BT_MAX_CONN), one for a request and one for a response, each sized to carry a full OBEX packet over RFCOMM ( CONFIG_BT_GOEP_RFCOMM_MTU). An application that needs to keep more buffers in flight has to pass its own pool.
| client | Push Client object. |
| pool | Buffer pool to allocate from, or NULL for the pool owned by the OPP module. |
client is NULL or has not been passed to bt_opp_client_transport_connect yet. When the pool is empty the call blocks until a buffer is freed, except when called from the system work queue or the Bluetooth RX work queue, where it returns NULL instead. | int bt_opp_client_disconnect | ( | struct bt_opp_client * | client, |
| struct net_buf * | buf ) |
#include <zephyr/bluetooth/classic/opp.h>
Terminate the OBEX connection.
Sends an OBEX DISCONNECT request. The bt_opp_client_cb::disconnect() callback is invoked when the response is received.
| client | Push Client instance. |
| buf | Optional OBEX headers buffer, or NULL. |
| 0 | on success. |
| -EINVAL | Invalid parameter, or buf carries a header the profile excludes. |
| -ENOTCONN | OBEX connection is not established. |
| -errno | Error code of the underlying OBEX layer on failure. |
| int bt_opp_client_pull | ( | struct bt_opp_client * | client, |
| struct net_buf * | buf ) |
#include <zephyr/bluetooth/classic/opp.h>
Pull the server's default business card (OBEX GET).
Sends an OBEX GET request for the server's Default Get Object (owner business card). The first request of a pull operation identifies that object:
The bt_opp_client_cb::pull() callback is called with each response. BT_OPP_RSP_CODE_NOT_FOUND is returned by the server when no default object exists. If the response is BT_OPP_RSP_CODE_CONTINUE, call this function again to fetch the next chunk; the continuation request carries no headers, so buf may be empty.
| client | Push Client instance. |
| buf | Buffer carrying the OBEX headers of the first request, or an empty buffer for a continuation request. |
| 0 | on success. |
| -EINVAL | Invalid parameter, buf carries a header the profile excludes, or buf does not address the Default Get Object: it names an object or asks for another format. |
| -ENODATA | The Type header is missing from the first request of a pull operation. |
| -ENOTSUP | bt_opp_client_cb::pull() is not provided. |
| -ENOTCONN | OBEX connection is not established. |
| -errno | Error code of the underlying OBEX layer on failure. |
| int bt_opp_client_push | ( | struct bt_opp_client * | client, |
| bool | final, | ||
| struct net_buf * | buf ) |
#include <zephyr/bluetooth/classic/opp.h>
Push an object to the Push Server (OBEX PUT).
Sends an OBEX PUT request to deliver an object to the server's inbox. The first request of a push operation describes the object and carries:
Intermediate requests repeat none of these headers.
The object data travels in the Body header (BT_OBEX_HEADER_ID_BODY), except for the last chunk, which uses End-of-Body (BT_OBEX_HEADER_ID_END_BODY). For End-of-Body, the API only checks that the request with final set carries it; the order of the headers inside buf is up to the caller.
The bt_opp_client_cb::push() callback is called after each PUT response; BT_OPP_RSP_CODE_CONTINUE means the server is ready for the next chunk.
| client | Push Client instance. |
| final | True if this is the last (or only) PUT packet (use BT_OBEX_HEADER_ID_END_BODY in buf). False for intermediate packets (use BT_OBEX_HEADER_ID_BODY). |
| buf | Buffer carrying the OBEX headers of the request. |
| 0 | on success. |
| -EINVAL | Invalid parameter, buf carries a header the profile excludes, or the first request of a push operation is missing the Name or Length header. |
| -ENOTCONN | OBEX connection is not established. |
| -ENODATA | The End-of-Body header is missing from buf when final is true. |
| -errno | Error code of the underlying OBEX layer on failure. |
| int bt_opp_client_transport_connect | ( | struct bt_conn * | conn, |
| struct bt_opp_client * | client, | ||
| const struct bt_opp_client_cb * | cb, | ||
| uint8_t | channel ) |
#include <zephyr/bluetooth/classic/opp.h>
Connect the Push Client to a Push Server transport.
Establishes the GOEP v1.1 (RFCOMM) transport connection using the channel obtained from SDP discovery (Protocol Descriptor List). Once the transport is up the bt_opp_client_cb::transport_connected() callback is called; after that, call bt_opp_client_connect to establish the OBEX connection. If this function returns 0 but the transport cannot be established, bt_opp_client_cb::transport_disconnected() is called instead.
| conn | ACL connection object. |
| client | Push Client instance to connect. |
| cb | Callback operations structure, bt_opp_client_cb. Must not be NULL and must provide every mandatory callback. |
| channel | RFCOMM channel from SDP discovery. |
| 0 | on success. |
| -EINVAL | Invalid parameter, or a mandatory callback is missing. |
| -EALREADY | Transport is connected, or a transport connection or disconnection is in progress. |
| -errno | Error code of the underlying transport on failure. |
| int bt_opp_client_transport_disconnect | ( | struct bt_opp_client * | client | ) |
#include <zephyr/bluetooth/classic/opp.h>
Disconnect the Push Client transport connection.
Closes the transport connection. The bt_opp_client_cb::transport_disconnected() callback is called when done.
| client | Push Client instance to disconnect. |
| 0 | on success. |
| -EINVAL | Invalid parameter. |
| -ENOTCONN | Transport is not connected. |
| -errno | Error code of the underlying transport on failure. |
| int bt_opp_server_abort | ( | struct bt_opp_server * | server, |
| struct net_buf * | buf ) |
#include <zephyr/bluetooth/classic/opp.h>
Send an OBEX ABORT response from the Push Server.
Responds to an abort request received via bt_opp_server_cb::abort() with BT_OPP_RSP_CODE_SUCCESS, which tells the client that the server is resynchronized with it; a client that receives anything else should disconnect.
| server | Push Server instance. |
| buf | Optional response headers buffer, or NULL. |
| 0 | on success. |
| -EINVAL | Invalid parameter, or buf carries a header the profile excludes. |
| -errno | Error code of the underlying OBEX layer on failure. |
| int bt_opp_server_connect | ( | struct bt_opp_server * | server, |
| uint16_t | mopl, | ||
| uint8_t | rsp_code, | ||
| struct net_buf * | buf ) |
#include <zephyr/bluetooth/classic/opp.h>
Send an OBEX CONNECT response from the Push Server.
Responds to a connect request received via bt_opp_server_cb::connect(). The OBEX connection is established only if rsp_code is BT_OPP_RSP_CODE_SUCCESS.
| server | Push Server instance. |
| mopl | Maximum OBEX packet length accepted by this server. |
| rsp_code | Response code, bt_opp_rsp_code. |
| buf | Optional response headers buffer, or NULL. |
| 0 | on success. |
| -EINVAL | Invalid parameter, or buf carries a header the profile excludes. |
| -ENOTCONN | No CONNECT request is outstanding, so there is nothing to answer. |
| -errno | Error code of the underlying OBEX layer on failure. |
| struct net_buf * bt_opp_server_create_pdu | ( | struct bt_opp_server * | server, |
| struct net_buf_pool * | pool ) |
#include <zephyr/bluetooth/classic/opp.h>
Allocate a PDU buffer with headroom reserved for OPP Push Server.
The headroom accounts for all lower-layer headers (OBEX, RFCOMM, L2CAP and ACL), so the application can append OBEX headers with the bt_obex_add_header_* helpers right away.
If pool is NULL the buffer is taken from the pool owned by the OPP module. That pool holds two buffers per ACL connection ( CONFIG_BT_MAX_CONN), one for a request and one for a response, each sized to carry a full OBEX packet over RFCOMM ( CONFIG_BT_GOEP_RFCOMM_MTU). An application that needs to keep more buffers in flight has to pass its own pool.
| server | Push Server object. |
| pool | Buffer pool to allocate from, or NULL for the pool owned by the OPP module. |
server is NULL or has not been handed out by bt_opp_server_transport::accept() yet. When the pool is empty the call waits for a buffer to be freed, except when called from the system work queue or the Bluetooth RX work queue, where it returns NULL instead. | int bt_opp_server_disconnect | ( | struct bt_opp_server * | server, |
| struct net_buf * | buf ) |
#include <zephyr/bluetooth/classic/opp.h>
Send an OBEX DISCONNECT response from the Push Server.
Responds to a disconnect request received via bt_opp_server_cb::disconnect() with BT_OPP_RSP_CODE_SUCCESS, which tears the OBEX connection down. A disconnect request cannot be refused.
| server | Push Server instance. |
| buf | Optional response headers buffer, or NULL. |
| 0 | on success. |
| -EINVAL | Invalid parameter, buf carries a header the profile excludes, or no DISCONNECT request is outstanding. |
| -errno | Error code of the underlying OBEX layer on failure. |
| int bt_opp_server_pull | ( | struct bt_opp_server * | server, |
| uint8_t | rsp_code, | ||
| struct net_buf * | buf ) |
#include <zephyr/bluetooth/classic/opp.h>
Send an OBEX GET response from the Push Server (business card pull).
Responds to a business card pull request received via bt_opp_server_cb::pull(). Send BT_OPP_RSP_CODE_CONTINUE for each intermediate body chunk and BT_OPP_RSP_CODE_SUCCESS with the final End-of-Body chunk. Respond with BT_OPP_RSP_CODE_NOT_FOUND if no default object is available.
| server | Push Server instance. |
| rsp_code | Response code, bt_opp_rsp_code. |
| buf | Response headers buffer containing Body or End-of-Body, or NULL. |
| 0 | on success. |
| -EINVAL | Invalid parameter, or buf carries a header the profile excludes. |
| -ENODATA | rsp_code is BT_OPP_RSP_CODE_SUCCESS but buf carries no End-of-Body header. |
| -errno | Error code of the underlying OBEX layer on failure. |
| int bt_opp_server_push | ( | struct bt_opp_server * | server, |
| uint8_t | rsp_code, | ||
| struct net_buf * | buf ) |
#include <zephyr/bluetooth/classic/opp.h>
Send an OBEX PUT response from the Push Server.
Responds to a push request received via bt_opp_server_cb::push(). Answer a request without the final bit with BT_OPP_RSP_CODE_CONTINUE and the request with the final bit with BT_OPP_RSP_CODE_SUCCESS once the object has been received. BT_OPP_RSP_CODE_SUCCESS is refused for a request without the final bit.
| server | Push Server instance. |
| rsp_code | Response code, bt_opp_rsp_code. |
| buf | Optional response headers buffer, or NULL. |
| 0 | on success. |
| -EINVAL | Invalid parameter, or buf carries a header the profile excludes. |
| -errno | Error code of the underlying OBEX layer on failure. |
| int bt_opp_server_register | ( | struct bt_opp_server * | server, |
| const struct bt_opp_server_cb * | cb ) |
#include <zephyr/bluetooth/classic/opp.h>
Register a Push Server instance with the OPP subsystem.
Initializes the server object and associates the callback structure. This must be called inside the bt_opp_server_transport::accept() callback before returning the instance.
The registration outlives the transport connection, so an instance that is to be reused for a later connection has to be released first, either by bt_opp_server_unregister or by zeroing the whole structure. The natural place for that is the bt_opp_server_cb::transport_disconnected() callback, which is where the instance becomes free again.
| server | Push Server instance to register, bt_opp_server. |
| cb | Callback operations structure, bt_opp_server_cb. Must not be NULL and must provide every mandatory callback. |
| 0 | on success. |
| -EINVAL | Invalid parameter, or a mandatory callback is missing. |
| -EINPROGRESS | The instance is in use by an OBEX connection. |
| -EALREADY | The instance is still registered from an earlier connection and is left unchanged, see bt_opp_server_unregister. |
| -errno | Error code of the underlying OBEX layer on failure. |
| int bt_opp_server_transport_register | ( | struct bt_opp_server_transport * | server | ) |
#include <zephyr/bluetooth/classic/opp.h>
Register an OPP Push Server transport listener.
Registers the RFCOMM server to listen for incoming OPP connections. The allocated RFCOMM channel must be advertised via SDP (Protocol Descriptor List). If bt_rfcomm_server::channel of bt_goep_transport_rfcomm_server::rfcomm is 0, a channel is auto-assigned by RFCOMM.
CONFIG_BT_COD Kconfig option, then call bt_br_set_discoverable.| server | Transport registration structure, bt_opp_server_transport. |
| 0 | on success. |
| -EINVAL | Invalid parameter, or bt_opp_server_transport::accept() is missing. |
| -EEXIST | The transport is already registered. |
| -errno | Error code of the underlying transport on failure. |
| int bt_opp_server_unregister | ( | struct bt_opp_server * | server | ) |
#include <zephyr/bluetooth/classic/opp.h>
Release a Push Server instance.
Undoes bt_opp_server_register, so that the instance can be handed back by bt_opp_server_transport::accept() for a later connection. Call it once the instance is free, which the bt_opp_server_cb::transport_disconnected() callback reports.
| server | Push Server instance to release, bt_opp_server. |
| 0 | on success. |
| -EINVAL | Invalid parameter. |
| -EALREADY | The instance is not registered. |
| -EINPROGRESS | The instance is still in use by a transport connection. |
| -errno | Error code of the underlying OBEX layer on failure. |