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