client/include/net_nfc_ndef_message.h

   1 /*
   2  * Copyright (c) 2012, 2013 Samsung Electronics Co., Ltd.
   3  *
   4  * Licensed under the Flora License, Version 1.1 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *     http://floralicense.org/license/
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16 #ifndef __NET_NFC_NDEF_MESSAGE_H__
  17 #define __NET_NFC_NDEF_MESSAGE_H__
  18
  19 #include "net_nfc_typedef.h"
  20
  21 /**
  22
  23   @addtogroup NET_NFC_MANAGER_NDEF
  24   @{
  25   This document is for the APIs reference document
  26
  27   NFC Manager defines are defined in <nfc-manager-def.h>
  28
  29   @li @c #net_nfc_client_initialize                  Initialize the nfc device.
  30
  31 */
  32
  33 /**
  34   create ndef message handler. this function allocate the ndef message handler and initialize.
  35
  36   \par Sync (or) Async: sync
  37   This is a Synchronous API
  38
  39   @param[out]   ndef_message            instance of the ndef_message is retuened
  40
  41   @return       return the result of the calling the function
  42
  43   @exception NET_NFC_NULL_PARAMETER             parameter(s) has(have) illigal NULL pointer(s)
  44   @exception NET_NFC_ALLOC_FAIL                 memory allocation is failed
  45
  46   @code
  47
  48   net_nfc_error_e result = NET_NFC_OK;
  49   ndef_message_s *msg = NULL;
  50   ndef_record_s *record = NULL;
  51
  52   result = net_nfc_create_ndef_message (&msg);
  53   if (result != NET_NFC_OK) return result;
  54
  55   result = net_nfc_create_uri_type_record (&record , "http://www.samsung.com" ,NET_NFC_SCHEMA_FULL_URI);
  56   if (result != NET_NFC_OK) return result;
  57
  58   result = net_nfc_append_record_to_ndef_message (msg ,record);
  59   if (result != NET_NFC_OK) return result;
  60
  61   net_nfc_write_ndef(id, msg, &user_context);
  62
  63   net_nfc_free_ndef_message (msg);
  64
  65   @endcode
  66   */
  67
  68
  69 net_nfc_error_e net_nfc_create_ndef_message(ndef_message_s **ndef_message);
  70
  71 /**
  72   this APIs is the getter of  record counts
  73
  74   \par Sync (or) Async: sync
  75   This is a Synchronous API
  76
  77   @param[in]    ndef_message    output structure to get the record
  78   @param[out]   count                   number of record count
  79
  80
  81   @return               return the result of the calling the function
  82
  83   @exception NET_NFC_NULL_PARAMETER             parameter(s) has(have) illigal NULL pointer(s)
  84
  85   @code
  86
  87         static void net_nfc_cb(net_nfc_message_e message, net_nfc_error_e result, void* data , void* userContext)
  88         {
  89                 switch (message)
  90                 {
  91                         case NET_NFC_MESSAGE_READ_NDEF:
  92                                 {
  93                                         if(data != NULL)
  94                                         {
  95                                                 int count = 0;
  96                                                 ndef_message_s *ndef = (ndef_message_s*)data;
  97                                                 net_nfc_get_ndef_message_record_count (ndef, &count);
  98                                                 printf ("record count = %d\n", count);
  99                                         }
 100                                 }
 101                         break;
 102                 }
 103         }
 104         @endcode
 105 */
 106 net_nfc_error_e net_nfc_get_ndef_message_record_count (ndef_message_s *ndef_message, int * count);
 107
 108 /**
 109   This function converts the NDEF Message structure to serial bytes of ndef message.
 110
 111   it gets copy of the rawdata bytes from ndef_message. ndef_message has no effect after free rawdata
 112   Application should free rawdata.
 113
 114   \par Sync (or) Async: sync
 115   This is a Synchronous API
 116
 117   @param[in]    ndef_message    output structure to get the record
 118   @param[out]   rawdata                 this is the raw data that will be formed into the
 119
 120   @return               return the result of the calling the function
 121
 122   @exception NET_NFC_NULL_PARAMETER             parameter(s) has(have) illigal NULL pointer(s)
 123   @exception NET_NFC_ALLOC_FAIL                 memory allocation is failed
 124   @exception NET_NFC_NDEF_BUF_END_WITHOUT_ME    Wrong formatted NDEF message
 125
 126   @code
 127
 128   net_nfc_error_e result = NET_NFC_OK;
 129   data_s *rawdata;
 130   ndef_message_s *msg = NULL;
 131   ndef_record_s *record = NULL;
 132   int idx;
 133   uint8_t * buffer = NULL;
 134
 135   result = net_nfc_create_ndef_message (&msg);
 136   if (result != NET_NFC_OK) return result;
 137
 138   result = net_nfc_create_uri_type_record (&record , "http://www.samsung.com" ,NET_NFC_SCHEMA_FULL_URI);
 139   if (result != NET_NFC_OK) return result;
 140
 141   result = net_nfc_append_record_to_ndef_message (msg ,record);
 142   if (result != NET_NFC_OK) return result;
 143
 144   net_nfc_create_rawdata_from_ndef_message (msg, &rawdata);
 145
 146   buffer = net_nfc_get_data_buffer (rawdata) ;
 147
 148   for (idx = 0; idx < net_nfc_get_data_length (rawdata) ; idx++)
 149   {
 150                 printf (" %02X", buffer[idx]);
 151                 if (idx % 16 == 0) printf ("\n");
 152   }
 153
 154   net_nfc_free_ndef_message (msg);
 155
 156   @endcode
 157
 158
 159 */
 160
 161 net_nfc_error_e net_nfc_create_rawdata_from_ndef_message(
 162                 ndef_message_s *ndef_message, data_s **rawdata);
 163
 164 /**
 165   This function return the structure of ndef_message from serial format of ndef message.
 166   You may say create ndef handler from raw serial bytes
 167   it cunsumes the bytes array until get the (ME==1). it retunrs error if the bytes array does not have ME flag.
 168   if the array has two NDEF Message serially (not recursive case - like smart poster). the first NDEF message
 169   will be converted to ndef_message handler, and other messages will be ignored.
 170
 171   \par Sync (or) Async: sync
 172   This is a Synchronous API
 173
 174   @param[out]   ndef_message            ndef message handler that will be returned
 175   @param[in]    rawdata                         ndef message that formed in bytes array
 176
 177   @return               return the result of the calling the function
 178
 179   @exception NET_NFC_NULL_PARAMETER             parameter(s) has(have) illigal NULL pointer(s)
 180   @exception NET_NFC_ALLOC_FAIL                 memory allocation is failed
 181   @exception NET_NFC_NDEF_BUF_END_WITHOUT_ME    Wrong formatted NDEF message
 182
 183   @code
 184
 185         static void net_nfc_cb(net_nfc_message_e message, net_nfc_error_e result, void* data , void* userContext)
 186         {
 187                 switch (message)
 188                 {
 189                         case NET_NFC_MESSAGE_READ_NDEF:
 190                                 {
 191                                         if(data != NULL)
 192                                         {
 193                                                 record_h record;
 194                                                 ndef_message_s *url;
 195                                                 data_s *ndef_type;
 196                                                 data_s *payload;
 197
 198                                                 ndef_message_s *ndef = (ndef_message_s*)data;
 199                                                 net_nfc_get_record_by_index (ndef, 0, &record);
 200                                                 net_nfc_get_record_type (record, &ndef_type);
 201                                                 if (strncmp (ndef_type.buffer, "Sp", ndef_type.length)){
 202                                                         net_nfc_get_record_payload (record, &payload);
 203                                                         net_nfc_create_ndef_message_from_rawdata (&url, payload);
 204                                                         printf_ndef_massage (url);
 205                                                 }
 206                                         }
 207                                 }
 208                         break;
 209                 }
 210         }
 211         @endcode
 212
 213 */
 214
 215
 216 net_nfc_error_e net_nfc_create_ndef_message_from_rawdata(
 217                 ndef_message_s **ndef_message, data_s *rawdata);
 218
 219 /**
 220   it returns the total size of ndef message bytes. parse the structure data and count the bytes
 221   to know the length of bytes required to store the NDEF message.
 222
 223   it calculates the length every time application calls this function. it does not cache inside.
 224   TODO: do we need to cache the value inside of ndef_message_s
 225
 226   \par Sync (or) Async: sync
 227   This is a Synchronous API
 228
 229   @param[in]    ndef_message            this is the raw data that will be formed into the
 230   @param[out]   length                  number of bytes required to create ndef message serial format
 231
 232   @return               return the result of the calling the function
 233
 234   @exception NET_NFC_NULL_PARAMETER             parameter(s) has(have) illigal NULL pointer(s)
 235 */
 236
 237 net_nfc_error_e net_nfc_get_ndef_message_byte_length(
 238                 ndef_message_s *ndef_message, uint32_t *length);
 239 /**
 240   Append a record to ndef message structure.
 241   This API help to create NDEF message and it control Record flags to follow the NDEF forum specification
 242
 243   \par Sync (or) Async: sync
 244   This is a Synchronous API
 245
 246   @param[in]    ndef_message            NDEF message structure
 247   @param[in]    record                  a record will be added into the ndef message
 248
 249   @return               return the result of the calling the function
 250
 251   @exception NET_NFC_NULL_PARAMETER             parameter(s) has(have) illigal NULL pointer(s)
 252
 253   @code
 254
 255   net_nfc_error_e result = NET_NFC_OK;
 256   data_s *rawdata;
 257   ndef_message_s *msg = NULL;
 258   ndef_record_s *record = NULL;
 259   int idx;
 260   uint8_t * buffer = NULL;
 261
 262   result = net_nfc_create_ndef_message (&msg);
 263   if (result != NET_NFC_OK) return result;
 264
 265   result = net_nfc_create_uri_type_record (&record , "http://www.samsung.com" ,NET_NFC_SCHEMA_FULL_URI);
 266   if (result != NET_NFC_OK) return result;
 267
 268   result = net_nfc_append_record_to_ndef_message (msg ,record);
 269   if (result != NET_NFC_OK) return result;
 270
 271   net_nfc_create_rawdata_from_ndef_message (msg, &rawdata);
 272
 273   buffer = net_nfc_get_data_buffer (rawdata) ;
 274
 275   for (idx = 0; idx < net_nfc_get_data_length (rawdata) ; idx++)
 276   {
 277     printf (" %02X", buffer[idx]);
 278     if (idx % 16 == 0) printf ("\n");
 279   }
 280
 281   net_nfc_free_ndef_message (msg);
 282
 283   @endcode
 284   */
 285 net_nfc_error_e net_nfc_append_record_to_ndef_message(
 286                 ndef_message_s *ndef_message, ndef_record_s *record);
 287
 288 /**
 289   remove the record that indicated by index number.
 290   and this deleted record will be freed.
 291
 292   \par Sync (or) Async: sync
 293   This is a Synchronous API
 294
 295   @param[in]    ndef_message    the message wil be freed
 296   @param[in]    index                   index of record
 297
 298   @return       return the result of the calling the function
 299
 300   @exception NET_NFC_NULL_PARAMETER             parameter(s) has(have) illigal NULL pointer(s)
 301   @exception NET_NFC_OUT_OF_BOUND                       index is out of bound
 302   @exception NET_NFC_INVALID_FORMAT             Wrong formatted ndef message
 303
 304 */
 305
 306 net_nfc_error_e net_nfc_remove_record_by_index(ndef_message_s *ndef_message,
 307                 int index);
 308
 309 /**
 310   get record by index. this function just return the pointer of record.
 311   if you change the record value it directly affected to NDEF message
 312
 313   \par Sync (or) Async: sync
 314   This is a Synchronous API
 315
 316   @param[in]    ndef_message            the message wil be freed
 317   @param[in]    index                   index of record
 318   @param[in]    record                  record pointer
 319
 320   @return               return the result of the calling the function
 321
 322   @exception NET_NFC_NULL_PARAMETER             parameter(s) has(have) illigal NULL pointer(s)
 323   @exception NET_NFC_OUT_OF_BOUND                       index is out of bound
 324
 325 */
 326 net_nfc_error_e net_nfc_get_record_by_index(ndef_message_s *ndef_message,
 327                 int index, ndef_record_s **record);
 328
 329 /**
 330   Add a record by index. This API help to add record by index. MB or ME bits will automatically assained.
 331
 332   \par Sync (or) Async: sync
 333   This is a Synchronous API
 334
 335   @param[in]    ndef_message            the message wil be freed
 336   @param[in]    index                   index of record
 337   @param[in]    record                  record pointer
 338
 339   @return               return the result of the calling the function
 340
 341   @exception NET_NFC_NULL_PARAMETER             parameter(s) has(have) illigal NULL pointer(s)
 342   @exception NET_NFC_OUT_OF_BOUND                       index is out of bound
 343   @exception NET_NFC_INVALID_FORMAT             Wrong formatted ndef message
 344   */
 345
 346 net_nfc_error_e net_nfc_append_record_by_index(ndef_message_s *ndef_message,
 347                 int index, ndef_record_s *record);
 348
 349
 350 /**
 351   search the specific type in the NDEF message. this function return the first record that holds the type.
 352   if the type has "urn:nfc:wkt:" or "urn:nfc:ext:", these prefix will be removed automatically.
 353
 354   @param[in]            ndef_message            NDEF message handler
 355   @param[in]            tnf                             TNF value
 356   @param[in]            type                            Record type , include type length
 357   @param[out]           record                  record handle
 358
 359   @return               return the result of the calling the function
 360
 361   @exception NET_NFC_NULL_PARAMETER             parameter(s) has(have) illigal NULL pointer(s)
 362   @exception NET_NFC_NO_DATA_FOUND                      search is failed
 363   @exception NET_NFC_INVALID_FORMAT             Wrong formatted ndef message
 364
 365   @code
 366
 367         static void net_nfc_cb(net_nfc_message_e message, net_nfc_error_e result, void* data , void* userContext)
 368         {
 369                 switch (message)
 370                 {
 371                         case NET_NFC_MESSAGE_READ_NDEF:
 372                                 {
 373                                         if(data != NULL)
 374                                         {
 375                                                 date_h type;
 376                                                 int count = 0;
 377                                                 ndef_message_s *ndef = (ndef_message_s*)data;
 378                                                 ndef_record_s *record;
 379                                                 net_nfc_create_data (&type, "Sp", 2);
 380                                                 net_nfc_search_record_by_type (ndef, NET_NFC_RECORD_WELL_KNOWN_TYPE, type, &record);
 381                                         }
 382                                 }
 383                         break;
 384                 }
 385         }
 386
 387   @endcode
 388
 389 */
 390 net_nfc_error_e net_nfc_search_record_by_type (ndef_message_s *ndef_message,
 391                 net_nfc_record_tnf_e tnf, data_s *type, ndef_record_s **record);
 392
 393
 394 /**
 395   this function helps to free the ndef_message_s type structure.
 396   it has multiple ndef_record_s with linked list form and each record has own pointer.
 397   this function free these memory in one shot!
 398   don't worry about the record handler. these handlers also freed.
 399
 400   \par Sync (or) Async: sync
 401   This is a Synchronous API
 402
 403   @param[in]    ndef_message            the message wil be freed
 404
 405   @return               return the result of the calling the function
 406
 407   @exception NET_NFC_NULL_PARAMETER             parameter(s) has(have) illigal NULL pointer(s)
 408
 409 */
 410
 411 net_nfc_error_e net_nfc_free_ndef_message(ndef_message_s *ndef_message);
 412
 413
 414 /**
 415   retreive ndef message which is read by nfc-manager .
 416   after reading message, it will be removed from nfc-manager storage
 417
 418   \par Sync (or) Async: sync
 419   This is a Synchronous API
 420
 421   @param[in]    ndef_message            the message wil be retrieved
 422
 423   @return               return the result of the calling the function
 424
 425   @exception NET_NFC_NULL_PARAMETER             parameter(s) has(have) illigal NULL pointer(s)
 426   @exception NET_NFC_NO_NDEF_MESSAGE            No ndef message is found
 427   @exception NET_NFC_INVALID_FORMAT             Wrong formatted ndef message
 428   @exception NET_NFC_ALLOC_FAIL                 memory allocation is failed
 429
 430 */
 431
 432 net_nfc_error_e net_nfc_retrieve_current_ndef_message(
 433                 ndef_message_s **ndef_message);
 434
 435
 436 /**
 437   @}
 438   */
 439
 440 #endif //__NET_NFC_NDEF_MESSAGE_H__