2 * Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
4 * Licensed under the Apache License, Version 2.0 (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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
16 #ifndef __NET_NFC_NDEF_MESSAGE_H__
17 #define __NET_NFC_NDEF_MESSAGE_H__
19 #include "net_nfc_typedef.h"
23 @addtogroup NET_NFC_MANAGER_NDEF
25 This document is for the APIs reference document
27 NFC Manager defines are defined in <nfc-manager-def.h>
29 @li @c #net_nfc_client_initialize Initialize the nfc device.
34 create ndef message handler. this function allocate the ndef message handler and initialize.
36 \par Sync (or) Async: sync
37 This is a Synchronous API
39 @param[out] ndef_message instance of the ndef_message is retuened
41 @return return the result of the calling the function
43 @exception NET_NFC_NULL_PARAMETER parameter(s) has(have) illigal NULL pointer(s)
44 @exception NET_NFC_ALLOC_FAIL memory allocation is failed
48 net_nfc_error_e result = NET_NFC_OK;
49 ndef_message_s *msg = NULL;
50 ndef_record_s *record = NULL;
52 result = net_nfc_create_ndef_message (&msg);
53 if (result != NET_NFC_OK) return result;
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;
58 result = net_nfc_append_record_to_ndef_message (msg ,record);
59 if (result != NET_NFC_OK) return result;
61 net_nfc_write_ndef(id, msg, &user_context);
63 net_nfc_free_ndef_message (msg);
69 net_nfc_error_e net_nfc_create_ndef_message(ndef_message_s **ndef_message);
72 this APIs is the getter of record counts
74 \par Sync (or) Async: sync
75 This is a Synchronous API
77 @param[in] ndef_message output structure to get the record
78 @param[out] count number of record count
81 @return return the result of the calling the function
83 @exception NET_NFC_NULL_PARAMETER parameter(s) has(have) illigal NULL pointer(s)
87 static void net_nfc_cb(net_nfc_message_e message, net_nfc_error_e result, void* data , void* userContext)
91 case NET_NFC_MESSAGE_READ_NDEF:
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);
106 net_nfc_error_e net_nfc_get_ndef_message_record_count (ndef_message_s *ndef_message, int * count);
109 This function converts the NDEF Message structure to serial bytes of ndef message.
111 it gets copy of the rawdata bytes from ndef_message. ndef_message has no effect after free rawdata
112 Application should free rawdata.
114 \par Sync (or) Async: sync
115 This is a Synchronous API
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
120 @return return the result of the calling the function
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
128 net_nfc_error_e result = NET_NFC_OK;
130 ndef_message_s *msg = NULL;
131 ndef_record_s *record = NULL;
133 uint8_t * buffer = NULL;
135 result = net_nfc_create_ndef_message (&msg);
136 if (result != NET_NFC_OK) return result;
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;
141 result = net_nfc_append_record_to_ndef_message (msg ,record);
142 if (result != NET_NFC_OK) return result;
144 net_nfc_create_rawdata_from_ndef_message (msg, &rawdata);
146 buffer = net_nfc_get_data_buffer (rawdata) ;
148 for (idx = 0; idx < net_nfc_get_data_length (rawdata) ; idx++)
150 printf (" %02X", buffer[idx]);
151 if (idx % 16 == 0) printf ("\n");
154 net_nfc_free_ndef_message (msg);
161 net_nfc_error_e net_nfc_create_rawdata_from_ndef_message(
162 ndef_message_s *ndef_message, data_s **rawdata);
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.
171 \par Sync (or) Async: sync
172 This is a Synchronous API
174 @param[out] ndef_message ndef message handler that will be returned
175 @param[in] rawdata ndef message that formed in bytes array
177 @return return the result of the calling the function
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
185 static void net_nfc_cb(net_nfc_message_e message, net_nfc_error_e result, void* data , void* userContext)
189 case NET_NFC_MESSAGE_READ_NDEF:
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);
216 net_nfc_error_e net_nfc_create_ndef_message_from_rawdata(
217 ndef_message_s **ndef_message, data_s *rawdata);
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.
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
226 \par Sync (or) Async: sync
227 This is a Synchronous API
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
232 @return return the result of the calling the function
234 @exception NET_NFC_NULL_PARAMETER parameter(s) has(have) illigal NULL pointer(s)
237 net_nfc_error_e net_nfc_get_ndef_message_byte_length(
238 ndef_message_s *ndef_message, uint32_t *length);
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
243 \par Sync (or) Async: sync
244 This is a Synchronous API
246 @param[in] ndef_message NDEF message structure
247 @param[in] record a record will be added into the ndef message
249 @return return the result of the calling the function
251 @exception NET_NFC_NULL_PARAMETER parameter(s) has(have) illigal NULL pointer(s)
255 net_nfc_error_e result = NET_NFC_OK;
257 ndef_message_s *msg = NULL;
258 ndef_record_s *record = NULL;
260 uint8_t * buffer = NULL;
262 result = net_nfc_create_ndef_message (&msg);
263 if (result != NET_NFC_OK) return result;
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;
268 result = net_nfc_append_record_to_ndef_message (msg ,record);
269 if (result != NET_NFC_OK) return result;
271 net_nfc_create_rawdata_from_ndef_message (msg, &rawdata);
273 buffer = net_nfc_get_data_buffer (rawdata) ;
275 for (idx = 0; idx < net_nfc_get_data_length (rawdata) ; idx++)
277 printf (" %02X", buffer[idx]);
278 if (idx % 16 == 0) printf ("\n");
281 net_nfc_free_ndef_message (msg);
285 net_nfc_error_e net_nfc_append_record_to_ndef_message(
286 ndef_message_s *ndef_message, ndef_record_s *record);
289 remove the record that indicated by index number.
290 and this deleted record will be freed.
292 \par Sync (or) Async: sync
293 This is a Synchronous API
295 @param[in] ndef_message the message wil be freed
296 @param[in] index index of record
298 @return return the result of the calling the function
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
306 net_nfc_error_e net_nfc_remove_record_by_index(ndef_message_s *ndef_message,
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
313 \par Sync (or) Async: sync
314 This is a Synchronous API
316 @param[in] ndef_message the message wil be freed
317 @param[in] index index of record
318 @param[in] record record pointer
320 @return return the result of the calling the function
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
326 net_nfc_error_e net_nfc_get_record_by_index(ndef_message_s *ndef_message,
327 int index, ndef_record_s **record);
330 Add a record by index. This API help to add record by index. MB or ME bits will automatically assained.
332 \par Sync (or) Async: sync
333 This is a Synchronous API
335 @param[in] ndef_message the message wil be freed
336 @param[in] index index of record
337 @param[in] record record pointer
339 @return return the result of the calling the function
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
346 net_nfc_error_e net_nfc_append_record_by_index(ndef_message_s *ndef_message,
347 int index, ndef_record_s *record);
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.
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
359 @return return the result of the calling the function
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
367 static void net_nfc_cb(net_nfc_message_e message, net_nfc_error_e result, void* data , void* userContext)
371 case NET_NFC_MESSAGE_READ_NDEF:
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);
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);
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.
400 \par Sync (or) Async: sync
401 This is a Synchronous API
403 @param[in] ndef_message the message wil be freed
405 @return return the result of the calling the function
407 @exception NET_NFC_NULL_PARAMETER parameter(s) has(have) illigal NULL pointer(s)
411 net_nfc_error_e net_nfc_free_ndef_message(ndef_message_s *ndef_message);
415 retreive ndef message which is read by nfc-manager .
416 after reading message, it will be removed from nfc-manager storage
418 \par Sync (or) Async: sync
419 This is a Synchronous API
421 @param[in] ndef_message the message wil be retrieved
423 @return return the result of the calling the function
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
432 net_nfc_error_e net_nfc_retrieve_current_ndef_message(
433 ndef_message_s **ndef_message);
440 #endif //__NET_NFC_NDEF_MESSAGE_H__