Line data Source code
1 0 : /* obex.h - IrDA Oject Exchange Protocol handling */
2 :
3 : /*
4 : * Copyright 2024-2025 NXP
5 : *
6 : * SPDX-License-Identifier: Apache-2.0
7 : */
8 :
9 : #ifndef ZEPHYR_INCLUDE_BLUETOOTH_OBEX_H_
10 : #define ZEPHYR_INCLUDE_BLUETOOTH_OBEX_H_
11 :
12 : /**
13 : * @brief IrDA Oject Exchange Protocol (OBEX)
14 : * @defgroup bt_obex IrDA Oject Exchange Protocol (OBEX)
15 : * @ingroup bluetooth
16 : * @{
17 : */
18 :
19 : #include <zephyr/kernel.h>
20 : #include <string.h>
21 : #include <errno.h>
22 : #include <stdbool.h>
23 :
24 : #ifdef __cplusplus
25 : extern "C" {
26 : #endif
27 :
28 : /** @brief OBEX Response Code. */
29 1 : enum __packed bt_obex_rsp_code {
30 : /** Continue */
31 : BT_OBEX_RSP_CODE_CONTINUE = 0x90,
32 : /** OK */
33 : BT_OBEX_RSP_CODE_OK = 0xa0,
34 : /** Success */
35 : BT_OBEX_RSP_CODE_SUCCESS = 0xa0,
36 : /** Created */
37 : BT_OBEX_RSP_CODE_CREATED = 0xa1,
38 : /** Accepted */
39 : BT_OBEX_RSP_CODE_ACCEPTED = 0xa2,
40 : /** Non-Authoritative Information */
41 : BT_OBEX_RSP_CODE_NON_AUTH_INFO = 0xa3,
42 : /** No Content */
43 : BT_OBEX_RSP_CODE_NO_CONTENT = 0xa4,
44 : /** Reset Content */
45 : BT_OBEX_RSP_CODE_RESET_CONTENT = 0xa5,
46 : /** Partial Content */
47 : BT_OBEX_RSP_CODE_PARTIAL_CONTENT = 0xa6,
48 : /** Multiple Choices */
49 : BT_OBEX_RSP_CODE_MULTI_CHOICES = 0xb0,
50 : /** Moved Permanently */
51 : BT_OBEX_RSP_CODE_MOVED_PERM = 0xb1,
52 : /** Moved temporarily */
53 : BT_OBEX_RSP_CODE_MOVED_TEMP = 0xb2,
54 : /** See Other */
55 : BT_OBEX_RSP_CODE_SEE_OTHER = 0xb3,
56 : /** Not modified */
57 : BT_OBEX_RSP_CODE_NOT_MODIFIED = 0xb4,
58 : /** Use Proxy */
59 : BT_OBEX_RSP_CODE_USE_PROXY = 0xb5,
60 : /** Bad Request - server couldn’t understand request */
61 : BT_OBEX_RSP_CODE_BAD_REQ = 0xc0,
62 : /** Unauthorized */
63 : BT_OBEX_RSP_CODE_UNAUTH = 0xc1,
64 : /** Payment Required */
65 : BT_OBEX_RSP_CODE_PAY_REQ = 0xc2,
66 : /** Forbidden - operation is understood but refused */
67 : BT_OBEX_RSP_CODE_FORBIDDEN = 0xc3,
68 : /** Not Found */
69 : BT_OBEX_RSP_CODE_NOT_FOUND = 0xc4,
70 : /** Method Not Allowed */
71 : BT_OBEX_RSP_CODE_NOT_ALLOW = 0xc5,
72 : /** Not Acceptable */
73 : BT_OBEX_RSP_CODE_NOT_ACCEPT = 0xc6,
74 : /** Proxy Authentication Required */
75 : BT_OBEX_RSP_CODE_PROXY_AUTH_REQ = 0xc7,
76 : /** Request Time Out */
77 : BT_OBEX_RSP_CODE_REQ_TIMEOUT = 0xc8,
78 : /** Conflict */
79 : BT_OBEX_RSP_CODE_CONFLICT = 0xc9,
80 : /** Gone */
81 : BT_OBEX_RSP_CODE_GONE = 0xca,
82 : /** Length Required */
83 : BT_OBEX_RSP_CODE_LEN_REQ = 0xcb,
84 : /** Precondition Failed */
85 : BT_OBEX_RSP_CODE_PRECON_FAIL = 0xcc,
86 : /** Requested Entity Too Large */
87 : BT_OBEX_RSP_CODE_ENTITY_TOO_LARGE = 0xcd,
88 : /** Requested URL Too Large */
89 : BT_OBEX_RSP_CODE_URL_TOO_LARGE = 0xce,
90 : /** Unsupported media type */
91 : BT_OBEX_RSP_CODE_UNSUPP_MEDIA_TYPE = 0xcf,
92 : /** Internal serve Error */
93 : BT_OBEX_RSP_CODE_INTER_ERROR = 0xd0,
94 : /** Not Implemented */
95 : BT_OBEX_RSP_CODE_NOT_IMPL = 0xd1,
96 : /** Bad Gateway */
97 : BT_OBEX_RSP_CODE_BAD_GATEWAY = 0xd2,
98 : /** Service Unavailable */
99 : BT_OBEX_RSP_CODE_UNAVAIL = 0xd3,
100 : /** Gateway Timeout */
101 : BT_OBEX_RSP_CODE_GATEWAY_TIMEOUT = 0xd4,
102 : /** HTTP Version not supported */
103 : BT_OBEX_RSP_CODE_VER_UNSUPP = 0xd5,
104 : /** Database Full */
105 : BT_OBEX_RSP_CODE_DB_FULL = 0xe0,
106 : /** Database Locked */
107 : BT_OBEX_RSP_CODE_DB_LOCK = 0xe1,
108 : };
109 :
110 : /** Converts a OBEX response code to string.
111 : *
112 : * @param rsp_code Response code.
113 : *
114 : * @return The string representation of the response code.
115 : * If @kconfig{CONFIG_BT_OEBX_RSP_CODE_TO_STR} is not enabled,
116 : * this just returns the empty string.
117 : */
118 : #if defined(CONFIG_BT_OEBX_RSP_CODE_TO_STR)
119 : const char *bt_obex_rsp_code_to_str(enum bt_obex_rsp_code rsp_code);
120 : #else
121 1 : static inline const char *bt_obex_rsp_code_to_str(enum bt_obex_rsp_code rsp_code)
122 : {
123 : ARG_UNUSED(rsp_code);
124 :
125 : return "";
126 : }
127 : #endif /* CONFIG_BT_OEBX_RSP_CODE_TO_STR */
128 :
129 : /** @brief OBEX Header ID */
130 1 : enum __packed bt_obex_header_id {
131 : /** Number of objects (used by Connect) */
132 : BT_OBEX_HEADER_ID_COUNT = 0xC0,
133 :
134 : /** Name of the object (often a file name) */
135 : BT_OBEX_HEADER_ID_NAME = 0x01,
136 :
137 : /** Type of object - e.g. text, html, binary, manufacturer specific */
138 : BT_OBEX_HEADER_ID_TYPE = 0x42,
139 :
140 : /** The length of the object in bytes */
141 : BT_OBEX_HEADER_ID_LEN = 0xC3,
142 :
143 : /** Date/time stamp – ISO 8601 version - preferred */
144 : BT_OBEX_HEADER_ID_TIME_ISO_8601 = 0x44,
145 :
146 : /** Date/time stamp – 4 byte version (for compatibility only) */
147 : BT_OBEX_HEADER_ID_TIME = 0xC4,
148 :
149 : /** Text description of the object */
150 : BT_OBEX_HEADER_ID_DES = 0x05,
151 :
152 : /** Name of service that operation is targeted to */
153 : BT_OBEX_HEADER_ID_TARGET = 0x46,
154 :
155 : /** An HTTP 1.x header */
156 : BT_OBEX_HEADER_ID_HTTP = 0x47,
157 :
158 : /** A chunk of the object body. */
159 : BT_OBEX_HEADER_ID_BODY = 0x48,
160 :
161 : /** The final chunk of the object body. */
162 : BT_OBEX_HEADER_ID_END_BODY = 0x49,
163 :
164 : /** Identifies the OBEX application, used to tell if talking to a peer. */
165 : BT_OBEX_HEADER_ID_WHO = 0x4A,
166 :
167 : /** An identifier used for OBEX connection multiplexing. */
168 : BT_OBEX_HEADER_ID_CONN_ID = 0xCB,
169 :
170 : /** Extended application request & response information. */
171 : BT_OBEX_HEADER_ID_APP_PARAM = 0x4C,
172 :
173 : /** Authentication digest-challenge. */
174 : BT_OBEX_HEADER_ID_AUTH_CHALLENGE = 0x4D,
175 :
176 : /** Authentication digest-response. */
177 : BT_OBEX_HEADER_ID_AUTH_RSP = 0x4E,
178 :
179 : /** Indicates the creator of an object. */
180 : BT_OBEX_HEADER_ID_CREATE_ID = 0xCF,
181 :
182 : /** Uniquely identifies the network client (OBEX server). */
183 : BT_OBEX_HEADER_ID_WAN_UUID = 0x50,
184 :
185 : /** OBEX Object class of object. */
186 : BT_OBEX_HEADER_ID_OBJECT_CLASS = 0x51,
187 :
188 : /** Parameters used in session commands/responses. */
189 : BT_OBEX_HEADER_ID_SESSION_PARAM = 0x52,
190 :
191 : /** Sequence number used in each OBEX packet for reliability. */
192 : BT_OBEX_HEADER_ID_SESSION_SEQ_NUM = 0x93,
193 :
194 : /** Specifies the action to be performed (used in ACTION operation). */
195 : BT_OBEX_HEADER_ID_ACTION_ID = 0x94,
196 :
197 : /** The destination object name (used in certain ACTION operations). */
198 : BT_OBEX_HEADER_ID_DEST_NAME = 0x15,
199 :
200 : /** 4-byte bit mask for setting permissions. */
201 : BT_OBEX_HEADER_ID_PERM = 0xD6,
202 :
203 : /** 1-byte value to setup Single Response Mode (SRM). */
204 : BT_OBEX_HEADER_ID_SRM = 0x97,
205 :
206 : /** 1-byte value for setting parameters used during Single Response Mode (SRM). */
207 : BT_OBEX_HEADER_ID_SRM_PARAM = 0x98,
208 : };
209 :
210 0 : #define BT_OBEX_SEND_BUF_RESERVE 7
211 :
212 : struct bt_obex;
213 :
214 : /** @brief OBEX server operations structure.
215 : *
216 : * The object has to stay valid and constant for the lifetime of the OBEX server.
217 : */
218 1 : struct bt_obex_server_ops {
219 : /** @brief OBEX connect request callback
220 : *
221 : * If this callback is provided it will be called whenever the OBEX connect request
222 : * is received.
223 : *
224 : * @param obex The OBEX object.
225 : * @param version OBEX version number.
226 : * @param mopl Maximum OBEX packet length.
227 : * @param buf Sequence of headers.
228 : */
229 1 : void (*connect)(struct bt_obex *obex, uint8_t version, uint16_t mopl, struct net_buf *buf);
230 :
231 : /** @brief OBEX disconnect request callback
232 : *
233 : * If this callback is provided it will be called whenever the OBEX disconnect request
234 : * is received.
235 : *
236 : * @param obex The OBEX object.
237 : * @param buf Sequence of headers.
238 : */
239 1 : void (*disconnect)(struct bt_obex *obex, struct net_buf *buf);
240 :
241 : /** @brief OBEX put request callback
242 : *
243 : * If this callback is provided it will be called whenever the OBEX put request is
244 : * received.
245 : *
246 : * @param obex The OBEX object.
247 : * @param final If the final bit is set.
248 : * @param buf Sequence of headers.
249 : */
250 1 : void (*put)(struct bt_obex *obex, bool final, struct net_buf *buf);
251 :
252 : /** @brief OBEX get request callback
253 : *
254 : * If this callback is provided it will be called whenever the OBEX get request is
255 : * received.
256 : *
257 : * @param obex The OBEX object.
258 : * @param final If the final bit is set.
259 : * @param buf Sequence of headers.
260 : */
261 1 : void (*get)(struct bt_obex *obex, bool final, struct net_buf *buf);
262 :
263 : /** @brief OBEX abort request callback
264 : *
265 : * If this callback is provided it will be called whenever the OBEX abort request is
266 : * received.
267 : *
268 : * @param obex The OBEX object.
269 : * @param buf Optional headers.
270 : */
271 1 : void (*abort)(struct bt_obex *obex, struct net_buf *buf);
272 :
273 : /** @brief OBEX SetPath request callback
274 : *
275 : * If this callback is provided it will be called whenever the OBEX SetPath request is
276 : * received.
277 : *
278 : * @param obex The OBEX object.
279 : * @param flags The flags.
280 : * @param buf Optional headers.
281 : */
282 1 : void (*setpath)(struct bt_obex *obex, uint8_t flags, struct net_buf *buf);
283 :
284 : /** @brief OBEX action request callback
285 : *
286 : * If this callback is provided it will be called whenever the OBEX action request is
287 : * received.
288 : *
289 : * @param obex The OBEX object.
290 : * @param final If the final bit is set.
291 : * @param buf Sequence of headers (Including action identifier header if it exists).
292 : */
293 1 : void (*action)(struct bt_obex *obex, bool final, struct net_buf *buf);
294 : };
295 :
296 : /** @brief OBEX client operations structure.
297 : *
298 : * The object has to stay valid and constant for the lifetime of the OBEX client.
299 : */
300 1 : struct bt_obex_client_ops {
301 : /** @brief OBEX connect response callback
302 : *
303 : * If this callback is provided it will be called whenever the OBEX connect response
304 : * is received.
305 : *
306 : * @param obex The OBEX object.
307 : * @param rsp_code Response code.
308 : * @param version OBEX version number.
309 : * @param mopl Maximum OBEX packet length.
310 : * @param buf Sequence of headers.
311 : */
312 1 : void (*connect)(struct bt_obex *obex, uint8_t rsp_code, uint8_t version, uint16_t mopl,
313 : struct net_buf *buf);
314 :
315 : /** @brief OBEX disconnect response callback
316 : *
317 : * If this callback is provided it will be called whenever the OBEX disconnect response
318 : * is received.
319 : *
320 : * @param obex The OBEX object.
321 : * @param rsp_code Response code.
322 : * @param buf Sequence of headers.
323 : */
324 1 : void (*disconnect)(struct bt_obex *obex, uint8_t rsp_code, struct net_buf *buf);
325 :
326 : /** @brief OBEX put response callback
327 : *
328 : * If this callback is provided it will be called whenever the OBEX put response is
329 : * received.
330 : *
331 : * @param obex The OBEX object.
332 : * @param rsp_code Response code.
333 : * @param buf Optional response headers.
334 : */
335 1 : void (*put)(struct bt_obex *obex, uint8_t rsp_code, struct net_buf *buf);
336 :
337 : /** @brief OBEX get response callback
338 : *
339 : * If this callback is provided it will be called whenever the OBEX get response is
340 : * received.
341 : *
342 : * @param obex The OBEX object.
343 : * @param rsp_code Response code.
344 : * @param buf Optional response headers.
345 : */
346 1 : void (*get)(struct bt_obex *obex, uint8_t rsp_code, struct net_buf *buf);
347 :
348 : /** @brief OBEX abort response callback
349 : *
350 : * If this callback is provided it will be called whenever the OBEX abort response is
351 : * received.
352 : *
353 : * @param obex The OBEX object.
354 : * @param rsp_code Response code.
355 : * @param buf Optional response headers.
356 : */
357 1 : void (*abort)(struct bt_obex *obex, uint8_t rsp_code, struct net_buf *buf);
358 :
359 : /** @brief OBEX SetPath response callback
360 : *
361 : * If this callback is provided it will be called whenever the OBEX SetPath response is
362 : * received.
363 : *
364 : * @param obex The OBEX object.
365 : * @param rsp_code Response code.
366 : * @param buf Optional response headers.
367 : */
368 1 : void (*setpath)(struct bt_obex *obex, uint8_t rsp_code, struct net_buf *buf);
369 :
370 : /** @brief OBEX action response callback
371 : *
372 : * If this callback is provided it will be called whenever the OBEX action response is
373 : * received.
374 : *
375 : * @param obex The OBEX object.
376 : * @param rsp_code Response code.
377 : * @param buf Optional response headers.
378 : */
379 1 : void (*action)(struct bt_obex *obex, uint8_t rsp_code, struct net_buf *buf);
380 : };
381 :
382 : /** @brief OBEX transport operations structure.
383 : *
384 : * The object has to stay valid and constant for the lifetime of the OBEX client/server.
385 : */
386 1 : struct bt_obex_transport_ops {
387 : /** @brief allocate buf callback
388 : *
389 : * If this callback is provided it will be called to allocate a net buffer to store
390 : * the outgoing data.
391 : *
392 : * @param obex The OBEX object.
393 : * @param pool Which pool to take the buffer from.
394 : *
395 : * @return Allocated buffer.
396 : */
397 : struct net_buf *(*alloc_buf)(struct bt_obex *obex, struct net_buf_pool *pool);
398 :
399 : /** @brief Send OBEX data via transport
400 : *
401 : * If this callback is provided it will be called to send data via OBEX transport.
402 : *
403 : * @param obex The OBEX object.
404 : * @param buf OBEX packet.
405 : *
406 : * @return 0 in case of success or negative value in case of error.
407 : * @return -EMSGSIZE if `buf` is larger than `obex`'s MOPL.
408 : */
409 1 : int (*send)(struct bt_obex *obex, struct net_buf *buf);
410 :
411 : /** @brief Disconnect from transport
412 : *
413 : * If this callback is provided it will be called to disconnect transport.
414 : *
415 : * @param obex The OBEX object.
416 : *
417 : * @return 0 in case of success or negative value in case of error.
418 : */
419 1 : int (*disconnect)(struct bt_obex *obex);
420 : };
421 :
422 : /** @brief Life-span states of OBEX.
423 : *
424 : * Used only by internal APIs dealing with setting OBEX to proper state depending on operational
425 : * context.
426 : *
427 : * OBEX enters the @ref BT_OBEX_CONNECTING state upon @ref bt_obex_connect, or upon returning
428 : * from @ref bt_obex_server_ops::connect.
429 : *
430 : * When OBEX leaves the @ref BT_OBEX_CONNECTING state and enters the @ref BT_OBEX_CONNECTED,
431 : * @ref bt_obex_connect_rsp or @ref bt_obex_client_ops::connect is called with the response code
432 : * @ref BT_OBEX_RSP_CODE_SUCCESS.
433 : *
434 : * When OBEX enters the @ref BT_OBEX_DISCONNECTED from other states,
435 : * @ref bt_obex_client_ops::disconnect or @ref bt_obex_connect_rsp is called with the response code
436 : * @ref BT_OBEX_RSP_CODE_SUCCESS. Or OBEX transport enters the disconnected state from other OBEX
437 : * transport states.
438 : */
439 1 : enum __packed bt_obex_state {
440 : /** OBEX disconnected */
441 : BT_OBEX_DISCONNECTED,
442 : /** OBEX in connecting state */
443 : BT_OBEX_CONNECTING,
444 : /** OBEX ready for upper layer traffic on it */
445 : BT_OBEX_CONNECTED,
446 : /** OBEX in disconnecting state */
447 : BT_OBEX_DISCONNECTING,
448 : };
449 :
450 : /** @brief OBEX structure. */
451 1 : struct bt_obex {
452 : /** @brief OBEX Server operations
453 : *
454 : * If it is a obex sever, the upper layer should pass the operations of server to
455 : * `server_ops` when providing the OBEX structure.
456 : */
457 1 : const struct bt_obex_server_ops *server_ops;
458 :
459 : /** @brief OBEX Client operations
460 : *
461 : * If it is a obex client, the upper layer should pass the operations of client to
462 : * `client_ops` when providing the OBEX structure.
463 : */
464 1 : const struct bt_obex_client_ops *client_ops;
465 :
466 : struct {
467 : /** @brief MTU of OBEX transport */
468 1 : uint16_t mtu;
469 : /** @brief The Maximum OBEX Packet Length (MOPL) */
470 1 : uint16_t mopl;
471 0 : } rx;
472 :
473 : struct {
474 : /** @brief MTU of OBEX transport */
475 : uint16_t mtu;
476 : /** @brief The Maximum OBEX Packet Length (MOPL) */
477 : uint16_t mopl;
478 0 : } tx;
479 :
480 : /** @internal OBEX transport operations */
481 : const struct bt_obex_transport_ops *_transport_ops;
482 :
483 : /** @internal Saves the current state, @ref bt_obex_state */
484 : atomic_t _state;
485 :
486 : /** @internal OBEX opcode */
487 : atomic_t _opcode;
488 :
489 : /** @internal OBEX previous opcode */
490 : atomic_t _pre_opcode;
491 : };
492 :
493 : /** @brief OBEX connect request
494 : *
495 : * The connect operation initiates the connection and sets up the basic expectations of each side
496 : * of the link. The connect request must fit in a single packet.
497 : * The third parameter `buf` saves the packet data (sequence of headers) of the connect request is
498 : * stored in thrid parameter `buf`. All headers are packed by calling function
499 : * bt_obex_add_header_*. Such as header `Authenticate Challenge` is packed by calling
500 : * @ref bt_obex_add_header_auth_challenge.
501 : *
502 : * @note Buffer ownership is transferred to the stack in case of success, in case of an error
503 : * the caller retains the ownership of the buffer.
504 : *
505 : * @param obex OBEX object.
506 : * @param mopl Maximum OBEX packet length.
507 : * @param buf Sequence of headers to be sent out.
508 : *
509 : * @return 0 in case of success or negative value in case of error.
510 : */
511 1 : int bt_obex_connect(struct bt_obex *obex, uint16_t mopl, struct net_buf *buf);
512 :
513 : /** @brief OBEX connect response
514 : *
515 : * The connect response is used to acknowledged connect request packet.
516 : * The connect response must fit in a single packet.
517 : *
518 : * The second parameter `rsp_code` is used to pass the response code @ref bt_obex_rsp_code. The
519 : * typical values @ref BT_OBEX_RSP_CODE_SUCCESS for `success`.
520 : * The 4th parameter `buf` saves the packet data (sequence of headers) of the connect response is
521 : * stored in thrid parameter `buf`. All headers are packed by calling function
522 : * bt_obex_add_header_*. Such as header `Authenticate Response` is packed by calling
523 : * @ref bt_obex_add_header_auth_rsp.
524 : *
525 : * @note Buffer ownership is transferred to the stack in case of success, in case of an error
526 : * the caller retains the ownership of the buffer.
527 : *
528 : * @param obex OBEX object.
529 : * @param rsp_code Response code.
530 : * @param mopl Maximum OBEX packet length.
531 : * @param buf Sequence of headers to be sent out.
532 : *
533 : * @return 0 in case of success or negative value in case of error.
534 : */
535 1 : int bt_obex_connect_rsp(struct bt_obex *obex, uint8_t rsp_code, uint16_t mopl, struct net_buf *buf);
536 :
537 : /** @brief OBEX disconnect request
538 : *
539 : * The disconnect operation signals the end of the OBEX connection from client side.
540 : * The disconnect request must fit in a single packet.
541 : *
542 : * The second parameter `buf` saves the packet data (sequence of headers) of the disconnect
543 : * request is stored in second parameter `buf`. All headers are packed by calling function
544 : * bt_obex_add_header_*. Such as header `Connection Id` is packed by calling
545 : * @ref bt_obex_add_header_conn_id.
546 : *
547 : * @note Buffer ownership is transferred to the stack in case of success, in case of an error
548 : * the caller retains the ownership of the buffer.
549 : *
550 : * @param obex OBEX object.
551 : * @param buf Sequence of headers to be sent out.
552 : *
553 : * @return 0 in case of success or negative value in case of error.
554 : */
555 1 : int bt_obex_disconnect(struct bt_obex *obex, struct net_buf *buf);
556 :
557 : /** @brief OBEX disconnect response
558 : *
559 : * The disconnect response is used to acknowledged disconnect request packet.
560 : * The disconnect response must fit in a single packet.
561 : *
562 : * The second parameter `rsp_code` is used to pass the response code @ref bt_obex_rsp_code. The
563 : * typical values, @ref BT_OBEX_RSP_CODE_SUCCESS for `success`, @ref BT_OBEX_RSP_CODE_UNAVAIL for
564 : * `service unavailable` if the header `Connection Id` is invalid.
565 : * The third parameter `buf` saves the packet data (sequence of headers) of the connect response
566 : * is stored in third parameter `buf`. All headers are packed by calling function
567 : * bt_obex_add_header_*.
568 : *
569 : * @note Buffer ownership is transferred to the stack in case of success, in case of an error
570 : * the caller retains the ownership of the buffer.
571 : *
572 : * @param obex OBEX object.
573 : * @param rsp_code Response code.
574 : * @param buf Sequence of headers to be sent out.
575 : *
576 : * @return 0 in case of success or negative value in case of error.
577 : */
578 1 : int bt_obex_disconnect_rsp(struct bt_obex *obex, uint8_t rsp_code, struct net_buf *buf);
579 :
580 : /** @brief OBEX put request
581 : *
582 : * The put operation sends one object from the client to the server.
583 : * The put operation consists of one or more request packets, the last of which should have the
584 : * second parameter `final` set.
585 : * The third parameter `buf` saves the packet data (sequence of headers) of the put request is
586 : * stored in thrid parameter `buf`. All headers are packed by calling function
587 : * bt_obex_add_header_*. Such as header `Name` is packed by calling @ref bt_obex_add_header_name.
588 : *
589 : * @note A put operation with NO Body or End-of-Body headers whatsoever should be treated as a
590 : * delete request. Similarly, a put operation with an empty End-of-Body header requests the
591 : * recipient to create an empty object. This definition may not make sense or apply to every
592 : * implementation (in other words devices are not required to support delete operations or
593 : * empty objects).
594 : *
595 : * @note Buffer ownership is transferred to the stack in case of success, in case of an error
596 : * the caller retains the ownership of the buffer.
597 : *
598 : * @param obex OBEX object.
599 : * @param final The final bit of opcode.
600 : * @param buf Sequence of headers to be sent out.
601 : *
602 : * @return 0 in case of success or negative value in case of error.
603 : */
604 1 : int bt_obex_put(struct bt_obex *obex, bool final, struct net_buf *buf);
605 :
606 : /** @brief OBEX put response
607 : *
608 : * The put response is used to acknowledged each put request packet. It is sent from the server
609 : * to client.
610 : * The second parameter `rsp_code` is used to pass the response code @ref bt_obex_rsp_code. The
611 : * typical values, @ref BT_OBEX_RSP_CODE_CONTINUE for `continue`, @ref BT_OBEX_RSP_CODE_SUCCESS
612 : * for `success`.
613 : * The third parameter `buf` saves the packet data (sequence of headers) of the put response is
614 : * stored in thrid parameter `buf`. All headers are packed by calling function
615 : * bt_obex_add_header_*. Such as header `srm` is packed by calling @ref bt_obex_add_header_srm.
616 : * Or, the `buf` could be NULL if there is not any data needs to be sent.
617 : *
618 : * @note Buffer ownership is transferred to the stack in case of success, in case of an error
619 : * the caller retains the ownership of the buffer.
620 : *
621 : * @param obex OBEX object.
622 : * @param rsp_code Response code.
623 : * @param buf Sequence of headers to be sent out.
624 : *
625 : * @return 0 in case of success or negative value in case of error.
626 : */
627 1 : int bt_obex_put_rsp(struct bt_obex *obex, uint8_t rsp_code, struct net_buf *buf);
628 :
629 : /** @brief OBEX get request
630 : *
631 : * The get operation requests that the server return an object to the client.
632 : * The get operation consists of one or more request packets, the last of which should have the
633 : * second parameter `final` set, and the request phase of the get is complete. Once a get request
634 : * is sent with the final bit, all subsequent get request packets must set the final bit until
635 : * the operation is complete.
636 : * The third parameter `buf` saves the packet data (sequence of headers) of the get request is
637 : * stored in thrid parameter `buf`. All headers are packed by calling function
638 : * bt_obex_add_header_*. Such as header `Name` is packed by calling @ref bt_obex_add_header_name.
639 : * Or, the `buf` could be NULL if there is not any data needs to be sent.
640 : *
641 : * @note Buffer ownership is transferred to the stack in case of success, in case of an error
642 : * the caller retains the ownership of the buffer.
643 : *
644 : * @param obex OBEX object.
645 : * @param final The final bit of opcode.
646 : * @param buf Sequence of headers to be sent out.
647 : *
648 : * @return 0 in case of success or negative value in case of error.
649 : */
650 1 : int bt_obex_get(struct bt_obex *obex, bool final, struct net_buf *buf);
651 :
652 : /** @brief OBEX get response
653 : *
654 : * The get response is used to acknowledged get request packets. It is sent from the server
655 : * to client.
656 : * If the server has more than one object that fits the request, the behavior is system
657 : * dependent. But the server device must not begin sending the object body chunks until the
658 : * request phase is complete.
659 : *
660 : * The second parameter `rsp_code` is used to pass the response code @ref bt_obex_rsp_code. The
661 : * typical values, @ref BT_OBEX_RSP_CODE_CONTINUE for `continue`, @ref BT_OBEX_RSP_CODE_SUCCESS
662 : * for `success`.
663 : * A successful response for an object that fits entirely in one response packet is
664 : * @ref BT_OBEX_RSP_CODE_SUCCESS (Success, with Final bit set) in the response code, followed
665 : * by the object body. If the response is large enough to require multiple GET responses, only
666 : * the last response is @ref BT_OBEX_RSP_CODE_SUCCESS, and the others are all
667 : * @ref BT_OBEX_RSP_CODE_CONTINUE (Continue). The object is returned as a sequence of headers
668 : * just as with put operation. Any other response code @ref bt_obex_rsp_code indicates failure.
669 : * The typical failure response codes, @ref BT_OBEX_RSP_CODE_BAD_REQ for `Bad request - server
670 : * couldn’t understand request`, @ref BT_OBEX_RSP_CODE_FORBIDDEN for `Forbidden - operation is
671 : * understood but refused`.
672 : * The third parameter `buf` saves the packet data (sequence of headers) of the get response is
673 : * stored in thrid parameter `buf`. All headers are packed by calling function
674 : * bt_obex_add_header_*. Such as header `srm` is packed by calling @ref bt_obex_add_header_srm.
675 : * Or, the `buf` could be NULL if there is not any data needs to be sent.
676 : *
677 : * @note Buffer ownership is transferred to the stack in case of success, in case of an error
678 : * the caller retains the ownership of the buffer.
679 : *
680 : * @param obex OBEX object.
681 : * @param rsp_code Response code.
682 : * @param buf Sequence of headers to be sent out.
683 : *
684 : * @return 0 in case of success or negative value in case of error.
685 : */
686 1 : int bt_obex_get_rsp(struct bt_obex *obex, uint8_t rsp_code, struct net_buf *buf);
687 :
688 : /** @brief OBEX abort request
689 : *
690 : * The abort request is used when the client decides to terminate a multi-packet operation (such
691 : * as put) before it would be normally end. The abort request always fits in one OBEX packet and
692 : * have the Final bit set.
693 : * The second parameter `buf` saves the packet data (sequence of headers) of the abort request is
694 : * stored in thrid parameter `buf`. All headers are packed by calling function
695 : * bt_obex_add_header_*. Such as header `description` is packed by calling
696 : * @ref bt_obex_add_header_description. Or, the `buf` could be NULL if there is not any data
697 : * needs to be sent.
698 : *
699 : * @note Buffer ownership is transferred to the stack in case of success, in case of an error
700 : * the caller retains the ownership of the buffer.
701 : *
702 : * @param obex OBEX object.
703 : * @param buf Sequence of headers to be sent out.
704 : *
705 : * @return 0 in case of success or negative value in case of error.
706 : */
707 1 : int bt_obex_abort(struct bt_obex *obex, struct net_buf *buf);
708 :
709 : /** @brief OBEX abort response
710 : *
711 : * The abort response is used to acknowledged abort request packet. It is sent from the server
712 : * to client.
713 : * The abort response always fits in one OBEX packet and have the Final bit set.
714 : *
715 : * The second parameter `rsp_code` is used to pass the response code @ref bt_obex_rsp_code. The
716 : * typical value @ref BT_OBEX_RSP_CODE_SUCCESS for `success`.
717 : * The third parameter `buf` saves the packet data (sequence of headers) of the abort response is
718 : * stored in thrid parameter `buf`. All headers are packed by calling function
719 : * bt_obex_add_header_*. Or, the `buf` could be NULL if there is not any data needs to be sent.
720 : *
721 : * @note Buffer ownership is transferred to the stack in case of success, in case of an error
722 : * the caller retains the ownership of the buffer.
723 : *
724 : * @param obex OBEX object.
725 : * @param rsp_code Response code.
726 : * @param buf Sequence of headers to be sent out.
727 : *
728 : * @return 0 in case of success or negative value in case of error.
729 : */
730 1 : int bt_obex_abort_rsp(struct bt_obex *obex, uint8_t rsp_code, struct net_buf *buf);
731 :
732 : /** @brief OBEX setpath request
733 : *
734 : * The setpath request is used to set the "current folder" on the receiving side in order to
735 : * enable transfers that need additional path information. The Path name is contained in a Name
736 : * header.
737 : * The setpath request always fits in one OBEX packet and have the Final bit set.
738 : *
739 : * The second parameter `flags` is the setpath operation flag bit maps. Bit 0 means `backup a
740 : * level before applying name (equivalent to ../ on many systems)`. Bit 1 means `Don’t create
741 : * folder if it does not exist, return an error instead.` Other bits must be set to zero by
742 : * sender and ignored by receiver.
743 : * The third parameter `buf` saves the packet data (sequence of headers) of the setpath request is
744 : * stored in thrid parameter `buf`. All headers are packed by calling function
745 : * bt_obex_add_header_*. Such as header `Name` is packed by calling @ref bt_obex_add_header_name.
746 : * If the header `Name` is added, it means the client wants to go one level down relative to the
747 : * current folder into the folder `name`. Or, the client wants to go back to the default folder
748 : * when no bit of flags set.
749 : *
750 : * @note The Name header may be omitted when flags or constants indicate the entire operation
751 : * being requested. For example, back up one level (bit 0 of `flags` is set), equivalent to
752 : * "cd .." on some systems.
753 : *
754 : * @note Buffer ownership is transferred to the stack in case of success, in case of an error
755 : * the caller retains the ownership of the buffer.
756 : *
757 : * @param obex OBEX object.
758 : * @param flags Flags for setpath request.
759 : * @param buf Sequence of headers to be sent out.
760 : *
761 : * @return 0 in case of success or negative value in case of error.
762 : */
763 1 : int bt_obex_setpath(struct bt_obex *obex, uint8_t flags, struct net_buf *buf);
764 :
765 : /** @brief OBEX setpath response
766 : *
767 : * The setpath response is used to acknowledged setpath request packet. It is sent from the
768 : * server to client.
769 : * The setpath response always fits in one OBEX packet and have the Final bit set.
770 : *
771 : * The second parameter `rsp_code` is used to pass the response code @ref bt_obex_rsp_code. The
772 : * typical value @ref BT_OBEX_RSP_CODE_SUCCESS for `success`. Any other response code
773 : * @ref bt_obex_rsp_code indicates failure. The typical failure response codes,
774 : * @ref BT_OBEX_RSP_CODE_BAD_REQ for `Bad request - server couldn’t understand request`,
775 : * @ref BT_OBEX_RSP_CODE_FORBIDDEN for `Forbidden - operation is understood but refused`.
776 : * The third parameter `buf` saves the packet data (sequence of headers) of the setpath response
777 : * is stored in thrid parameter `buf`. All headers are packed by calling function
778 : * bt_obex_add_header_*. Or, the `buf` could be NULL if there is not any data needs to be sent.
779 : *
780 : * @note Buffer ownership is transferred to the stack in case of success, in case of an error
781 : * the caller retains the ownership of the buffer.
782 : *
783 : * @param obex OBEX object.
784 : * @param rsp_code Response code.
785 : * @param buf Sequence of headers to be sent out.
786 : *
787 : * @return 0 in case of success or negative value in case of error.
788 : */
789 1 : int bt_obex_setpath_rsp(struct bt_obex *obex, uint8_t rsp_code, struct net_buf *buf);
790 :
791 : /** @brief OBEX Actions. */
792 1 : enum __packed bt_obex_action_id {
793 : /** Copy Object Action */
794 : BT_OBEX_ACTION_COPY = 0x00,
795 : /** Move/Rename Object Action */
796 : BT_OBEX_ACTION_MOVE_RENAME = 0x01,
797 : /** Set Object Permissions Action */
798 : BT_OBEX_ACTION_SET_PERM = 0x02,
799 : };
800 :
801 : /** @brief OBEX action request
802 : *
803 : * The action operation is defined to cover the needs of common actions. The `Action Id` header
804 : * @ref BT_OBEX_HEADER_ID_ACTION_ID is used in the action operation and contains an action
805 : * identifier which defines what action is to be performed. All actions are optional and depends
806 : * on the implementation of server.
807 : *
808 : * There are three actions defined @ref bt_obex_action_id,
809 : *
810 : * @ref BT_OBEX_ACTION_COPY is used to copy an object from one location to another. The header
811 : * `Name` @ref BT_OBEX_HEADER_ID_NAME specifies the source file name and the header `Dest Name`
812 : * @ref BT_OBEX_HEADER_ID_DEST_NAME specifies the destination file name. These two headers are
813 : * mandatory for this action.
814 : *
815 : * @ref BT_OBEX_ACTION_MOVE_RENAME is used to move an object from one location to another. It
816 : * can also be used to rename an object. The header `Name` @ref BT_OBEX_HEADER_ID_NAME specifies
817 : * the source file name and the header `Dest Name` @ref BT_OBEX_HEADER_ID_DEST_NAME specifies the
818 : * destination file name. These two headers are mandatory for this action.
819 : *
820 : * @ref BT_OBEX_ACTION_SET_PERM is used to set the access permissions of an object or folder.
821 : * The header `Name` @ref BT_OBEX_HEADER_ID_NAME specifies the source file name and the header
822 : * `Permissions` @ref BT_OBEX_HEADER_ID_PERM specifies the new permissions for this object. These
823 : * two headers are mandatory for this action.
824 : *
825 : * The action operation consists of one or more request packets, the last of which should have
826 : * the second parameter `final` set.
827 : * The third parameter `buf` saves the packet data (sequence of headers) of the action request is
828 : * stored in thrid parameter `buf`. All headers are packed by calling function
829 : * bt_obex_add_header_*. Such as header `Name` is packed by calling @ref bt_obex_add_header_name.
830 : *
831 : * @note Buffer ownership is transferred to the stack in case of success, in case of an error
832 : * the caller retains the ownership of the buffer.
833 : *
834 : * @param obex OBEX object.
835 : * @param final The final bit of opcode.
836 : * @param buf Sequence of headers to be sent out.
837 : *
838 : * @return 0 in case of success or negative value in case of error.
839 : */
840 1 : int bt_obex_action(struct bt_obex *obex, bool final, struct net_buf *buf);
841 :
842 : /** @brief OBEX action response
843 : *
844 : * The action response is used to acknowledged action request packets. It is sent from the server
845 : * to client.
846 : * The second parameter `rsp_code` is used to pass the response code @ref bt_obex_rsp_code. The
847 : * typical value @ref BT_OBEX_RSP_CODE_SUCCESS for `success`.
848 : *
849 : * There are three actions defined @ref bt_obex_action_id. For each action request, there are
850 : * failure response codes corresponding to it.
851 : *
852 : * For action @ref BT_OBEX_ACTION_COPY,
853 : * @ref BT_OBEX_RSP_CODE_NOT_FOUND - `Source object or destination folder does not exist`.
854 : * @ref BT_OBEX_RSP_CODE_FORBIDDEN - `Cannot modify the permissions of the destination
855 : * object/folder, permission denied`.
856 : * @ref BT_OBEX_RSP_CODE_DB_FULL - `Cannot create object in destination folder, out of memory`
857 : * @ref BT_OBEX_RSP_CODE_CONFLICT - `Cannot modify the permissions, sharing violation, object or
858 : * Set Object Permissions Action busy`.
859 : * @ref BT_OBEX_RSP_CODE_NOT_IMPL - `Set Object Permissions Action not supported`.
860 : * @ref BT_OBEX_RSP_CODE_NOT_MODIFIED - `Cannot create folder/file, destination folder/file
861 : * already exits`.
862 : *
863 : * For action @ref BT_OBEX_ACTION_MOVE_RENAME,
864 : * @ref BT_OBEX_RSP_CODE_NOT_FOUND - `Source object or destination folder does not exist`.
865 : * @ref BT_OBEX_RSP_CODE_FORBIDDEN - `Cannot modify the permissions of the destination
866 : * object/folder, permission denied`.
867 : * @ref BT_OBEX_RSP_CODE_DB_FULL - `Cannot create object in destination folder, out of memory`
868 : * @ref BT_OBEX_RSP_CODE_CONFLICT - `Cannot modify the permissions, sharing violation, object or
869 : * Set Object Permissions Action busy`.
870 : * @ref BT_OBEX_RSP_CODE_NOT_IMPL - `Set Object Permissions Action not supported`.
871 : * @ref BT_OBEX_RSP_CODE_NOT_MODIFIED - `Cannot create folder/file, destination folder/file
872 : * already exits`.
873 : *
874 : * For action @ref BT_OBEX_ACTION_SET_PERM,
875 : * @ref BT_OBEX_RSP_CODE_NOT_FOUND - `Source object or destination folder does not exist`.
876 : * @ref BT_OBEX_RSP_CODE_FORBIDDEN - `Cannot modify the permissions of the destination
877 : * object/folder, permission denied`.
878 : * @ref BT_OBEX_RSP_CODE_NOT_IMPL - `Set Object Permissions Action not supported`.
879 : * @ref BT_OBEX_RSP_CODE_CONFLICT - `Cannot modify the permissions, sharing violation, object or
880 : * Set Object Permissions Action busy`.
881 : *
882 : * The third parameter `buf` saves the packet data (sequence of headers) of the action response
883 : * is stored in thrid parameter `buf`. All headers are packed by calling function
884 : * bt_obex_add_header_*. Or, the `buf` could be NULL if there is not any data needs to be sent.
885 : *
886 : * @note Buffer ownership is transferred to the stack in case of success, in case of an error
887 : * the caller retains the ownership of the buffer.
888 : *
889 : * @param obex OBEX object.
890 : * @param rsp_code Response code.
891 : * @param buf Sequence of headers to be sent out.
892 : *
893 : * @return 0 in case of success or negative value in case of error.
894 : */
895 1 : int bt_obex_action_rsp(struct bt_obex *obex, uint8_t rsp_code, struct net_buf *buf);
896 :
897 : /** @brief Add Header: number of objects (used by Connect)
898 : *
899 : * @param buf Buffer needs to be sent.
900 : * @param count Number of objects.
901 : *
902 : * @return 0 in case of success or negative value in case of error.
903 : */
904 1 : int bt_obex_add_header_count(struct net_buf *buf, uint32_t count);
905 :
906 : /** @brief Add Header: name of the object (often a file name)
907 : *
908 : * @param buf Buffer needs to be sent.
909 : * @param len Length of name.
910 : * @param name Name of the object.
911 : *
912 : * @return 0 in case of success or negative value in case of error.
913 : */
914 1 : int bt_obex_add_header_name(struct net_buf *buf, uint16_t len, const uint8_t *name);
915 :
916 : /** @brief Add Header: type of object - e.g. text, html, binary, manufacturer specific
917 : *
918 : * @param buf Buffer needs to be sent.
919 : * @param len Length of type.
920 : * @param type Type of the object.
921 : *
922 : * @return 0 in case of success or negative value in case of error.
923 : */
924 1 : int bt_obex_add_header_type(struct net_buf *buf, uint16_t len, const uint8_t *type);
925 :
926 : /** @brief Add Header: the length of the object in bytes
927 : *
928 : * @param buf Buffer needs to be sent.
929 : * @param len The length of the object in bytes.
930 : *
931 : * @return 0 in case of success or negative value in case of error.
932 : */
933 1 : int bt_obex_add_header_len(struct net_buf *buf, uint32_t len);
934 :
935 : /** @brief Add Header: date/time stamp – ISO 8601 version - preferred
936 : *
937 : * @param buf Buffer needs to be sent.
938 : * @param len Length of data/time stamp.
939 : * @param t Data/time stamp.
940 : *
941 : * @return 0 in case of success or negative value in case of error.
942 : */
943 1 : int bt_obex_add_header_time_iso_8601(struct net_buf *buf, uint16_t len, const uint8_t *t);
944 :
945 : /** @brief Add Header: date/time stamp – 4 byte version (for compatibility only)
946 : *
947 : * @param buf Buffer needs to be sent.
948 : * @param t Data/time stamp.
949 : *
950 : * @return 0 in case of success or negative value in case of error.
951 : */
952 1 : int bt_obex_add_header_time(struct net_buf *buf, uint32_t t);
953 :
954 : /** @brief Add Header: text description of the object
955 : *
956 : * @param buf Buffer needs to be sent.
957 : * @param len Length of description.
958 : * @param dec Description of the object.
959 : *
960 : * @return 0 in case of success or negative value in case of error.
961 : */
962 1 : int bt_obex_add_header_description(struct net_buf *buf, uint16_t len, const uint8_t *dec);
963 :
964 : /** @brief Add Header: name of service that operation is targeted to
965 : *
966 : * @param buf Buffer needs to be sent.
967 : * @param len Length of target name.
968 : * @param target Target name.
969 : *
970 : * @return 0 in case of success or negative value in case of error.
971 : */
972 1 : int bt_obex_add_header_target(struct net_buf *buf, uint16_t len, const uint8_t *target);
973 :
974 : /** @brief Add Header: an HTTP 1.x header
975 : *
976 : * @param buf Buffer needs to be sent.
977 : * @param len Length of http 1.x header.
978 : * @param http Http 1.x header.
979 : *
980 : * @return 0 in case of success or negative value in case of error.
981 : */
982 1 : int bt_obex_add_header_http(struct net_buf *buf, uint16_t len, const uint8_t *http);
983 :
984 : /** @brief Add Header: a chunk of the object body
985 : *
986 : * @param buf Buffer needs to be sent.
987 : * @param len Length of body.
988 : * @param body Object Body.
989 : *
990 : * @return 0 in case of success or negative value in case of error.
991 : */
992 1 : int bt_obex_add_header_body(struct net_buf *buf, uint16_t len, const uint8_t *body);
993 :
994 : /** @brief Add Header: the final chunk of the object body.
995 : *
996 : * @param buf Buffer needs to be sent.
997 : * @param len Length of body.
998 : * @param body Object Body.
999 : *
1000 : * @return 0 in case of success or negative value in case of error.
1001 : */
1002 1 : int bt_obex_add_header_end_body(struct net_buf *buf, uint16_t len, const uint8_t *body);
1003 :
1004 : /** @brief Add Header: identifies the OBEX application, used to tell if talking to a peer.
1005 : *
1006 : * @param buf Buffer needs to be sent.
1007 : * @param len Length of who.
1008 : * @param who Who.
1009 : *
1010 : * @return 0 in case of success or negative value in case of error.
1011 : */
1012 1 : int bt_obex_add_header_who(struct net_buf *buf, uint16_t len, const uint8_t *who);
1013 :
1014 : /** @brief Add Header: an identifier used for OBEX connection multiplexing.
1015 : *
1016 : * @param buf Buffer needs to be sent.
1017 : * @param conn_id Connection Id.
1018 : *
1019 : * @return 0 in case of success or negative value in case of error.
1020 : */
1021 1 : int bt_obex_add_header_conn_id(struct net_buf *buf, uint32_t conn_id);
1022 :
1023 : /**
1024 : * @brief Bluetooth OBEX TLV triplet.
1025 : *
1026 : * Description of different data types that can be encoded into
1027 : * TLV triplet. Used to form arrays that are passed to the
1028 : * bt_obex_add_header_app_param(), bt_obex_add_header_auth_challenge(),
1029 : * and bt_obex_add_header_auth_rsp() function.
1030 : */
1031 1 : struct bt_obex_tlv {
1032 0 : uint8_t type;
1033 0 : uint8_t data_len;
1034 0 : const uint8_t *data;
1035 : };
1036 :
1037 : /** @brief Add Header: extended application request & response information.
1038 : *
1039 : * @param buf Buffer needs to be sent.
1040 : * @param count Number of @ref bt_obex_tlv structures in @p data.
1041 : * @param data Array of @ref bt_obex_tlv structures.
1042 : *
1043 : * @return 0 in case of success or negative value in case of error.
1044 : */
1045 1 : int bt_obex_add_header_app_param(struct net_buf *buf, size_t count,
1046 : const struct bt_obex_tlv data[]);
1047 :
1048 : /**
1049 : * OBEX digest-challenge tag: Nonce
1050 : * String of bytes representing the nonce.
1051 : */
1052 1 : #define BT_OBEX_CHALLENGE_TAG_NONCE 0x00
1053 :
1054 : /**
1055 : * OBEX digest-challenge tag: Options
1056 : * Optional Challenge Information.
1057 : */
1058 1 : #define BT_OBEX_CHALLENGE_TAG_OPTIONS 0x01
1059 :
1060 : /** Option BIT0: When set, the User Id must be sent in the authenticate response. */
1061 1 : #define BT_OBEX_CHALLENGE_TAG_OPTION_REQ_USER_ID BIT(0)
1062 : /** Option BIT1: Access mode: Read Only when set, otherwise Full access is permitted. */
1063 1 : #define BT_OBEX_CHALLENGE_TAG_OPTION_ACCESS_MODE BIT(1)
1064 :
1065 : /**
1066 : * OBEX digest-challenge tag: Realm
1067 : * A displayable string indicating which userid and/or password to use. The first byte of the
1068 : * string is the character set to use. The character set uses the same values as those defined
1069 : * in IrLMP for the nickname.
1070 : */
1071 1 : #define BT_OBEX_CHALLENGE_TAG_REALM 0x02
1072 :
1073 : /** @brief Add Header: authentication digest-challenge.
1074 : *
1075 : * @param buf Buffer needs to be sent.
1076 : * @param count Number of @ref bt_obex_tlv structures in @p data.
1077 : * @param data Array of @ref bt_obex_tlv structures.
1078 : *
1079 : * @return 0 in case of success or negative value in case of error.
1080 : */
1081 1 : int bt_obex_add_header_auth_challenge(struct net_buf *buf, size_t count,
1082 : const struct bt_obex_tlv data[]);
1083 :
1084 : /**
1085 : * OBEX digest-Response tag: Request-digest
1086 : * String of bytes representing the request digest.
1087 : */
1088 1 : #define BT_OBEX_RESPONSE_TAG_REQ_DIGEST 0x00
1089 :
1090 : /**
1091 : * OBEX digest-Response tag: User Id
1092 : * User ID string of length n. Max size is 20 bytes.
1093 : */
1094 1 : #define BT_OBEX_RESPONSE_TAG_USER_ID 0x01
1095 :
1096 : /**
1097 : * OBEX digest-Response tag: Nonce
1098 : * The nonce sent in the digest challenge string.
1099 : */
1100 1 : #define BT_OBEX_RESPONSE_TAG_NONCE 0x02
1101 :
1102 : /** @brief Add Header: authentication digest-response.
1103 : *
1104 : * @param buf Buffer needs to be sent.
1105 : * @param count Number of @ref bt_obex_tlv structures in @p data.
1106 : * @param data Array of @ref bt_obex_tlv structures.
1107 : *
1108 : * @return 0 in case of success or negative value in case of error.
1109 : */
1110 1 : int bt_obex_add_header_auth_rsp(struct net_buf *buf, size_t count, const struct bt_obex_tlv data[]);
1111 :
1112 : /** @brief Add Header: indicates the creator of an object.
1113 : *
1114 : * @param buf Buffer needs to be sent.
1115 : * @param creator_id Creator Id.
1116 : *
1117 : * @return 0 in case of success or negative value in case of error.
1118 : */
1119 1 : int bt_obex_add_header_creator_id(struct net_buf *buf, uint32_t creator_id);
1120 :
1121 : /** @brief Add Header: uniquely identifies the network client (OBEX server).
1122 : *
1123 : * @param buf Buffer needs to be sent.
1124 : * @param len Length of UUID.
1125 : * @param uuid UUID.
1126 : *
1127 : * @return 0 in case of success or negative value in case of error.
1128 : */
1129 1 : int bt_obex_add_header_wan_uuid(struct net_buf *buf, uint16_t len, const uint8_t *uuid);
1130 :
1131 : /** @brief Add Header: OBEX Object class of object.
1132 : *
1133 : * @param buf Buffer needs to be sent.
1134 : * @param len Length of object class.
1135 : * @param obj_class Class of object.
1136 : *
1137 : * @return 0 in case of success or negative value in case of error.
1138 : */
1139 1 : int bt_obex_add_header_obj_class(struct net_buf *buf, uint16_t len, const uint8_t *obj_class);
1140 :
1141 : /** @brief Add Header: parameters used in session commands/responses.
1142 : *
1143 : * @param buf Buffer needs to be sent.
1144 : * @param len Length of session parameter.
1145 : * @param session_param Session parameter.
1146 : *
1147 : * @return 0 in case of success or negative value in case of error.
1148 : */
1149 1 : int bt_obex_add_header_session_param(struct net_buf *buf, uint16_t len,
1150 : const uint8_t *session_param);
1151 :
1152 : /** @brief Add Header: sequence number used in each OBEX packet for reliability.
1153 : *
1154 : * @param buf Buffer needs to be sent.
1155 : * @param session_seq_number Session sequence parameter.
1156 : *
1157 : * @return 0 in case of success or negative value in case of error.
1158 : */
1159 1 : int bt_obex_add_header_session_seq_number(struct net_buf *buf, uint32_t session_seq_number);
1160 :
1161 : /** @brief Add Header: specifies the action to be performed (used in ACTION operation).
1162 : *
1163 : * @param buf Buffer needs to be sent.
1164 : * @param action_id Action Id @ref bt_obex_action_id.
1165 : *
1166 : * @return 0 in case of success or negative value in case of error.
1167 : */
1168 1 : int bt_obex_add_header_action_id(struct net_buf *buf, uint32_t action_id);
1169 :
1170 : /** @brief Add Header: the destination object name (used in certain ACTION operations).
1171 : *
1172 : * @param buf Buffer needs to be sent.
1173 : * @param len Length of destination name.
1174 : * @param dest_name Destination name.
1175 : *
1176 : * @return 0 in case of success or negative value in case of error.
1177 : */
1178 1 : int bt_obex_add_header_dest_name(struct net_buf *buf, uint16_t len, const uint8_t *dest_name);
1179 :
1180 : /** @brief Add Header: 4-byte bit mask for setting permissions.
1181 : *
1182 : * @param buf Buffer needs to be sent.
1183 : * @param perm Permissions.
1184 : *
1185 : * @return 0 in case of success or negative value in case of error.
1186 : */
1187 1 : int bt_obex_add_header_perm(struct net_buf *buf, uint32_t perm);
1188 :
1189 : /** @brief Add Header: 1-byte value to setup Single Response Mode (SRM).
1190 : *
1191 : * @param buf Buffer needs to be sent.
1192 : * @param srm SRM.
1193 : *
1194 : * @return 0 in case of success or negative value in case of error.
1195 : */
1196 1 : int bt_obex_add_header_srm(struct net_buf *buf, uint8_t srm);
1197 :
1198 : /** @brief Add Header: Single Response Mode (SRM) Parameter.
1199 : *
1200 : * @param buf Buffer needs to be sent.
1201 : * @param srm_param SRM parameter.
1202 : *
1203 : * @return 0 in case of success or negative value in case of error.
1204 : */
1205 1 : int bt_obex_add_header_srm_param(struct net_buf *buf, uint8_t srm_param);
1206 :
1207 : /** @brief OBEX Header structure */
1208 1 : struct bt_obex_hdr {
1209 : /** Header ID @ref bt_obex_header_id */
1210 1 : uint8_t id;
1211 : /** The length of header value */
1212 1 : uint16_t len;
1213 : /** Header value */
1214 1 : const uint8_t *data;
1215 : };
1216 :
1217 : /** @brief Helper for parsing OBEX header.
1218 : *
1219 : * A helper for parsing the header structure for OBEX packets. The most common scenario is to
1220 : * call this helper on the in the callback of OBEX server and client.
1221 : *
1222 : * @warning This helper function will consume `buf` when parsing. The user should make a copy
1223 : * if the original data is to be used afterwards.
1224 : *
1225 : * @param buf OBEX packet as given to the callback of OBEX server and client.
1226 : * @param func Callback function which will be called for each element that's found in the data
1227 : * The callback should return true to continue parsing, or false to stop parsing.
1228 : * @param user_data User data to be passed to the callback.
1229 : *
1230 : * @return 0 in case of success or negative value in case of error.
1231 : */
1232 1 : int bt_obex_header_parse(struct net_buf *buf,
1233 : bool (*func)(struct bt_obex_hdr *hdr, void *user_data), void *user_data);
1234 :
1235 : /** @brief Get header value: number of objects (used by Connect)
1236 : *
1237 : * @param buf Buffer needs to be sent.
1238 : * @param count Number of objects.
1239 : *
1240 : * @return 0 in case of success or negative value in case of error.
1241 : */
1242 1 : int bt_obex_get_header_count(struct net_buf *buf, uint32_t *count);
1243 :
1244 : /** @brief Get header value: name of the object (often a file name)
1245 : *
1246 : * @param buf Buffer needs to be sent.
1247 : * @param len Length of name.
1248 : * @param name Name of the object.
1249 : *
1250 : * @return 0 in case of success or negative value in case of error.
1251 : */
1252 1 : int bt_obex_get_header_name(struct net_buf *buf, uint16_t *len, const uint8_t **name);
1253 :
1254 : /** @brief Get header value: type of object - e.g. text, html, binary, manufacturer specific
1255 : *
1256 : * @param buf Buffer needs to be sent.
1257 : * @param len Length of type.
1258 : * @param type Type of the object.
1259 : *
1260 : * @return 0 in case of success or negative value in case of error.
1261 : */
1262 1 : int bt_obex_get_header_type(struct net_buf *buf, uint16_t *len, const uint8_t **type);
1263 :
1264 : /** @brief Get header value: the length of the object in bytes
1265 : *
1266 : * @param buf Buffer needs to be sent.
1267 : * @param len The length of the object in bytes.
1268 : *
1269 : * @return 0 in case of success or negative value in case of error.
1270 : */
1271 1 : int bt_obex_get_header_len(struct net_buf *buf, uint32_t *len);
1272 :
1273 : /** @brief Get header value: date/time stamp – ISO 8601 version - preferred
1274 : *
1275 : * @param buf Buffer needs to be sent.
1276 : * @param len Length of data/time stamp.
1277 : * @param t Data/time stamp.
1278 : *
1279 : * @return 0 in case of success or negative value in case of error.
1280 : */
1281 1 : int bt_obex_get_header_time_iso_8601(struct net_buf *buf, uint16_t *len, const uint8_t **t);
1282 :
1283 : /** @brief Get header value: date/time stamp – 4 byte version (for compatibility only)
1284 : *
1285 : * @param buf Buffer needs to be sent.
1286 : * @param t Data/time stamp.
1287 : *
1288 : * @return 0 in case of success or negative value in case of error.
1289 : */
1290 1 : int bt_obex_get_header_time(struct net_buf *buf, uint32_t *t);
1291 :
1292 : /** @brief Get header value: text description of the object
1293 : *
1294 : * @param buf Buffer needs to be sent.
1295 : * @param len Length of description.
1296 : * @param dec Description of the object.
1297 : *
1298 : * @return 0 in case of success or negative value in case of error.
1299 : */
1300 1 : int bt_obex_get_header_description(struct net_buf *buf, uint16_t *len, const uint8_t **dec);
1301 :
1302 : /** @brief Get header value: name of service that operation is targeted to
1303 : *
1304 : * @param buf Buffer needs to be sent.
1305 : * @param len Length of target name.
1306 : * @param target Target name.
1307 : *
1308 : * @return 0 in case of success or negative value in case of error.
1309 : */
1310 1 : int bt_obex_get_header_target(struct net_buf *buf, uint16_t *len, const uint8_t **target);
1311 :
1312 : /** @brief Get header value: an HTTP 1.x header
1313 : *
1314 : * @param buf Buffer needs to be sent.
1315 : * @param len Length of http 1.x header.
1316 : * @param http Http 1.x header.
1317 : *
1318 : * @return 0 in case of success or negative value in case of error.
1319 : */
1320 1 : int bt_obex_get_header_http(struct net_buf *buf, uint16_t *len, const uint8_t **http);
1321 :
1322 : /** @brief Get header value: a chunk of the object body.
1323 : *
1324 : * @param buf Buffer needs to be sent.
1325 : * @param len Length of body.
1326 : * @param body Object Body.
1327 : *
1328 : * @return 0 in case of success or negative value in case of error.
1329 : */
1330 1 : int bt_obex_get_header_body(struct net_buf *buf, uint16_t *len, const uint8_t **body);
1331 :
1332 : /** @brief Get header value: the final chunk of the object body.
1333 : *
1334 : * @param buf Buffer needs to be sent.
1335 : * @param len Length of body.
1336 : * @param body Object Body.
1337 : *
1338 : * @return 0 in case of success or negative value in case of error.
1339 : */
1340 1 : int bt_obex_get_header_end_body(struct net_buf *buf, uint16_t *len, const uint8_t **body);
1341 :
1342 : /** @brief Get header value: identifies the OBEX application, used to tell if talking to a peer.
1343 : *
1344 : * @param buf Buffer needs to be sent.
1345 : * @param len Length of who.
1346 : * @param who Who.
1347 : *
1348 : * @return 0 in case of success or negative value in case of error.
1349 : */
1350 1 : int bt_obex_get_header_who(struct net_buf *buf, uint16_t *len, const uint8_t **who);
1351 :
1352 : /** @brief Get header value: an identifier used for OBEX connection multiplexing.
1353 : *
1354 : * @param buf Buffer needs to be sent.
1355 : * @param conn_id Connection Id.
1356 : *
1357 : * @return 0 in case of success or negative value in case of error.
1358 : */
1359 1 : int bt_obex_get_header_conn_id(struct net_buf *buf, uint32_t *conn_id);
1360 :
1361 : /** @brief Helper for parsing OBEX TLV triplet.
1362 : *
1363 : * A helper for parsing the TLV triplet structure for OBEX packets. The most common scenario is to
1364 : * call this helper on the in the callback of OBEX server and client.
1365 : * The @p data is encoded by using A Tag-Length-Value encoding scheme. Usually, it is the header
1366 : * value of the header `Application Request-Response Parameters`, `Authenticate Challenge`, and
1367 : * `Authenticate Response`. It means the @p data is the output of the
1368 : * @ref bt_obex_get_header_app_param, @ref bt_obex_get_header_auth_challenge, or
1369 : * @ref bt_obex_get_header_auth_rsp.
1370 : *
1371 : * @param len The length of the @p data.
1372 : * @param data The data as given to the callback of OBEX server and client.
1373 : * @param func Callback function which will be called for each TLV triplet that's found from the
1374 : * @p data. The callback should return true to continue parsing, or false to stop
1375 : * parsing.
1376 : * @param user_data User data to be passed to the callback.
1377 : *
1378 : * @return 0 in case of success or negative value in case of error.
1379 : */
1380 1 : int bt_obex_tlv_parse(uint16_t len, const uint8_t *data,
1381 : bool (*func)(struct bt_obex_tlv *tlv, void *user_data), void *user_data);
1382 :
1383 : /** @brief Get header value: extended application request & response information.
1384 : *
1385 : * The parameter can be parsed by calling @ref bt_obex_tlv_parse.
1386 : *
1387 : * @param buf Buffer needs to be sent.
1388 : * @param len Length of app_param.
1389 : * @param app_param Application parameter.
1390 : *
1391 : * @return 0 in case of success or negative value in case of error.
1392 : */
1393 1 : int bt_obex_get_header_app_param(struct net_buf *buf, uint16_t *len, const uint8_t **app_param);
1394 :
1395 : /** @brief Get header value: authentication digest-challenge.
1396 : *
1397 : * The options can be parsed by calling @ref bt_obex_tlv_parse.
1398 : *
1399 : * @param buf Buffer needs to be sent.
1400 : * @param len Length of auth_challenge.
1401 : * @param auth Authentication challenge.
1402 : *
1403 : * @return 0 in case of success or negative value in case of error.
1404 : */
1405 1 : int bt_obex_get_header_auth_challenge(struct net_buf *buf, uint16_t *len, const uint8_t **auth);
1406 :
1407 : /** @brief Get header value: authentication digest-response.
1408 : *
1409 : * The options can be parsed by calling @ref bt_obex_tlv_parse.
1410 : *
1411 : * @param buf Buffer needs to be sent.
1412 : * @param len Length of authentication response.
1413 : * @param auth Authentication response.
1414 : *
1415 : * @return 0 in case of success or negative value in case of error.
1416 : */
1417 1 : int bt_obex_get_header_auth_rsp(struct net_buf *buf, uint16_t *len, const uint8_t **auth);
1418 :
1419 : /** @brief Get header value: indicates the creator of an object.
1420 : *
1421 : * @param buf Buffer needs to be sent.
1422 : * @param creator_id Creator Id.
1423 : *
1424 : * @return 0 in case of success or negative value in case of error.
1425 : */
1426 1 : int bt_obex_get_header_creator_id(struct net_buf *buf, uint32_t *creator_id);
1427 :
1428 : /** @brief Get header value: uniquely identifies the network client (OBEX server).
1429 : *
1430 : * @param buf Buffer needs to be sent.
1431 : * @param len Length of UUID.
1432 : * @param uuid UUID.
1433 : *
1434 : * @return 0 in case of success or negative value in case of error.
1435 : */
1436 1 : int bt_obex_get_header_wan_uuid(struct net_buf *buf, uint16_t *len, const uint8_t **uuid);
1437 :
1438 : /** @brief Get header value: oBEX Object class of object.
1439 : *
1440 : * @param buf Buffer needs to be sent.
1441 : * @param len Length of oject class.
1442 : * @param obj_class Class of object.
1443 : *
1444 : * @return 0 in case of success or negative value in case of error.
1445 : */
1446 1 : int bt_obex_get_header_obj_class(struct net_buf *buf, uint16_t *len, const uint8_t **obj_class);
1447 :
1448 : /** @brief Get header value: parameters used in session commands/responses.
1449 : *
1450 : * @param buf Buffer needs to be sent.
1451 : * @param len Length of session parameter.
1452 : * @param session_param Session parameter.
1453 : *
1454 : * @return 0 in case of success or negative value in case of error.
1455 : */
1456 1 : int bt_obex_get_header_session_param(struct net_buf *buf, uint16_t *len,
1457 : const uint8_t **session_param);
1458 :
1459 : /** @brief Get header value: sequence number used in each OBEX packet for reliability.
1460 : *
1461 : * @param buf Buffer needs to be sent.
1462 : * @param session_seq_number Session sequence parameter.
1463 : *
1464 : * @return 0 in case of success or negative value in case of error.
1465 : */
1466 1 : int bt_obex_get_header_session_seq_number(struct net_buf *buf, uint32_t *session_seq_number);
1467 :
1468 : /** @brief Get header value: specifies the action to be performed (used in ACTION operation).
1469 : *
1470 : * @param buf Buffer needs to be sent.
1471 : * @param action_id Action Id @ref bt_obex_action_id.
1472 : *
1473 : * @return 0 in case of success or negative value in case of error.
1474 : */
1475 1 : int bt_obex_get_header_action_id(struct net_buf *buf, uint32_t *action_id);
1476 :
1477 : /** @brief Get header value: the destination object name (used in certain ACTION operations).
1478 : *
1479 : * @param buf Buffer needs to be sent.
1480 : * @param len Length of destination name.
1481 : * @param dest_name Destination name.
1482 : *
1483 : * @return 0 in case of success or negative value in case of error.
1484 : */
1485 1 : int bt_obex_get_header_dest_name(struct net_buf *buf, uint16_t *len, const uint8_t **dest_name);
1486 :
1487 : /** @brief Get header value: 4-byte bit mask for setting permissions.
1488 : *
1489 : * @param buf Buffer needs to be sent.
1490 : * @param perm Permissions.
1491 : *
1492 : * @return 0 in case of success or negative value in case of error.
1493 : */
1494 1 : int bt_obex_get_header_perm(struct net_buf *buf, uint32_t *perm);
1495 :
1496 : /** @brief Get header value: 1-byte value to setup Single Response Mode (SRM).
1497 : *
1498 : * @param buf Buffer needs to be sent.
1499 : * @param srm SRM.
1500 : *
1501 : * @return 0 in case of success or negative value in case of error.
1502 : */
1503 1 : int bt_obex_get_header_srm(struct net_buf *buf, uint8_t *srm);
1504 :
1505 : /** @brief Get header value: Single Response Mode (SRM) Parameter.
1506 : *
1507 : * @param buf Buffer needs to be sent.
1508 : * @param srm_param SRM parameter.
1509 : *
1510 : * @return 0 in case of success or negative value in case of error.
1511 : */
1512 1 : int bt_obex_get_header_srm_param(struct net_buf *buf, uint8_t *srm_param);
1513 :
1514 : #ifdef __cplusplus
1515 : }
1516 : #endif
1517 :
1518 : /**
1519 : * @}
1520 : */
1521 :
1522 : #endif /* ZEPHYR_INCLUDE_BLUETOOTH_OBEX_H_ */
|
