Zebra MC45,MC4587,MC4597 MC45 NFC Programmers Guide English
MC45
NFC PROGRAMMING
GUIDE
MC45
NFC PROGRAMMING GUIDE
MN000145A02
Rev. A
February 2015
ii MC45 NFC Programming Guide
© 2015 Symbol Technologies, Inc.
No part of this publication may be reproduced or used in any form, or by any electrical or mechanical means,
without permission in writing from Zebra. This includes electronic or mechanical means, such as photocopying,
recording, or information storage and retrieval systems. The material in this manual is subject to change
without notice.
The software is provided strictly on an “as is” basis. All software, including firmware, furnished to the user is on
a licensed basis. Zebra grants to the user a non-transferable and non-exclusive license to use each software
or firmware program delivered hereunder (licensed program). Except as noted below, such license may not be
assigned, sublicensed, or otherwise transferred by the user without prior written consent of Zebra. No right to
copy a licensed program in whole or in part is granted, except as permitted under copyright law. The user shall
not modify, merge, or incorporate any form or portion of a licensed program with other program material, create
a derivative work from a licensed program, or use a licensed program in a network without written permission
from Zebra. The user agrees to maintain Zebra’s copyright notice on the licensed programs delivered
hereunder, and to include the same on any authorized copies it makes, in whole or in part. The user agrees not
to decompile, disassemble, decode, or reverse engineer any licensed program delivered to the user or any
portion thereof.
Zebra reserves the right to make changes to any software or product to improve reliability, function, or design.
Zebra does not assume any product liability arising out of, or in connection with, the application or use of any
product, circuit, or application described herein.
No license is granted, either expressly or by implication, estoppel, or otherwise under any Zebra intellectual
property rights. An implied license only exists for equipment, circuits, and subsystems contained in Zebra
products.
Zebra and the Zebra head graphic are registered trademarks of ZIH Corp. The Symbol logo is a registered
trademark of Symbol Technologies, Inc., a Zebra Technologies company.
Zebra Technologies Corporation
Lincolnshire, IL U.S.A
http://www.zebra.com
Revision History
Changes to the original guide are listed below:
Change Date Description
Rev A 10/2013 Initial release
Rev A 2/2015 Zebra rebranding
iii
iv MC45 NFC Programming Guide
TABLE OF CONTENTS
Revision History .............................................................................................................................. iii
About This Guide
Introduction ..................................................................................................................................... i
Chapter Descriptions ...................................................................................................................... i
Notational Conventions................................................................................................................... ii
Service Information ......................................................................................................................... ii
Chapter 1: Functions
Introduction .................................................................................................................................... 1-1
NFC_Init() ................................................................................................................................ 1-1
NFC_DeInit() ............................................................................................................................ 1-3
NFC_GetVersion() ................................................................................................................... 1-4
NFC_GetCapabilities() ............................................................................................................. 1-5
NFC_GetConfig() ..................................................................................................................... 1-6
NFC_SetConfig() ..................................................................................................................... 1-7
NFC_SetDefaultConfig() .......................................................................................................... 1-8
NFC_RegisterForConfigChange() ........................................................................................... 1-9
NFC_CloseHandle() ................................................................................................................. 1-10
NFC_CloseAllHandles() ........................................................................................................... 1-11
NFC_RegisterForTagDetection() ............................................................................................. 1-12
NFC_RegisterForMessage() .................................................................................................... 1-14
NFC_GetRecord() .................................................................................................................... 1-16
NFC_GetEnclosedMessageInfo() ............................................................................................ 1-18
NFC_GetMessageContent() .................................................................................................... 1-20
NFC_CreateMessage() ............................................................................................................ 1-22
NFC_AddRecord() ................................................................................................................... 1-23
NFC_WriteMessage() .............................................................................................................. 1-25
NFC_ExchangeData() .............................................................................................................. 1-27
NFC_NDEFFormat() ................................................................................................................ 1-28
NFC_MakeReadOnly() ............................................................................................................ 1-30
NFC Card Emulation APIs ............................................................................................................. 1-32
2 MC45 NFC Programming Guide
NFC_RegisterForHostCardEmulation() ................................................................................... 1-32
NFC_EnableCE() ..................................................................................................................... 1-34
NFC_DisableCE() .................................................................................................................... 1-35
NFC Bluetooth Pairing APIs .......................................................................................................... 1-36
NFC_EnableBTPairing() .......................................................................................................... 1-36
NFC_DisableBTPairing() ......................................................................................................... 1-37
Chapter 2: Callback Prototypes
Introduction .................................................................................................................................... 2-1
NFC_Config_Callback ............................................................................................................. 2-1
NFC_CE_Callback ................................................................................................................... 2-2
NFC_BT_Callback ................................................................................................................... 2-3
NFC_TagDetection_Callback .................................................................................................. 2-4
NFC_Message_Callback ......................................................................................................... 2-5
Chapter 3: Structures
Introduction .................................................................................................................................... 3-1
NFC_HANDLE ......................................................................................................................... 3-1
STRUCT_INFO ........................................................................................................................ 3-1
NFC_Version ........................................................................................................................... 3-2
NFC_Config ............................................................................................................................. 3-2
NFC_Record ............................................................................................................................ 3-3
NFC_Tags ................................................................................................................................ 3-4
NFC_CapStruct ........................................................................................................................ 3-5
NFC_TagInfo ........................................................................................................................... 3-7
NFC_BTPairingInfo .................................................................................................................. 3-8
Chapter 4: Return Values
Introduction .................................................................................................................................... 4-1
NFC_STATUS ............................................................................................................................... 4-1
Chapter 5: Programming Overview
Introduction .................................................................................................................................... 5-1
NFC Components .......................................................................................................................... 5-1
NFC Programming Overview ......................................................................................................... 5-2
NFC Stack Initialization & De-Initialization ............................................................................... 5-2
NFC Capabilities of the System ............................................................................................... 5-2
Configuring NFC ...................................................................................................................... 5-2
NFC Radio and Polling ............................................................................................................ 5-3
Configuring Application Types and Modes .............................................................................. 5-4
NDEF Message ........................................................................................................................ 5-11
ABOUT THIS GUIDE
Introduction
This guide describes the Zebra Application Programmer’s Interface (API) which provides a way for application
developers to programmatically access the NFC stack functionality and aids in new application development.
The main features of NFC software stack are:
•
Supports NFC functionality such as NFC card reader and card emulation.
•
Supports identification, reading and writing to the following tags:
• NFC tag types 1-4
• Mifare
• Calypso
• ISO 15693 NXP i-CODE
• Felica
• TI TagIT.
Chapter Descriptions
Topics covered in this guide are as follows:
•
Chapter 1, Functions provides a detailed overview of all of the functions available for MC45 NFC
programming including a description, function prototype, parameters, return values, comments and an
example for each function.
•
Chapter 2, Callback Prototypes provides information on all of the available callback functions for MC45 NFC
programming including a description, function prototype, parameters, and return values for each function.
•
Chapter 3, Structures describes the available structures for MC45 NFC programming including a description
and structure definition for each.
•
Chapter 4, Return Values provides a table of all possible return values along with a description of each.
•
Chapter 5, Programming Overview provides an overview of NFC programming giving step-by-step
procedures and examples on how to initialize and deinitialize the NFC stack, view the NFC capabilities of the
ii MC45 NFC Programming Guide
system, NFC configuration, NFC radio and polling services, configuring application types and modes and
creating/reading NDEF messages.
Notational Conventions
The following conventions are used in this document:
•
Italics are used to highlight the following:
• Chapters and sections in this and related documents
• Dialog box, window and screen names
• Drop-down list and list box names
• Check box and radio button names
• Icons on a screen.
•
Bold text is used to highlight the following:
• Key names on a keypad
• Button names on a screen or window.
•
bullets (•) indicate:
• Action items
• Lists of alternatives
• Lists of required steps that are not necessarily sequential
•
Sequential lists (e.g., those that describe step-by-step procedures) appear as numbered lists.
NOTE This symbol indicates something of special interest or importance to the reader. Failure to read the note
will not result in physical harm to the reader, equipment or data.
CAUTION This symbol indicates that if this information is ignored, the possibility of data or material damage may
occur.
WARNING! This symbol indicates that if this information is ignored the possibility that serious personal
Service Information
If you have a problem with your equipment, contact Zebra Global Customer Support for your region. Contact
information is available at: http://www.zebra.com/support
injury may occur.
.
When contacting Zebra Global Customer Support, please have the following information available:
•
Serial number of the unit
•
Model number or product name
•
Software type and version number.
Zebra responds to calls by E-mail, telephone or fax within the time limits set forth in support agreements.
If your problem cannot be solved by Zebra Global Customer Support, you may need to return your equipment
for servicing and will be given specific directions. Zebra is not responsible for any damages incurred during
About This Guide iii
shipment if the approved shipping container is not used. Shipping the units improperly can possibly void the
warranty.
If you purchased your business product from a Zebra business partner, contact that business partner for
support.
iv MC45 NFC Programming Guide
CHAPTER 1 FUNCTIONS
Introduction
This chapter provides a detailed overview of all of the functions available for MC45 NFC programming
including a description, function prototype, parameters, return values, comments and examples.
NFC_Init()
Description
Initializes the NFC stack. This needs to be called before any other NFC APIs.
Function Prototype
NFC_STATUS NFC_Init (void)
Parameters
None
Return Values
NFC_SUCCESS
NFC_ERROR_OUT_OF_RESOURCE Out of resources like memory.
NFC_ERROR_DLL_NOT_AVAILABLE NFC Stack DLL has not been loaded.
NFC_ERROR_NOT_SUPPORTED NFC is Not Supported on the terminal.
NFC_FAILED If any other error occurs.
Comments
Individual firmware version, stack version, etc. can be obtained through NFC_GetCapabilities.
NFC_SUCCESS in case of success.
1 - 2 MC45 NFC Programming Guide
See Also
NFC_DeInit()
Example
/* Initialize the NFC stack */
if(nStatus = NFC_Init() != NFC_SUCCESS)
{
printf("Error %d: Cannot initialize the NFC stack.\n", nStatus);
exit();
}
NFC_DeInit()
Description
De-initializes the NFC stack. Any open handles will be closed by the NFC stack.
Function Prototype
NFC_STATUS NFC_DeInit(void)
Parameters
None
Return Values
Functions 1 - 3
NFC_SUCCESS
NFC_FAILED If any error occurs.
NFC_SUCCESS in case of success.
Comments
None
See Also
NFC_Init()
Example
/* De-Initialize the NFC stack */
if(nStatus = NFC_DeInit() != NFC_SUCCESS)
{
printf("Error %d: DeInit NFC stack.\n", nStatus);
return -1;
}
1 - 4 MC45 NFC Programming Guide
NFC_GetVersion()
Description
This function obtains the version information of the NFC stack.
Function Prototype
NFC_STATUS NFC_GetVersion (NFC_Version *pNfcVersion)
Parameters
[out] pNFCVersion
A pointer of NFC_Version passed to the function. The function returns the
consolidated version number of the NFC Stack.
Return Values
NFC_SUCCESS
NFC_ERROR_OUT_OF_RESOURCE Out of resources (Ex. memory)
NFC_FAILED If any error occurs
Indicates success
Comments
Individual firmware version, stack version, etc. can be obtained through NFC_GetCapabilities.
See Also
NFC_GetCapabilities
Example
/* Initialize the NFC stack */
if(nStatus = NFC_GetVersion(&nfcVersion) != NFC_SUCCESS)
{
printf("Error %d: Failed to get NFC Version.\n", nStatus);
exit();
}
Functions 1 - 5
NFC_GetCapabilities()
Description
This function returns the capabilities of the stack, the version number of the firmware, the vendor name, etc.
The capabilities are stored in a structure.
Function Prototype
NFC_STATUS NFC_GetCapabilities (NFC_CapStruct *pCapabilities)
Parameters
[out] pCapabilties
A pointer to a structure for receiving the capability values.
Return Values
NFC_SUCCESS
NFC_ERROR_OUT_OF_RESOURCE Out of resources (Example: memory).
NFC_FAILED If any error occurs.
Comments
None
See Also
None
Example
NFC_CapStruct capValues;
NFC_STATUS status;
status = NFC_GetCapabilities(&capValues);
...
Indicates success.
1 - 6 MC45 NFC Programming Guide
NFC_GetConfig()
Description
This function returns the current configuration values of the stack.
Function Prototype
NFC_STATUS NFC_GetConfig (NFC_Config *psConfigValues)
Parameters
[out] psConfigValues
The configuration values.
Return Values
NFC_SUCCESS
NFC_ERROR_OUT_OF_RESOURCE Out of resources (Example: memory).
NFC_FAILED If any error occurs.
Comments
None
See Also
NFC_SetConfig()
Example
NFC_Config configValues;
NFC_STATUS status;
status = NFC_GetConfig(&configValues);
...
Indicates success.
Functions 1 - 7
NFC_SetConfig()
Description
This function sets configuration values for the stack. See NFC_Version on page 3-2 for the values that can be
configured.
Function Prototype
NFC_STATUS NFC_SetConfig (NFC_Config sConfigValues)
Parameters
[in] psConfigValues
The configuration values.
Return Values
NFC_SUCCESS
NFC_ERROR_BAD_PARAMETER
NFC_ERROR_OUT_OF_RESOURCE Out of resources (Example: memory).
NFC_FAILED If any other error occurs.
The operation is performed successfully.
A wrong value is detected for a parameter.
Comments
Important: Before modifying the configuration, you must first obtain the system configuration with properly
populated fields using NFC_GetConfig(), and then continue to modify the required fields. Subsequently, set the
configuration using NFC_SetConfig().
See Also
NFC_GetConfig(), NFC_SetDefaultConfig(), NFC_RegisterForConfigChange()
Example
NFC_Config configValues;
NFC_STATUS status;
If (NFC_GetConfig(&configValues) == SUCCESS)
{
configValues.PollingTimeout = 60;
configValues.passkey = {'1','1','1','1','\0'};
If (NFC_SetConfig(configValues) != SUCCESS)
{
...
1 - 8 MC45 NFC Programming Guide
NFC_SetDefaultConfig()
Description
This function sets the default configuration values for the stack. The default configuration values are defined in
NFC_Version on page 3-2.
Function Prototype
NFC_STATUS NFC_SetDefaultConfig (Void)
Parameters
None
Return Values
NFC_SUCCESS
NFC_ERROR_OUT_OF_RESOURCE Out of resources (Example: memory).
NFC_FAILED If any other error occurs.
Comments
None
See Also
NFC_SetConfig()
Example
NFC_STATUS status;
status = NFC_SetDefaultConfig();
...
The operation is performed successfully.
Functions 1 - 9
NFC_RegisterForConfigChange()
Description
This function registers a callback that needs to be invoked whenever a configuration is changed by another
application. This is usually used to indicate if the other application changed configuration.
Function Prototype
NFC_STATUS NFC_RegisterForConfigChange (NFC_Config_Callback *pHandler,PVOID
pPassbackParameter, NFC_HANDLE*phConfigChangeHandle)
Parameters
[in] pHandler
[in] pPassbackParameter
[out] phConfigChangeHandle
Return Values
NFC_SUCCESS
NFC_ERROR_OUT_OF_RESOURCE Out of resources (Example: memory).
NFC_FAILED If any other error occurs.
Comments
None
See Also
None
A pointer on the handler function invoked when any configuration
changes.
A parameter transmitted to the handler function.
A pointer on a variable valued with the handle of the registration.
This value may be used with NFC_CloseHandle() to unregister the
handler function.
The operation is performed successfully.
Example
NFC_Handle configChangeHandle;
NFC_STATUS status;
status = NFC_RegisterForConfigChange(configChangeHandler, NULL,
configChangeHandle);
...
1 - 10 MC45 NFC Programming Guide
NFC_CloseHandle()
Description
Frees the resources allocated for a handle. The handle becomes invalid after the call to NFC_CloseHandle().
Using this handle subsequently will cause an error.
Function Prototype
NFC_STATUS NFC_CloseHandle (NFC_HANDLE hHandle)
Parameters
[in] hHandle
The handle of the connection to close.
Return Values
NFC_SUCCESS
NFC_ERROR_BAD_HANDLE A bad handle value is detected.
NFC_FAILED Indicates if any other errors.
NFC_SUCCESS in case of success.
Comments
The following handles may be used with NFC_CloseHandle():
•
The event registry handles. Closing an event registry handle causes the un-registration of the event
handler function.
•
The connection handles.
•
The NFC message handles.
See Also
NFC_CloseAllHandles()
Example
NFC_HANDLE aTagEventRegistry;
/* Register TAG handler */
...
/* Un-Register TAG handler */
NFC_CloseHandle(aTagEventRegistry);
Functions 1 - 11
NFC_CloseAllHandles()
Description
Frees the resources allocated by all handles in the application. The handles become invalid after the call to
NFC_CloseAllHandles(). Using those handles subsequently will cause an error.
Function Prototype
NFC_STATUS NFC_CloseAllHandles (void)
Parameters
None
Return Values
NFC_SUCCESS
NFC_FAILED Indicates if any other errors.
Comments
None
See Also
NFC_CloseHandle()
Example
// Close all Handles
NFC_CloseAllHandles();
NFC_SUCCESS in case of success.
1 - 12 MC45 NFC Programming Guide
NFC_RegisterForTagDetection()
Description
This function registers a handler function to listen to tag detection. After a successful registration, the handler
function is called each time a tag is detected. NFC_CloseHandle() should be called to unregister the function.
If TagsToBeDetected is set to null, every tag supported by the stack is detected.
Function Prototype
NFC_STATUS NFC_RegisterForTagDetection ( NFC_ TagDetection _Callback *pHandler, PVOID
pPassbackParameter, const NFC_Tags TagsToBeDetected, NFC_HANDLE *phTagDetectionHandle)
Parameters
[in] pHandler
[in] pPassbackParameter
[in] TagsToBeDetected
[out] phTagDetectionHandle
A pointer on the handler function called to listen to the tag detection.
A parameter transmitted to the handler function.
A structure with TRUE values corresponding to type of tags to be
detected.
A pointer on a variable valued with the handle of the registration. This
value may be used with NFC_CloseHandle() to unregister the
handler function.
Return Values
NFC_SUCCESS
NFC_ERROR_BAD_PARAMETER A bad parameter value.
NFC_ERROR_FEATURE_NOT_SUPPORTED The requested feature is not supported.
NFC_ERROR_OUT_OF_RESOURCE
NFC_FAILED
NFC_SUCCESS in case of success.
Out of resources. (Example: memory).
Indicates if any other errors.
Comments
Calling this function turns on the NFC radio if it is off and starts the polling process for all registered
technologies.
See Also
NFC_GetCapabilities()
Example
/* Register tag event handler */
NFC_Tags TagsToBeDetected;
TagsToBeDetected.MiFareUL = TRUE;
TagsToBeDetected.MiFareStd = TRUE;
TagsToBeDetected.ISO14443A = TRUE;
Functions 1 - 13
NFC_STATUS nStatus = NFC_RegisterForTagDetection(static_TagDetectionHandler,
NULL, TagsToBeDetected, &hTagDetectionHandle);
/* Get the result of the tag detection */
void static_TagDetectionHandler (void *pPassbackParameter, NFC_HANDLE
hConnection,
NFC_TagInfo TagInfo, NFC_STATUS nStatus)
{
/* Perform tag operations based on detected tag*/
If (TagInfo.TagsAndProtocols.MiFareUL == TRUE)
{
}
else if (TagInfo.TagsAndProtocols.MiFareStd == TRUE)
{
}
…
}
1 - 14 MC45 NFC Programming Guide
NFC_RegisterForMessage()
Description
Retrieves NDEF messages from NFC tags. The function registers a callback function to be called each time a
matching message is read from a tag. Value 'zero' for nTNF, registers for all NDEF messages. A valid value in
nTNF and NULL for pTypesArray, registers for all types of the registered TNF format.
The un-registration is done by closing the handle returned in the NDEFMessageRegistrationHandle parameter
using NFC_CloseHandle().
Function Prototype
NFC_STATUS NFC_RegisterForMessage (NFC_Message _Callback* pHandler,
PVOID pPassbackParameter, WORD nTNF, const TCHAR* pTypesArray[], WORD nNoOfTypes,
NFC_HANDLE* NDEFMessageRegistrationHandle)
Parameters
[in] pHandler
[in] pPassbackParameter
[in] nTNF
[in] pTypesArray
[in] nNoOfTypes
[out] NDEFMessageRegistrationHandle
Return Values
NFC_SUCCESS
NFC_ERROR_BAD_PARAMETER A bad parameter value.
NFC_ERROR_OUT_OF_RESOURCE Out of resources (Example: memory).
A pointer on the handler function.
A parameter transmitted to the handler function.
The message TNF value. An nTNF value of 0 indicates
registration for all NDEF messages. The valid values for
nTNF are: TNF-WKT (Well-Known Type), TNF-MIME,
TNF-AbsURI, TNF-EXT (External Type) and TNF-UNK
(Unknown Type).
An array of types to filter for. A value of NULL indicates
registration for all types with TNF value indicated by nTNF.
No. of types to filter for; the types are in pTypesArray.
A pointer on a variable valued with the handle of the
registration. This value may be used with
NFC_CloseHandle() to unregister the handler function.
The operation was performed successfully.
NFC_FAILED If any other error occurred.
Comments
NFC_RegisterForMessage registers for reading message present on any type of tag (Type 1, 2, 3, 4). The TNF
and Type of the first record in the message is considered for comparing with the registered TNF and Types.
Calling this function turns on the NFC radio if it is off and starts the polling process for all technologies.
Loading...