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