ndef_utils.h revision e9df6ba5a8fcccf306a80b1670b423be8fe7746a 
1/******************************************************************************
2 *
3 *  Copyright (C) 2010-2012 Broadcom Corporation
4 *
5 *  Licensed under the Apache License, Version 2.0 (the "License");
6 *  you may not use this file except in compliance with the License.
7 *  You may obtain a copy of the License at:
8 *
9 *  http://www.apache.org/licenses/LICENSE-2.0
10 *
11 *  Unless required by applicable law or agreed to in writing, software
12 *  distributed under the License is distributed on an "AS IS" BASIS,
13 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 *  See the License for the specific language governing permissions and
15 *  limitations under the License.
16 *
17 ******************************************************************************/
18
19/******************************************************************************
20 *
21 *  This file contains definitions for some utility functions to help parse
22 *  and build NFC Data Exchange Format (NDEF) messages
23 *
24 ******************************************************************************/
25
26#ifndef NDEF_UTILS_H
27#define NDEF_UTILS_H
28
29#include "bt_types.h"
30
31#define NDEF_MB_MASK            0x80    /* Message Begin */
32#define NDEF_ME_MASK            0x40    /* Message End */
33#define NDEF_CF_MASK            0x20    /* Chunk Flag */
34#define NDEF_SR_MASK            0x10    /* Short Record */
35#define NDEF_IL_MASK            0x08    /* ID Length */
36#define NDEF_TNF_MASK           0x07    /* Type Name Format */
37
38/* NDEF Type Name Format */
39#define NDEF_TNF_EMPTY          0   /* Empty (type/id/payload len =0) */
40#define NDEF_TNF_WKT            1   /* NFC Forum well-known type/RTD */
41#define NDEF_TNF_MEDIA          2   /* Media-type as defined in RFC 2046 */
42#define NDEF_TNF_URI            3   /* Absolute URI as defined in RFC 3986 */
43#define NDEF_TNF_EXT            4   /* NFC Forum external type/RTD */
44#define NDEF_TNF_UNKNOWN        5   /* Unknown (type len =0) */
45#define NDEF_TNF_UNCHANGED      6   /* Unchanged (type len =0) */
46#define NDEF_TNF_RESERVED       7   /* Reserved */
47
48/* Define the status code returned from the Validate, Parse or Build functions
49*/
50enum
51{
52    NDEF_OK,                            /* 0 - OK                                   */
53
54    NDEF_REC_NOT_FOUND,                 /* 1 - No record matching the find criteria */
55    NDEF_MSG_TOO_SHORT,                 /* 2 - Message was too short (< 3 bytes)    */
56    NDEF_MSG_NO_MSG_BEGIN,              /* 3 - No 'begin' flag at start of message  */
57    NDEF_MSG_NO_MSG_END,                /* 4 - No 'end' flag at end of message      */
58    NDEF_MSG_EXTRA_MSG_BEGIN,           /* 5 - 'begin' flag after start of message  */
59    NDEF_MSG_UNEXPECTED_CHUNK,          /* 6 - Unexpected chunk found               */
60    NDEF_MSG_INVALID_EMPTY_REC,         /* 7 - Empty record with non-zero contents  */
61    NDEF_MSG_INVALID_CHUNK,             /* 8 - Invalid chunk found                  */
62    NDEF_MSG_LENGTH_MISMATCH,           /* 9 - Overall message length doesn't match */
63    NDEF_MSG_INSUFFICIENT_MEM           /* 10 - Insuffiecient memory to add record  */
64};
65typedef UINT8 tNDEF_STATUS;
66
67
68#define HR_REC_TYPE_LEN     2       /* Handover Request Record Type     */
69#define HS_REC_TYPE_LEN     2       /* Handover Select Record Type      */
70#define HC_REC_TYPE_LEN     2       /* Handover Carrier recrod Type     */
71#define CR_REC_TYPE_LEN     2       /* Collision Resolution Record Type */
72#define AC_REC_TYPE_LEN     2       /* Alternative Carrier Record Type  */
73#define ERR_REC_TYPE_LEN    3       /* Error Record Type                */
74#define BT_OOB_REC_TYPE_LEN 32      /* Bluetooth OOB Data Type          */
75
76
77#ifdef __cplusplus
78extern "C" {
79#endif
80
81/* Define prefix for exporting APIs from libraries */
82#ifdef  NFC_DLL
83#define EXPORT_NDEF_API __declspec(dllexport)       /* Windows DLL export prefix */
84#else
85#define EXPORT_NDEF_API
86#endif
87
88/* Functions to parse a received NDEF Message
89*/
90/*******************************************************************************
91**
92** Function         NDEF_MsgValidate
93**
94** Description      This function validates an NDEF message.
95**
96** Returns          TRUE if all OK, or FALSE if the message is invalid.
97**
98*******************************************************************************/
99EXPORT_NDEF_API extern tNDEF_STATUS NDEF_MsgValidate (UINT8 *p_msg, UINT32 msg_len, BOOLEAN b_allow_chunks);
100
101/*******************************************************************************
102**
103** Function         NDEF_MsgGetNumRecs
104**
105** Description      This function gets the number of records in the given NDEF
106**                  message.
107**
108** Returns          The record count, or 0 if the message is invalid.
109**
110*******************************************************************************/
111EXPORT_NDEF_API extern INT32 NDEF_MsgGetNumRecs (UINT8 *p_msg);
112
113/*******************************************************************************
114**
115** Function         NDEF_MsgGetRecLength
116**
117** Description      This function returns length of the current record in the given
118**                  NDEF message.
119**
120** Returns          Length of record
121**
122*******************************************************************************/
123EXPORT_NDEF_API extern UINT32 NDEF_MsgGetRecLength (UINT8 *p_cur_rec);
124
125/*******************************************************************************
126**
127** Function         NDEF_MsgGetNextRec
128**
129** Description      This function gets a pointer to the next record after the
130**                  current one.
131**
132** Returns          Pointer to the start of the record, or NULL if no more
133**
134*******************************************************************************/
135EXPORT_NDEF_API extern UINT8 *NDEF_MsgGetNextRec (UINT8 *p_cur_rec);
136
137/*******************************************************************************
138**
139** Function         NDEF_MsgGetRecByIndex
140**
141** Description      This function gets a pointer to the record with the given
142**                  index (0-based index) in the given NDEF message.
143**
144** Returns          Pointer to the start of the record, or NULL
145**
146*******************************************************************************/
147EXPORT_NDEF_API extern UINT8 *NDEF_MsgGetRecByIndex (UINT8 *p_msg, INT32 index);
148
149/*******************************************************************************
150**
151** Function         NDEF_MsgGetLastRecInMsg
152**
153** Description      This function gets a pointer to the last record in the
154**                  given NDEF message.
155**
156** Returns          Pointer to the start of the last record, or NULL if some problem
157**
158*******************************************************************************/
159EXPORT_NDEF_API extern UINT8 *NDEF_MsgGetLastRecInMsg (UINT8 *p_msg);
160
161/*******************************************************************************
162**
163** Function         NDEF_MsgGetFirstRecByType
164**
165** Description      This function gets a pointer to the first record with the given
166**                  record type in the given NDEF message.
167**
168** Returns          Pointer to the start of the record, or NULL
169**
170*******************************************************************************/
171EXPORT_NDEF_API extern UINT8 *NDEF_MsgGetFirstRecByType (UINT8 *p_msg, UINT8 tnf, UINT8 *p_type, UINT8 tlen);
172
173/*******************************************************************************
174**
175** Function         NDEF_MsgGetNextRecByType
176**
177** Description      This function gets a pointer to the next record with the given
178**                  record type in the given NDEF message.
179**
180** Returns          Pointer to the start of the record, or NULL
181**
182*******************************************************************************/
183EXPORT_NDEF_API extern UINT8 *NDEF_MsgGetNextRecByType (UINT8 *p_cur_rec, UINT8 tnf, UINT8 *p_type, UINT8 tlen);
184
185/*******************************************************************************
186**
187** Function         NDEF_MsgGetFirstRecById
188**
189** Description      This function gets a pointer to the first record with the given
190**                  record id in the given NDEF message.
191**
192** Returns          Pointer to the start of the record, or NULL
193**
194*******************************************************************************/
195EXPORT_NDEF_API extern UINT8 *NDEF_MsgGetFirstRecById (UINT8 *p_msg, UINT8 *p_id, UINT8 ilen);
196
197/*******************************************************************************
198**
199** Function         NDEF_MsgGetNextRecById
200**
201** Description      This function gets a pointer to the next record with the given
202**                  record id in the given NDEF message.
203**
204** Returns          Pointer to the start of the record, or NULL
205**
206*******************************************************************************/
207EXPORT_NDEF_API extern UINT8 *NDEF_MsgGetNextRecById (UINT8 *p_cur_rec, UINT8 *p_id, UINT8 ilen);
208
209/*******************************************************************************
210**
211** Function         NDEF_RecGetType
212**
213** Description      This function gets a pointer to the record type for the given NDEF record.
214**
215** Returns          Pointer to Type (NULL if none). TNF and len are filled in.
216**
217*******************************************************************************/
218EXPORT_NDEF_API extern UINT8 *NDEF_RecGetType (UINT8 *p_rec, UINT8 *p_tnf, UINT8 *p_type_len);
219
220/*******************************************************************************
221**
222** Function         NDEF_RecGetId
223**
224** Description      This function gets a pointer to the record id for the given NDEF record.
225**
226** Returns          Pointer to Id (NULL if none). ID Len is filled in.
227**
228*******************************************************************************/
229EXPORT_NDEF_API extern UINT8 *NDEF_RecGetId (UINT8 *p_rec, UINT8 *p_id_len);
230
231/*******************************************************************************
232**
233** Function         NDEF_RecGetPayload
234**
235** Description      This function gets a pointer to the payload for the given NDEF record.
236**
237** Returns          a pointer to the payload (NULL if none). Payload len filled in.
238**
239*******************************************************************************/
240EXPORT_NDEF_API extern UINT8 *NDEF_RecGetPayload (UINT8 *p_rec, UINT32 *p_payload_len);
241
242
243/* Functions to build an NDEF Message
244*/
245/*******************************************************************************
246**
247** Function         NDEF_MsgInit
248**
249** Description      This function initializes an NDEF message.
250**
251** Returns          void
252**                  *p_cur_size is initialized to 0
253**
254*******************************************************************************/
255EXPORT_NDEF_API extern void NDEF_MsgInit (UINT8 *p_msg, UINT32 max_size, UINT32 *p_cur_size);
256
257/*******************************************************************************
258**
259** Function         NDEF_MsgAddRec
260**
261** Description      This function adds an NDEF record to the end of an NDEF message.
262**
263** Returns          OK, or error if the record did not fit
264**                  *p_cur_size is updated
265**
266*******************************************************************************/
267EXPORT_NDEF_API extern tNDEF_STATUS  NDEF_MsgAddRec (UINT8 *p_msg, UINT32 max_size, UINT32 *p_cur_size,
268                                     UINT8 tnf, UINT8 *p_type, UINT8 type_len,
269                                     UINT8 *p_id, UINT8  id_len,
270                                     UINT8 *p_payload, UINT32 payload_len);
271
272/*******************************************************************************
273**
274** Function         NDEF_MsgInsertRec
275**
276** Description      This function inserts a record at a specific index into the
277**                  given NDEF message
278**
279** Returns          OK, or error if the record did not fit
280**                  *p_cur_size is updated
281**
282*******************************************************************************/
283EXPORT_NDEF_API extern tNDEF_STATUS  NDEF_MsgInsertRec (UINT8 *p_msg, UINT32 max_size, UINT32 *p_cur_size, INT32 index,
284                                        UINT8 tnf, UINT8 *p_type, UINT8 type_len,
285                                        UINT8 *p_id, UINT8  id_len,
286                                        UINT8 *p_payload, UINT32 payload_len);
287
288/*******************************************************************************
289**
290** Function         NDEF_MsgAppendRec
291**
292** Description      This function adds NDEF records to the end of an NDEF message.
293**
294** Returns          OK, or error if the record did not fit
295**                  *p_cur_size is updated
296**
297*******************************************************************************/
298EXPORT_NDEF_API extern tNDEF_STATUS  NDEF_MsgAppendRec (UINT8 *p_msg, UINT32 max_size, UINT32 *p_cur_size,
299                                        UINT8 *p_new_rec, UINT32 new_rec_len);
300
301/*******************************************************************************
302**
303** Function         NDEF_MsgAppendPayload
304**
305** Description      This function appends extra payload to a specific record in the
306**                  given NDEF message
307**
308** Returns          OK, or error if the extra payload did not fit
309**                  *p_cur_size is updated
310**
311*******************************************************************************/
312EXPORT_NDEF_API extern tNDEF_STATUS NDEF_MsgAppendPayload (UINT8 *p_msg, UINT32 max_size, UINT32 *p_cur_size,
313                                           UINT8 *p_rec, UINT8 *p_add_pl, UINT32 add_pl_len);
314
315/*******************************************************************************
316**
317** Function         NDEF_MsgReplacePayload
318**
319** Description      This function replaces the payload of a specific record in the
320**                  given NDEF message
321**
322** Returns          OK, or error if the new payload did not fit
323**                  *p_cur_size is updated
324**
325*******************************************************************************/
326EXPORT_NDEF_API extern tNDEF_STATUS NDEF_MsgReplacePayload (UINT8 *p_msg, UINT32 max_size, UINT32 *p_cur_size,
327                                            UINT8 *p_rec, UINT8 *p_new_pl, UINT32 new_pl_len);
328
329/*******************************************************************************
330**
331** Function         NDEF_MsgReplaceType
332**
333** Description      This function replaces the type field of a specific record in the
334**                  given NDEF message
335**
336** Returns          OK, or error if the new type field did not fit
337**                  *p_cur_size is updated
338**
339*******************************************************************************/
340EXPORT_NDEF_API extern tNDEF_STATUS NDEF_MsgReplaceType (UINT8 *p_msg, UINT32 max_size, UINT32 *p_cur_size,
341                                         UINT8 *p_rec, UINT8 *p_new_type, UINT8 new_type_len);
342
343/*******************************************************************************
344**
345** Function         NDEF_MsgReplaceId
346**
347** Description      This function replaces the ID field of a specific record in the
348**                  given NDEF message
349**
350** Returns          OK, or error if the new ID field did not fit
351**                  *p_cur_size is updated
352**
353*******************************************************************************/
354EXPORT_NDEF_API extern tNDEF_STATUS NDEF_MsgReplaceId (UINT8 *p_msg, UINT32 max_size, UINT32 *p_cur_size,
355                                       UINT8 *p_rec, UINT8 *p_new_id, UINT8 new_id_len);
356
357/*******************************************************************************
358**
359** Function         NDEF_MsgRemoveRec
360**
361** Description      This function removes the record at the given
362**                  index in the given NDEF message.
363**
364** Returns          OK, or error if the index was invalid
365**                  *p_cur_size is updated
366**
367*******************************************************************************/
368EXPORT_NDEF_API extern tNDEF_STATUS NDEF_MsgRemoveRec (UINT8 *p_msg, UINT32 *p_cur_size, INT32 index);
369
370/*******************************************************************************
371**
372** Function         NDEF_MsgCopyAndDechunk
373**
374** Description      This function copies and de-chunks an NDEF message.
375**                  It is assumed that the destination is at least as large
376**                  as the source, since the source may not actually contain
377**                  any chunks.
378**
379** Returns          The output byte count
380**
381*******************************************************************************/
382EXPORT_NDEF_API extern tNDEF_STATUS NDEF_MsgCopyAndDechunk (UINT8 *p_src, UINT32 src_len, UINT8 *p_dest, UINT32 *p_out_len);
383
384/*******************************************************************************
385**
386** Function         NDEF_MsgCreateWktHr
387**
388** Description      This function creates Handover Request Record with version.
389**
390** Returns          NDEF_OK if all OK
391**
392*******************************************************************************/
393EXPORT_NDEF_API extern tNDEF_STATUS NDEF_MsgCreateWktHr (UINT8 *p_msg, UINT32 max_size, UINT32 *p_cur_size,
394                                                 UINT8 version );
395
396/*******************************************************************************
397**
398** Function         NDEF_MsgCreateWktHs
399**
400** Description      This function creates Handover Select Record with version.
401**
402** Returns          NDEF_OK if all OK
403**
404*******************************************************************************/
405EXPORT_NDEF_API extern tNDEF_STATUS NDEF_MsgCreateWktHs (UINT8 *p_msg, UINT32 max_size, UINT32 *p_cur_size,
406                                                 UINT8 version );
407
408/*******************************************************************************
409**
410** Function         NDEF_MsgAddWktHc
411**
412** Description      This function adds Handover Carrier Record.
413**
414** Returns          NDEF_OK if all OK
415**
416*******************************************************************************/
417EXPORT_NDEF_API extern tNDEF_STATUS NDEF_MsgAddWktHc (UINT8 *p_msg, UINT32 max_size, UINT32 *p_cur_size,
418                                              char  *p_id_str, UINT8 ctf,
419                                              UINT8 carrier_type_len, UINT8 *p_carrier_type,
420                                              UINT8 carrier_data_len, UINT8 *p_carrier_data);
421
422/*******************************************************************************
423**
424** Function         NDEF_MsgAddWktAc
425**
426** Description      This function adds Alternative Carrier Record.
427**
428** Returns          NDEF_OK if all OK
429**
430*******************************************************************************/
431EXPORT_NDEF_API extern tNDEF_STATUS NDEF_MsgAddWktAc (UINT8 *p_msg, UINT32 max_size, UINT32 *p_cur_size,
432                                              UINT8 cps, char *p_carrier_data_ref_str,
433                                              UINT8 aux_data_ref_count, char *p_aux_data_ref_str[]);
434
435/*******************************************************************************
436**
437** Function         NDEF_MsgAddWktCr
438**
439** Description      This function adds Collision Resolution Record.
440**
441** Returns          NDEF_OK if all OK
442**
443*******************************************************************************/
444EXPORT_NDEF_API extern tNDEF_STATUS NDEF_MsgAddWktCr (UINT8 *p_msg, UINT32 max_size, UINT32 *p_cur_size,
445                                              UINT16 random_number );
446
447/*******************************************************************************
448**
449** Function         NDEF_MsgAddWktErr
450**
451** Description      This function adds Error Record.
452**
453** Returns          NDEF_OK if all OK
454**
455*******************************************************************************/
456EXPORT_NDEF_API extern tNDEF_STATUS NDEF_MsgAddWktErr (UINT8 *p_msg, UINT32 max_size, UINT32 *p_cur_size,
457                                               UINT8 error_reason, UINT32 error_data );
458
459/*******************************************************************************
460**
461** Function         NDEF_MsgAddMediaBtOob
462**
463** Description      This function adds BT OOB Record.
464**
465** Returns          NDEF_OK if all OK
466**
467*******************************************************************************/
468EXPORT_NDEF_API extern tNDEF_STATUS NDEF_MsgAddMediaBtOob (UINT8 *p_msg, UINT32 max_size, UINT32 *p_cur_size,
469                                                   char *p_id_str, BD_ADDR bd_addr);
470
471/*******************************************************************************
472**
473** Function         NDEF_MsgAppendMediaBtOobCod
474**
475** Description      This function appends COD EIR data at the end of BT OOB Record.
476**
477** Returns          NDEF_OK if all OK
478**
479*******************************************************************************/
480EXPORT_NDEF_API extern tNDEF_STATUS NDEF_MsgAppendMediaBtOobCod (UINT8 *p_msg, UINT32 max_size, UINT32 *p_cur_size,
481                                                         char *p_id_str, DEV_CLASS cod);
482
483/*******************************************************************************
484**
485** Function         NDEF_MsgAppendMediaBtOobName
486**
487** Description      This function appends Bluetooth Local Name EIR data
488**                  at the end of BT OOB Record.
489**
490** Returns          NDEF_OK if all OK
491**
492*******************************************************************************/
493EXPORT_NDEF_API extern tNDEF_STATUS NDEF_MsgAppendMediaBtOobName (UINT8 *p_msg, UINT32 max_size, UINT32 *p_cur_size,
494                                                          char *p_id_str, BOOLEAN is_complete,
495                                                          UINT8 name_len, UINT8 *p_name);
496
497/*******************************************************************************
498**
499** Function         NDEF_MsgAppendMediaBtOobHashCRandR
500**
501** Description      This function appends Hash C and Rand R at the end of BT OOB Record.
502**
503** Returns          NDEF_OK if all OK
504**
505*******************************************************************************/
506EXPORT_NDEF_API extern tNDEF_STATUS NDEF_MsgAppendMediaBtOobHashCRandR (UINT8 *p_msg, UINT32 max_size, UINT32 *p_cur_size,
507                                                                char *p_id_str, UINT8 *p_hash_c, UINT8 *p_rand_r);
508
509/*******************************************************************************
510**
511** Function         NDEF_MsgAppendMediaBtOobEirData
512**
513** Description      This function appends EIR Data at the end of BT OOB Record.
514**
515** Returns          NDEF_OK if all OK
516**
517*******************************************************************************/
518EXPORT_NDEF_API extern tNDEF_STATUS NDEF_MsgAppendMediaBtOobEirData (UINT8 *p_msg, UINT32 max_size, UINT32 *p_cur_size,
519                                                             char *p_id_str,
520                                                             UINT8 eir_type, UINT8 data_len, UINT8 *p_data);
521
522#ifdef __cplusplus
523}
524#endif
525
526#endif /* NDEF_UTILS_H */
527