1 /*
2 * Copyright (c) 2020 Nordic Semiconductor ASA
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
7 #ifndef ZEPHYR_INCLUDE_BLUETOOTH_SERVICES_OTS_H_
8 #define ZEPHYR_INCLUDE_BLUETOOTH_SERVICES_OTS_H_
9
10 /**
11 * @brief Object Transfer Service (OTS)
12 * @defgroup bt_ots Object Transfer Service (OTS)
13 * @ingroup bluetooth
14 * @{
15 *
16 * [Experimental] Users should note that the APIs can change
17 * as a part of ongoing development.
18 */
19
20 #ifdef __cplusplus
21 extern "C" {
22 #endif
23
24 #include <zephyr/types.h>
25 #include <sys/byteorder.h>
26 #include <sys/types.h>
27 #include <sys/util.h>
28 #include <bluetooth/conn.h>
29 #include <bluetooth/uuid.h>
30
31 /** @brief Size of OTS object ID (in bytes). */
32 #define BT_OTS_OBJ_ID_SIZE 6
33
34 /** @brief Minimum allowed value for object ID (except ID for directory listing) */
35 #define BT_OTS_OBJ_ID_MIN 0x000000000100
36
37 /** @brief Maximum allowed value for object ID (except ID for directory listing) */
38 #define BT_OTS_OBJ_ID_MAX 0xFFFFFFFFFFFF
39
40 /** @brief ID of the Directory Listing Object */
41 #define OTS_OBJ_ID_DIR_LIST 0x000000000000
42
43 /** @brief Mask for OTS object IDs, preserving the 48 bits */
44 #define BT_OTS_OBJ_ID_MASK BIT64_MASK(48)
45
46 /** @brief Length of OTS object ID string (in bytes). */
47 #define BT_OTS_OBJ_ID_STR_LEN 15
48
49 /** @brief Type of an OTS object. */
50 struct bt_ots_obj_type {
51 union {
52 /* Used to indicate UUID type */
53 struct bt_uuid uuid;
54
55 /* 16-bit UUID value */
56 struct bt_uuid_16 uuid_16;
57
58 /* 128-bit UUID value */
59 struct bt_uuid_128 uuid_128;
60 };
61 };
62
63 /** @brief Properties of an OTS object. */
64 enum {
65 /** Bit 0 Deletion of this object is permitted */
66 BT_OTS_OBJ_PROP_DELETE = 0,
67
68 /** Bit 1 Execution of this object is permitted */
69 BT_OTS_OBJ_PROP_EXECUTE = 1,
70
71 /** Bit 2 Reading this object is permitted */
72 BT_OTS_OBJ_PROP_READ = 2,
73
74 /** Bit 3 Writing data to this object is permitted */
75 BT_OTS_OBJ_PROP_WRITE = 3,
76
77 /** @brief Bit 4 Appending data to this object is permitted.
78 *
79 * Appending data increases its Allocated Size.
80 */
81 BT_OTS_OBJ_PROP_APPEND = 4,
82
83 /** Bit 5 Truncation of this object is permitted */
84 BT_OTS_OBJ_PROP_TRUNCATE = 5,
85
86 /** @brief Bit 6 Patching this object is permitted
87 *
88 * Patching this object overwrites some of
89 * the object's existing contents.
90 */
91 BT_OTS_OBJ_PROP_PATCH = 6,
92
93 /** Bit 7 This object is a marked object */
94 BT_OTS_OBJ_PROP_MARKED = 7,
95 };
96
97 /** @brief Set @ref BT_OTS_OBJ_PROP_DELETE property.
98 *
99 * @param prop Object properties.
100 */
101 #define BT_OTS_OBJ_SET_PROP_DELETE(prop) \
102 WRITE_BIT(prop, BT_OTS_OBJ_PROP_DELETE, 1)
103
104 /** @brief Set @ref BT_OTS_OBJ_PROP_EXECUTE property.
105 *
106 * @param prop Object properties.
107 */
108 #define BT_OTS_OBJ_SET_PROP_EXECUTE(prop) \
109 WRITE_BIT(prop, BT_OTS_OBJ_PROP_EXECUTE, 1)
110
111 /** @brief Set @ref BT_OTS_OBJ_PROP_READ property.
112 *
113 * @param prop Object properties.
114 */
115 #define BT_OTS_OBJ_SET_PROP_READ(prop) \
116 WRITE_BIT(prop, BT_OTS_OBJ_PROP_READ, 1)
117
118 /** @brief Set @ref BT_OTS_OBJ_PROP_WRITE property.
119 *
120 * @param prop Object properties.
121 */
122 #define BT_OTS_OBJ_SET_PROP_WRITE(prop) \
123 WRITE_BIT(prop, BT_OTS_OBJ_PROP_WRITE, 1)
124
125 /** @brief Set @ref BT_OTS_OBJ_PROP_APPEND property.
126 *
127 * @param prop Object properties.
128 */
129 #define BT_OTS_OBJ_SET_PROP_APPEND(prop) \
130 WRITE_BIT(prop, BT_OTS_OBJ_PROP_APPEND, 1)
131
132 /** @brief Set @ref BT_OTS_OBJ_PROP_TRUNCATE property.
133 *
134 * @param prop Object properties.
135 */
136 #define BT_OTS_OBJ_SET_PROP_TRUNCATE(prop) \
137 WRITE_BIT(prop, BT_OTS_OBJ_PROP_TRUNCATE, 1)
138
139 /** @brief Set @ref BT_OTS_OBJ_PROP_PATCH property.
140 *
141 * @param prop Object properties.
142 */
143 #define BT_OTS_OBJ_SET_PROP_PATCH(prop) \
144 WRITE_BIT(prop, BT_OTS_OBJ_PROP_PATCH, 1)
145
146 /** @brief Set @ref BT_OTS_OBJ_SET_PROP_MARKED property.
147 *
148 * @param prop Object properties.
149 */
150 #define BT_OTS_OBJ_SET_PROP_MARKED(prop) \
151 WRITE_BIT(prop, BT_OTS_OBJ_PROP_MARKED, 1)
152
153 /** @brief Get @ref BT_OTS_OBJ_PROP_DELETE property.
154 *
155 * @param prop Object properties.
156 */
157 #define BT_OTS_OBJ_GET_PROP_DELETE(prop) \
158 ((prop) & BIT(BT_OTS_OBJ_PROP_DELETE))
159
160 /** @brief Get @ref BT_OTS_OBJ_PROP_EXECUTE property.
161 *
162 * @param prop Object properties.
163 */
164 #define BT_OTS_OBJ_GET_PROP_EXECUTE(prop) \
165 ((prop) & BIT(BT_OTS_OBJ_PROP_EXECUTE))
166
167 /** @brief Get @ref BT_OTS_OBJ_PROP_READ property.
168 *
169 * @param prop Object properties.
170 */
171 #define BT_OTS_OBJ_GET_PROP_READ(prop) \
172 ((prop) & BIT(BT_OTS_OBJ_PROP_READ))
173
174 /** @brief Get @ref BT_OTS_OBJ_PROP_WRITE property.
175 *
176 * @param prop Object properties.
177 */
178 #define BT_OTS_OBJ_GET_PROP_WRITE(prop) \
179 ((prop) & BIT(BT_OTS_OBJ_PROP_WRITE))
180
181 /** @brief Get @ref BT_OTS_OBJ_PROP_APPEND property.
182 *
183 * @param prop Object properties.
184 */
185 #define BT_OTS_OBJ_GET_PROP_APPEND(prop) \
186 ((prop) & BIT(BT_OTS_OBJ_PROP_APPEND))
187
188 /** @brief Get @ref BT_OTS_OBJ_PROP_TRUNCATE property.
189 *
190 * @param prop Object properties.
191 */
192 #define BT_OTS_OBJ_GET_PROP_TRUNCATE(prop) \
193 ((prop) & BIT(BT_OTS_OBJ_PROP_TRUNCATE))
194
195 /** @brief Get @ref BT_OTS_OBJ_PROP_PATCH property.
196 *
197 * @param prop Object properties.
198 */
199 #define BT_OTS_OBJ_GET_PROP_PATCH(prop) \
200 ((prop) & BIT(BT_OTS_OBJ_PROP_PATCH))
201
202 /** @brief Get @ref BT_OTS_OBJ_PROP_MARKED property.
203 *
204 * @param prop Object properties.
205 */
206 #define BT_OTS_OBJ_GET_PROP_MARKED(prop) \
207 ((prop) & BIT(BT_OTS_OBJ_PROP_MARKED))
208
209 /** @brief Descriptor for OTS Object Size parameter. */
210 struct bt_ots_obj_size {
211 /* Current Size */
212 uint32_t cur;
213
214 /* Allocated Size */
215 uint32_t alloc;
216 } __packed;
217
218 /** @brief Descriptor for OTS object initialization. */
219 struct bt_ots_obj_metadata {
220 /* Object Name */
221 char *name;
222
223 /* Object Type */
224 struct bt_ots_obj_type type;
225
226 /* Object Size */
227 struct bt_ots_obj_size size;
228
229 /* Object Properties */
230 uint32_t props;
231 };
232
233 /** @brief Object Action Control Point Feature bits. */
234 enum {
235 /** Bit 0 OACP Create Op Code Supported */
236 BT_OTS_OACP_FEAT_CREATE = 0,
237
238 /** Bit 1 OACP Delete Op Code Supported */
239 BT_OTS_OACP_FEAT_DELETE = 1,
240
241 /** Bit 2 OACP Calculate Checksum Op Code Supported */
242 BT_OTS_OACP_FEAT_CHECKSUM = 2,
243
244 /** Bit 3 OACP Execute Op Code Supported */
245 BT_OTS_OACP_FEAT_EXECUTE = 3,
246
247 /** Bit 4 OACP Read Op Code Supported */
248 BT_OTS_OACP_FEAT_READ = 4,
249
250 /** Bit 5 OACP Write Op Code Supported */
251 BT_OTS_OACP_FEAT_WRITE = 5,
252
253 /** Bit 6 Appending Additional Data to Objects Supported */
254 BT_OTS_OACP_FEAT_APPEND = 6,
255
256 /** Bit 7 Truncation of Objects Supported */
257 BT_OTS_OACP_FEAT_TRUNCATE = 7,
258
259 /** Bit 8 Patching of Objects Supported */
260 BT_OTS_OACP_FEAT_PATCH = 8,
261
262 /** Bit 9 OACP Abort Op Code Supported */
263 BT_OTS_OACP_FEAT_ABORT = 9,
264 };
265
266 /** @brief Set @ref BT_OTS_OACP_SET_FEAT_CREATE feature.
267 *
268 * @param feat OTS features.
269 */
270 #define BT_OTS_OACP_SET_FEAT_CREATE(feat) \
271 WRITE_BIT(feat, BT_OTS_OACP_FEAT_CREATE, 1)
272
273 /** @brief Set @ref BT_OTS_OACP_FEAT_DELETE feature.
274 *
275 * @param feat OTS features.
276 */
277 #define BT_OTS_OACP_SET_FEAT_DELETE(feat) \
278 WRITE_BIT(feat, BT_OTS_OACP_FEAT_DELETE, 1)
279
280 /** @brief Set @ref BT_OTS_OACP_FEAT_CHECKSUM feature.
281 *
282 * @param feat OTS features.
283 */
284 #define BT_OTS_OACP_SET_FEAT_CHECKSUM(feat) \
285 WRITE_BIT(feat, BT_OTS_OACP_FEAT_CHECKSUM, 1)
286
287 /** @brief Set @ref BT_OTS_OACP_FEAT_EXECUTE feature.
288 *
289 * @param feat OTS features.
290 */
291 #define BT_OTS_OACP_SET_FEAT_EXECUTE(feat) \
292 WRITE_BIT(feat, BT_OTS_OACP_FEAT_EXECUTE, 1)
293
294 /** @brief Set @ref BT_OTS_OACP_FEAT_READ feature.
295 *
296 * @param feat OTS features.
297 */
298 #define BT_OTS_OACP_SET_FEAT_READ(feat) \
299 WRITE_BIT(feat, BT_OTS_OACP_FEAT_READ, 1)
300
301 /** @brief Set @ref BT_OTS_OACP_FEAT_WRITE feature.
302 *
303 * @param feat OTS features.
304 */
305 #define BT_OTS_OACP_SET_FEAT_WRITE(feat) \
306 WRITE_BIT(feat, BT_OTS_OACP_FEAT_WRITE, 1)
307
308 /** @brief Set @ref BT_OTS_OACP_FEAT_APPEND feature.
309 *
310 * @param feat OTS features.
311 */
312 #define BT_OTS_OACP_SET_FEAT_APPEND(feat) \
313 WRITE_BIT(feat, BT_OTS_OACP_FEAT_APPEND, 1)
314
315 /** @brief Set @ref BT_OTS_OACP_FEAT_TRUNCATE feature.
316 *
317 * @param feat OTS features.
318 */
319 #define BT_OTS_OACP_SET_FEAT_TRUNCATE(feat) \
320 WRITE_BIT(feat, BT_OTS_OACP_FEAT_TRUNCATE, 1)
321
322 /** @brief Set @ref BT_OTS_OACP_FEAT_PATCH feature.
323 *
324 * @param feat OTS features.
325 */
326 #define BT_OTS_OACP_SET_FEAT_PATCH(feat) \
327 WRITE_BIT(feat, BT_OTS_OACP_FEAT_PATCH, 1)
328
329 /** @brief Set @ref BT_OTS_OACP_FEAT_ABORT feature.
330 *
331 * @param feat OTS features.
332 */
333 #define BT_OTS_OACP_SET_FEAT_ABORT(feat) \
334 WRITE_BIT(feat, BT_OTS_OACP_FEAT_ABORT, 1)
335
336 /** @brief Get @ref BT_OTS_OACP_FEAT_CREATE feature.
337 *
338 * @param feat OTS features.
339 */
340 #define BT_OTS_OACP_GET_FEAT_CREATE(feat) \
341 ((feat) & BIT(BT_OTS_OACP_FEAT_CREATE))
342
343 /** @brief Get @ref BT_OTS_OACP_FEAT_DELETE feature.
344 *
345 * @param feat OTS features.
346 */
347 #define BT_OTS_OACP_GET_FEAT_DELETE(feat) \
348 ((feat) & BIT(BT_OTS_OACP_FEAT_DELETE))
349
350 /** @brief Get @ref BT_OTS_OACP_FEAT_CHECKSUM feature.
351 *
352 * @param feat OTS features.
353 */
354 #define BT_OTS_OACP_GET_FEAT_CHECKSUM(feat) \
355 ((feat) & BIT(BT_OTS_OACP_FEAT_CHECKSUM))
356
357 /** @brief Get @ref BT_OTS_OACP_FEAT_EXECUTE feature.
358 *
359 * @param feat OTS features.
360 */
361 #define BT_OTS_OACP_GET_FEAT_EXECUTE(feat) \
362 ((feat) & BIT(BT_OTS_OACP_FEAT_EXECUTE))
363
364 /** @brief Get @ref BT_OTS_OACP_FEAT_READ feature.
365 *
366 * @param feat OTS features.
367 */
368 #define BT_OTS_OACP_GET_FEAT_READ(feat) \
369 ((feat) & BIT(BT_OTS_OACP_FEAT_READ))
370
371 /** @brief Get @ref BT_OTS_OACP_FEAT_WRITE feature.
372 *
373 * @param feat OTS features.
374 */
375 #define BT_OTS_OACP_GET_FEAT_WRITE(feat) \
376 ((feat) & BIT(BT_OTS_OACP_FEAT_WRITE))
377
378 /** @brief Get @ref BT_OTS_OACP_FEAT_APPEND feature.
379 *
380 * @param feat OTS features.
381 */
382 #define BT_OTS_OACP_GET_FEAT_APPEND(feat) \
383 ((feat) & BIT(BT_OTS_OACP_FEAT_APPEND))
384
385 /** @brief Get @ref BT_OTS_OACP_FEAT_TRUNCATE feature.
386 *
387 * @param feat OTS features.
388 */
389 #define BT_OTS_OACP_GET_FEAT_TRUNCATE(feat) \
390 ((feat) & BIT(BT_OTS_OACP_FEAT_TRUNCATE))
391
392 /** @brief Get @ref BT_OTS_OACP_FEAT_PATCH feature.
393 *
394 * @param feat OTS features.
395 */
396 #define BT_OTS_OACP_GET_FEAT_PATCH(feat) \
397 ((feat) & BIT(BT_OTS_OACP_FEAT_PATCH))
398
399 /** @brief Get @ref BT_OTS_OACP_FEAT_ABORT feature.
400 *
401 * @param feat OTS features.
402 */
403 #define BT_OTS_OACP_GET_FEAT_ABORT(feat) \
404 ((feat) & BIT(BT_OTS_OACP_FEAT_ABORT))
405
406 /** @brief Object List Control Point Feature bits. */
407 enum {
408 /** Bit 0 OLCP Go To Op Code Supported */
409 BT_OTS_OLCP_FEAT_GO_TO = 0,
410
411 /** Bit 1 OLCP Order Op Code Supported */
412 BT_OTS_OLCP_FEAT_ORDER = 1,
413
414 /** Bit 2 OLCP Request Number of Objects Op Code Supported */
415 BT_OTS_OLCP_FEAT_NUM_REQ = 2,
416
417 /** Bit 3 OLCP Clear Marking Op Code Supported*/
418 BT_OTS_OLCP_FEAT_CLEAR = 3,
419 };
420
421 /** @brief Set @ref BT_OTS_OLCP_FEAT_GO_TO feature.
422 *
423 * @param feat OTS features.
424 */
425 #define BT_OTS_OLCP_SET_FEAT_GO_TO(feat) \
426 WRITE_BIT(feat, BT_OTS_OLCP_FEAT_GO_TO, 1)
427
428 /** @brief Set @ref BT_OTS_OLCP_FEAT_ORDER feature.
429 *
430 * @param feat OTS features.
431 */
432 #define BT_OTS_OLCP_SET_FEAT_ORDER(feat) \
433 WRITE_BIT(feat, BT_OTS_OLCP_FEAT_ORDER, 1)
434
435 /** @brief Set @ref BT_OTS_OLCP_FEAT_NUM_REQ feature.
436 *
437 * @param feat OTS features.
438 */
439 #define BT_OTS_OLCP_SET_FEAT_NUM_REQ(feat) \
440 WRITE_BIT(feat, BT_OTS_OLCP_FEAT_NUM_REQ, 1)
441
442 /** @brief Set @ref BT_OTS_OLCP_FEAT_CLEAR feature.
443 *
444 * @param feat OTS features.
445 */
446 #define BT_OTS_OLCP_SET_FEAT_CLEAR(feat) \
447 WRITE_BIT(feat, BT_OTS_OLCP_FEAT_CLEAR, 1)
448
449 /** @brief Get @ref BT_OTS_OLCP_GET_FEAT_GO_TO feature.
450 *
451 * @param feat OTS features.
452 */
453 #define BT_OTS_OLCP_GET_FEAT_GO_TO(feat) \
454 ((feat) & BIT(BT_OTS_OLCP_FEAT_GO_TO))
455
456 /** @brief Get @ref BT_OTS_OLCP_GET_FEAT_ORDER feature.
457 *
458 * @param feat OTS features.
459 */
460 #define BT_OTS_OLCP_GET_FEAT_ORDER(feat) \
461 ((feat) & BIT(BT_OTS_OLCP_FEAT_ORDER))
462
463 /** @brief Get @ref BT_OTS_OLCP_GET_FEAT_NUM_REQ feature.
464 *
465 * @param feat OTS features.
466 */
467 #define BT_OTS_OLCP_GET_FEAT_NUM_REQ(feat) \
468 ((feat) & BIT(BT_OTS_OLCP_FEAT_NUM_REQ))
469
470 /** @brief Get @ref BT_OTS_OLCP_GET_FEAT_CLEAR feature.
471 *
472 * @param feat OTS features.
473 */
474 #define BT_OTS_OLCP_GET_FEAT_CLEAR(feat) \
475 ((feat) & BIT(BT_OTS_OLCP_FEAT_CLEAR))
476
477 /**@brief Features of the OTS. */
478 struct bt_ots_feat {
479 /* OACP Features */
480 uint32_t oacp;
481
482 /* OLCP Features */
483 uint32_t olcp;
484 } __packed;
485
486 /** @brief Opaque OTS instance. */
487 struct bt_ots;
488
489 /** @brief OTS callback structure. */
490 struct bt_ots_cb {
491 /** @brief Object created callback
492 *
493 * This callback is called whenever a new object is created.
494 * Application can reject this request by returning an error
495 * when it does not have necessary resources to hold this new
496 * object. This callback is also triggered when the server
497 * creates a new object with bt_ots_obj_add() API.
498 *
499 * @param ots OTS instance.
500 * @param conn The connection that is requesting object creation or
501 * NULL if object is created by the following function:
502 * bt_ots_obj_add().
503 * @param id Object ID.
504 * @param init Object initialization metadata.
505 *
506 * @return 0 in case of success or negative value in case of error.
507 * Possible return values:
508 * -ENOMEM if no available space for new object.
509 */
510 int (*obj_created)(struct bt_ots *ots, struct bt_conn *conn,
511 uint64_t id,
512 const struct bt_ots_obj_metadata *init);
513
514 /** @brief Object deleted callback
515 *
516 * This callback is called whenever an object is deleted. It is
517 * also triggered when the server deletes an object with
518 * bt_ots_obj_delete() API.
519 *
520 * @param ots OTS instance.
521 * @param conn The connection that deleted the object or NULL if
522 * this request came from the server.
523 * @param id Object ID.
524 */
525 void (*obj_deleted)(struct bt_ots *ots, struct bt_conn *conn,
526 uint64_t id);
527
528 /** @brief Object selected callback
529 *
530 * This callback is called on successful object selection.
531 *
532 * @param ots OTS instance.
533 * @param conn The connection that selected new object.
534 * @param id Object ID.
535 */
536 void (*obj_selected)(struct bt_ots *ots, struct bt_conn *conn,
537 uint64_t id);
538
539 /** @brief Object read callback
540 *
541 * This callback is called multiple times during the Object read
542 * operation. OTS module will keep requesting successive Object
543 * fragments from the application until the read operation is
544 * completed. The end of read operation is indicated by NULL data
545 * parameter.
546 *
547 * @param ots OTS instance.
548 * @param conn The connection that read object.
549 * @param id Object ID.
550 * @param data In: NULL once the read operations is completed.
551 * Out: Next chunk of data to be sent.
552 * @param len Remaining length requested by the client.
553 * @param offset Object data offset.
554 *
555 * @return Data length to be sent via data parameter. This value
556 * shall be smaller or equal to the len parameter.
557 * @return Negative value in case of an error.
558 */
559 ssize_t (*obj_read)(struct bt_ots *ots, struct bt_conn *conn,
560 uint64_t id, void **data, size_t len,
561 off_t offset);
562
563 /** @brief Object write callback
564 *
565 * This callback is called multiple times during the Object write
566 * operation. OTS module will keep providing successive Object
567 * fragments to the application until the write operation is
568 * completed. The offset and length of each write fragment is
569 * validated by the OTS module to be within the allocated size
570 * of the object. The remaining length indicates data length
571 * remaining to be written and will decrease each write iteration
572 * until it reaches 0 in the last write fragment.
573 *
574 * @param ots OTS instance.
575 * @param conn The connection that wrote object.
576 * @param id Object ID.
577 * @param data Next chunk of data to be written.
578 * @param len Length of the current chunk of data in the buffer.
579 * @param offset Object data offset.
580 * @param rem Remaining length in the write operation.
581 *
582 * @return Number of bytes written in case of success, if the number
583 * of bytes written does not match len, -EIO is returned to
584 * the L2CAP layer.
585 * @return A negative value in case of an error.
586 * @return -EINPROGRESS has a special meaning and is unsupported at
587 * the moment. It should not be returned.
588 */
589 ssize_t (*obj_write)(struct bt_ots *ots, struct bt_conn *conn, uint64_t id,
590 const void *data, size_t len, off_t offset,
591 size_t rem);
592
593 /** @brief Object name written callback
594 *
595 * This callback is called when the object name is written.
596 * This is a notification to the application that the object name
597 * has been updated by the OTS service implementation.
598 *
599 * @param ots OTS instance.
600 * @param conn The connection that wrote object name.
601 * @param id Object ID.
602 * @param name Object name.
603 */
604 void (*obj_name_written)(struct bt_ots *ots, struct bt_conn *conn,
605 uint64_t id, const char *name);
606 };
607
608 /** @brief Descriptor for OTS initialization. */
609 struct bt_ots_init {
610 /* OTS features */
611 struct bt_ots_feat features;
612
613 /* Callbacks */
614 struct bt_ots_cb *cb;
615 };
616
617 /** @brief Add an object to the OTS instance.
618 *
619 * This function adds an object to the OTS database. When the
620 * object is being added, a callback obj_created() is called
621 * to notify the user about a new object ID.
622 *
623 * @param ots OTS instance.
624 * @param obj_init Meta data of the object.
625 *
626 * @return 0 in case of success or negative value in case of error.
627 */
628 int bt_ots_obj_add(struct bt_ots *ots, struct bt_ots_obj_metadata *obj_init);
629
630 /** @brief Delete an object from the OTS instance.
631 *
632 * This function deletes an object from the OTS database. When the
633 * object is deleted a callback obj_deleted() is called
634 * to notify the user about this event. At this point, it is possible
635 * to free allocated buffer for object data.
636 *
637 * @param ots OTS instance.
638 * @param id ID of the object to be deleted (uint48).
639 *
640 * @return 0 in case of success or negative value in case of error.
641 */
642 int bt_ots_obj_delete(struct bt_ots *ots, uint64_t id);
643
644 /** @brief Get the service declaration attribute.
645 *
646 * This function is enabled for CONFIG_BT_OTS_SECONDARY_SVC configuration.
647 * The first service attribute can be included in any other GATT service.
648 *
649 * @param ots OTS instance.
650 *
651 * @return The first OTS attribute instance.
652 */
653 void *bt_ots_svc_decl_get(struct bt_ots *ots);
654
655 /** @brief Initialize the OTS instance.
656 *
657 * @param ots OTS instance.
658 * @param ots_init OTS initialization descriptor.
659 *
660 * @return 0 in case of success or negative value in case of error.
661 */
662 int bt_ots_init(struct bt_ots *ots, struct bt_ots_init *ots_init);
663
664 /** @brief Get a free instance of OTS from the pool.
665 *
666 * @return OTS instance in case of success or NULL in case of error.
667 */
668 struct bt_ots *bt_ots_free_instance_get(void);
669
670 /** @brief Converts binary OTS Object ID to string.
671 *
672 * @param obj_id Object ID.
673 * @param str Address of user buffer with enough room to store
674 * formatted string containing binary Object ID.
675 * @param len Length of data to be copied to user string buffer.
676 * Refer to BT_OTS_OBJ_ID_STR_LEN about
677 * recommended value.
678 *
679 * @return Number of successfully formatted bytes from binary ID.
680 */
bt_ots_obj_id_to_str(uint64_t obj_id,char * str,size_t len)681 static inline int bt_ots_obj_id_to_str(uint64_t obj_id, char *str, size_t len)
682 {
683 uint8_t id[6];
684
685 sys_put_le48(obj_id, id);
686
687 return snprintk(str, len, "0x%02X%02X%02X%02X%02X%02X",
688 id[5], id[4], id[3], id[2], id[1], id[0]);
689 }
690
691 #ifdef __cplusplus
692 }
693 #endif
694
695 /**
696 * @}
697 */
698
699 #endif /* ZEPHYR_INCLUDE_BLUETOOTH_SERVICES_OTS_H_ */
700
