MoSync 3.3
NFC API

Defines

#define MA_NFC_NOT_AVAILABLE   -1
#define MA_NFC_NOT_ENABLED   -2
#define MA_NFC_INVALID_TAG_TYPE   -2
#define MA_NFC_TAG_CONNECTION_LOST   -3
#define MA_NFC_TAG_NOT_CONNECTED   -4
#define MA_NFC_FORMAT_FAILED   -5
#define MA_NFC_TAG_IO_ERROR   -127
#define MA_NFC_TAG_TYPE_NDEF   1
#define MA_NFC_TAG_TYPE_MIFARE_CL   2
#define MA_NFC_TAG_TYPE_MIFARE_UL   3
#define MA_NFC_TAG_TYPE_NFC_A   4
#define MA_NFC_TAG_TYPE_NFC_B   5
#define MA_NFC_TAG_TYPE_ISO_DEP   6
#define MA_NFC_TAG_TYPE_NDEF_FORMATTABLE   128
#define MA_NFC_NDEF_TNF_EMPTY   0
#define MA_NFC_NDEF_TNF_WELL_KNOWN   1
#define MA_NFC_NDEF_TNF_MIME_MEDIA   2
#define MA_NFC_NDEF_TNF_ABSOLUTE_URI   3
#define MA_NFC_NDEF_TNF_EXTERNAL_TYPE   4
#define MA_NFC_NDEF_TNF_UNKNOWN   5
#define MA_NFC_NDEF_TNF_UNCHANGED   6
#define MA_NFC_NDEF_TNF_RESERVED   7
#define MA_NFC_MIFARE_KEY_A   1
#define MA_NFC_MIFARE_KEY_B   2

Functions

int maNFCStart (void)
void maNFCStop (void)
MAHandle maNFCReadTag (MAHandle nfcContext)
void maNFCDestroyTag (MAHandle tagHandle)
void maNFCConnectTag (MAHandle tagHandle)
void maNFCCloseTag (MAHandle tagHandle)
int maNFCIsType (MAHandle tagHandle, int type)
MAHandle maNFCGetTypedTag (MAHandle tagHandle, int type)
int maNFCBatchStart (MAHandle tagHandle)
void maNFCBatchCommit (MAHandle tagHandle)
void maNFCBatchRollback (MAHandle tagHandle)
int maNFCTransceive (MAHandle tag, const void *src, int srcLen, void *dst, int *dstLen)
int maNFCSetReadOnly (MAHandle tag)
int maNFCIsReadOnly (MAHandle tag)
int maNFCGetSize (MAHandle tag)
int maNFCGetId (MAHandle tag, void *dst, int len)
int maNFCReadNDEFMessage (MAHandle tag)
int maNFCWriteNDEFMessage (MAHandle tag, MAHandle ndefMessage)
MAHandle maNFCCreateNDEFMessage (int recordCount)
int maNFCGetNDEFMessage (MAHandle tag)
MAHandle maNFCGetNDEFRecord (MAHandle ndefMessage, int ix)
int maNFCGetNDEFRecordCount (MAHandle ndefMessage)
int maNFCGetNDEFId (MAHandle ndefRecord, void *dst, int len)
int maNFCGetNDEFPayload (MAHandle ndefRecord, void *dst, int len)
int maNFCGetNDEFTnf (MAHandle ndefRecord)
int maNFCGetNDEFType (MAHandle ndefRecord, void *dst, int len)
int maNFCSetNDEFId (MAHandle ndefRecord, const void *dst, int len)
int maNFCSetNDEFPayload (MAHandle ndefRecord, const void *dst, int len)
int maNFCSetNDEFTnf (MAHandle ndefRecord, int tnf)
int maNFCSetNDEFType (MAHandle ndefRecord, const void *dst, int len)
int maNFCAuthenticateMifareSector (MAHandle tagHandle, int keyType, int sectorIndex, const void *keySrc, int keyLen)
int maNFCGetMifareSectorCount (MAHandle tagHandle)
int maNFCGetMifareBlockCountInSector (MAHandle tagHandle, int sector)
int maNFCMifareSectorToBlock (MAHandle tagHandle, int sector)
int maNFCReadMifareBlocks (MAHandle tagHandle, int firstBlock, void *dst, int len)
int maNFCWriteMifareBlocks (MAHandle tagHandle, int firstBlock, const void *dst, int len)
int maNFCReadMifarePages (MAHandle tagHandle, int firstPage, void *dst, int len)
int maNFCWriteMifarePages (MAHandle tagHandle, int firstPage, const void *dst, int len)

Define Documentation

#define MA_NFC_NOT_AVAILABLE   -1

A constant indicating there is no NFC support on the device.

#define MA_NFC_NOT_ENABLED   -2

A constant indicating NFC is not enabled on the device. (But there is hardware support).

#define MA_NFC_INVALID_TAG_TYPE   -2

A constant indicating an invalid tag type.

#define MA_NFC_TAG_CONNECTION_LOST   -3

An error code if tag connection is lost.

#define MA_NFC_TAG_NOT_CONNECTED   -4

An error code if trying to perform I/O on an unconnected tag.

#define MA_NFC_FORMAT_FAILED   -5

An error code used by maNFCWriteNDEF if maNFCWriteNDEF was performed on an NDEF_FORMATTABLE tag and failed.

#define MA_NFC_TAG_IO_ERROR   -127

An error code if some general I/O error occurred, other than the special case of tag connection being lost.

#define MA_NFC_TAG_TYPE_NDEF   1

Represents an NDEF (NFC Data Exchange Format) tag.

#define MA_NFC_TAG_TYPE_MIFARE_CL   2

Represents a Mifare Classic tag.

#define MA_NFC_TAG_TYPE_MIFARE_UL   3

Represents a Mifare Ultralight tag.

#define MA_NFC_TAG_TYPE_NFC_A   4

Represents an NfcA tag (ISO 14443-3A).

#define MA_NFC_TAG_TYPE_NFC_B   5

Represents an NfcB tag (ISO 14443-3B).

#define MA_NFC_TAG_TYPE_ISO_DEP   6

Represents an ISO-DEP tag (ISO 14443-4).

Represents an 'abstract' tag that can accept requests for formatting it into an NDEF tag.

#define MA_NFC_NDEF_TNF_EMPTY   0

Indicates the NDEF message is empty.

Indicates the NDEF message is of a 'well-known' type; it may be further identified using the MA_NFC_NDEF_RTD_* constants.

Indicates the NDEF message contains mime media; use maNFCGetType() to get the mime type.

Indicates the NDEF message contains an absolute URI, the type conforming to RFC 3986.

Indicates the type of the NDEF message being 'external'.

#define MA_NFC_NDEF_TNF_UNKNOWN   5

Indicates the contents of the NDEF message to be of an unknown type. The type of the NDEF message should be empty.

#define MA_NFC_NDEF_TNF_UNCHANGED   6

Constant for chunked NDEF messages.

#define MA_NFC_NDEF_TNF_RESERVED   7

Reserved constant.

#define MA_NFC_MIFARE_KEY_A   1

The A key for MiFare Classic authentication

#define MA_NFC_MIFARE_KEY_B   2

The B key for MiFare Classic authentication


Function Documentation

int maNFCStart ( void  )

Start listening to NFC events.

Returns:
MA_NFC_NOT_ENABLED if NFC is not enabled on this device, MA_NFC_NOT_AVAILABLE if NFC is not at all available, or 0 otherwise.

References maIOCtl().

void maNFCStop ( void  )

Stop listening to NFC events.

References maIOCtl().

MAHandle maNFCReadTag ( MAHandle  nfcContext)

Reads the next available tag.

Returns:
A zero handle if no tag currently available

References maIOCtl().

void maNFCDestroyTag ( MAHandle  tagHandle)

Destroys the tag. Clients are responsible for calling this function for every corresponding maNFCReadTag.

References maIOCtl().

void maNFCConnectTag ( MAHandle  tagHandle)

Connects to a tag, enabling further I/O operations to be performed on it.

References maIOCtl().

void maNFCCloseTag ( MAHandle  tagHandle)

Closes I/O operations for a tag, disabling further I/O operations to be performed on it.

References maIOCtl().

int maNFCIsType ( MAHandle  tagHandle,
int  type 
)

Determines whether a tag is of a certain type. Use the constants prefixed with MA_NFC_TAG_TYPE_ to see the available tag types.

Returns:
> 0 if the tag is a the specified type, 0 if it is not, and MA_NFC_INVALID_TAG_TYPE if the tag type is not supported by this platform.

References maIOCtl().

MAHandle maNFCGetTypedTag ( MAHandle  tagHandle,
int  type 
)

To be able to call functions tag require the tag to be of a certain type (see maNFCIsType), the tag received must be converted to the proper type (see MA_NFC_TAG_TYPE_* constants). All typed tags returned by this function will be destroyed when the tag used to produce them is destroyed. Ie no explicit destruction of typed tags is necessary (but allowed).

Returns:
A handle if the type was convertable to the specified type.

References maIOCtl().

int maNFCBatchStart ( MAHandle  tagHandle)

Starts a batch operation. No NFC I/O operations will be performed until maBatchCommit has been called. Note that only one active batch per tag is allowed.

Parameters:
Thetag on which to perform the batch operation.
Returns:
A non-zero value if a batch is already started for this tag or if a batch could not be started, 0 otherwise.

References maIOCtl().

void maNFCBatchCommit ( MAHandle  tagHandle)

Asynchronously performs all operations since the last call to maNFCBatchStart. The event delivered will be of the EVENT_TYPE_NFC_BATCH_OP type and with an MANFCEventData containing the tag's handle.

Parameters:
Thehandle to the tag that is in batch mode.

References maIOCtl().

void maNFCBatchRollback ( MAHandle  tagHandle)

Cancels all operations of the current batch.

Parameters:
Thehandle to the tag that is in batch mode.

References maIOCtl().

int maNFCTransceive ( MAHandle  tag,
const void *  src,
int  srcLen,
void *  dst,
int *  dstLen 
)

Sends a message to a tag. The response will come as an EVENT_TYPE_NFC_TAG_DATA_READ event, with the handle set to the handle passed into this method and the result field set to the number of bytes actually read.

Parameters:
tagThe tag to communicate with.
srcThe data to send.
lenThe length of the data to send.
Returns:
0 if the tag can be transceived to, < 0 otherwise.

References maIOCtl().

int maNFCSetReadOnly ( MAHandle  tag)

Makes a tag read-only (this operation cannot be reverted). The response will come as an EVENT_TYPE_NFC_TAG_READ_ONLY event, with the handle set to the handle passed into this method.

Parameters:
tagThe tag to make read only.
Returns:
MA_NFC_INVALID_TAG_TYPE if the handle given as argument cannot be made read-only.

References maIOCtl().

int maNFCIsReadOnly ( MAHandle  tag)

Checks whether a tag is read-only.

Parameters:
tagThe tag to check for read/write permissions.
Returns:
MA_NFC_INVALID_TAG_TYPE if this operation is not applicable, a value > 0 if it is read-only, or 0 if it is read-only.

References maIOCtl().

int maNFCGetSize ( MAHandle  tag)

Returns the capacity/size of a tag.

Parameters:
tagThe tag to get the size from.
Returns:
The size of the tag, or -1 if unknown.

References maIOCtl().

int maNFCGetId ( MAHandle  tag,
void *  dst,
int  len 
)

Returns the (serial) id a tag. This id may or may not be unique depending on the underlying technology. The serial id may also be empty.

Parameters:
tagThe tag to read from.
dstWhere the result should be written to.
lenThe maximum length to write.
Returns:
The number of bytes of the id.

References maIOCtl().

Reads an NDEF message from the given tag, which must be of the MA_NFC_TAG_TYPE_NDEF type. The response will come a an EVENT_TYPE_NFC_TAG_DATA_READ event with the handle set to the handle passed into this method and the result field set to 0 on success and a value < 0 on error. After receiving the event, clients may call maNFCGetNDEFMessage() to get the actual message. If the handle is not an NDEF tag, MA_NFC_INVALID_TAG_TYPE will be returned.

References maIOCtl().

int maNFCWriteNDEFMessage ( MAHandle  tag,
MAHandle  ndefMessage 
)

Writes an NDEF message to the given tag, which must be of the MA_NFC_TAG_TYPE_NDEF or MA_NFC_TAG_TYPE_NDEF_FORMATTABLE type. The response will come a an EVENT_TYPE_NFC_TAG_DATA_WRITE event with the handle set to the handle passed into this method, the result field set to 0 on success and a value < 0 on error, and the dstId field set to the ndefMessage written. If the handle is not an NDEF tag, MA_NFC_INVALID_TAG_TYPE will be returned.

Parameters:
tagThe tag handle to write to
ndefMessageThe message to write

References maIOCtl().

MAHandle maNFCCreateNDEFMessage ( int  recordCount)

Creates a new NDEF message, to be used primarily by

 maNFCWriteDefMessage. 
Parameters:
recordCountThe number of records in the created message
Returns:
The handle to the created NDEF message; clients are responsible for destroying the message.

References maIOCtl().

Gets the NDEF message from a tag, which must be of the MA_NFC_TAG_TYPE_NDEF type. If the handle is not an NDEF tag, MA_NFC_INVALID_TAG_TYPE will be returned. (Please note the difference between an NDEF tag and an NDEF message.)

Returns:
The handle to the NDEF message, which may be subsequently used in NDEF specfic functions, or the zero handle if the tag has no NDEF message associated with it (in which case, clients may call maNFCReadNDEFMessage). IMPORTANT: Once the tag has been destroyed OR if maNFCReadNDEFMessage is called, any NDEF messages previously returned by this function will be destroyed with it and cannot be used.

References maIOCtl().

MAHandle maNFCGetNDEFRecord ( MAHandle  ndefMessage,
int  ix 
)
Returns:
A handle to the ith NDEF record of an NDEF message. If the handle is not an NDEF message, MA_NFC_INVALID_TAG_TYPE will be returned.

References maIOCtl().

int maNFCGetNDEFRecordCount ( MAHandle  ndefMessage)
Returns:
The number of NDEF records in an NDEF message. If the handle is not an NDEF message, MA_NFC_INVALID_TAG_TYPE will be returned.

References maIOCtl().

int maNFCGetNDEFId ( MAHandle  ndefRecord,
void *  dst,
int  len 
)

Reads the variable length id of an NDEF record.

Parameters:
ndefRecordthe handle to the record to read from.
dstWhere the result should be written to.
lenThe maximum length to write.
Returns:
The number of bytes written. If the handle is not an NDEF message record, MA_NFC_INVALID_TAG_TYPE will be returned.

References maIOCtl().

int maNFCGetNDEFPayload ( MAHandle  ndefRecord,
void *  dst,
int  len 
)

Reads the variable length payload of an NDEF record.

Parameters:
ndefRecordthe handle to the record to read from.
dstWhere the result should be written to.
lenThe maximum length to write.
Returns:
The number of bytes written. If the handle is not an NDEF message record, MA_NFC_INVALID_TAG_TYPE will be returned.

References maIOCtl().

int maNFCGetNDEFTnf ( MAHandle  ndefRecord)

Returns the 3-bit TNF of an NDEF record. If the handle is not an NDEF message record, MA_NFC_INVALID_TAG_TYPE will be returned.

References maIOCtl().

int maNFCGetNDEFType ( MAHandle  ndefRecord,
void *  dst,
int  len 
)

Returns the variable length type field of an NDEF record.

Parameters:
ndefRecordthe handle to the record to read from.
dstWhere the result should be written to.
lenThe maximum length to write.
Returns:
The number of bytes written. If the handle is not an NDEF message record, MA_NFC_INVALID_TAG_TYPE will be returned.

References maIOCtl().

int maNFCSetNDEFId ( MAHandle  ndefRecord,
const void *  dst,
int  len 
)

Sets the variable length id of an NDEF record. If the handle is not an NDEF message record, MA_NFC_INVALID_TAG_TYPE will be returned.

References maIOCtl().

int maNFCSetNDEFPayload ( MAHandle  ndefRecord,
const void *  dst,
int  len 
)

Sets the variable length payload of an NDEF record. If the handle is not NDEF message record, MA_NFC_INVALID_TAG_TYPE will be returned.

References maIOCtl().

int maNFCSetNDEFTnf ( MAHandle  ndefRecord,
int  tnf 
)

Sets the 3-bit TNF of an NDEF record, If the handle is not NDEF message record, MA_NFC_INVALID_TAG_TYPE will be returned.

References maIOCtl().

int maNFCSetNDEFType ( MAHandle  ndefRecord,
const void *  dst,
int  len 
)

Returns the variable length type field of an NDEF record. If the handle is not NDEF message record, MA_NFC_INVALID_TAG_TYPE will be returned.

References maIOCtl().

int maNFCAuthenticateMifareSector ( MAHandle  tagHandle,
int  keyType,
int  sectorIndex,
const void *  keySrc,
int  keyLen 
)

Authenticates a MIFARE Classic tag using the A or B key. Authentication must take place before reading/writing to a certain sector. The operation is asyncronous and will result in an EVENT_TYPE_NFC_TAG_AUTH_COMPLETE event, unless part of a batch operation.

Parameters:
tagHandleThe tag to authenticate
keyTypeEither MA_NFC_MIFARE_KEY_A or MA_NFC_MIFARE_KEY_B.
sectorIndexThe sector to authenticate
keySrcThe address to the key to authenticate with
keyLenThe length of the key to authenticate with If the handle is not a Mifare Classic tag, MA_NFC_INVALID_TAG_TYPE will be returned.

References maIOCtl().

int maNFCGetMifareSectorCount ( MAHandle  tagHandle)
Returns:
The number of sectors of a MIFARE Classic tag. If the handle is not a Mifare Classic tag, MA_NFC_INVALID_TAG_TYPE will be returned.

References maIOCtl().

int maNFCGetMifareBlockCountInSector ( MAHandle  tagHandle,
int  sector 
)

Returns the number of blocks in a sector of a MIFARE Classic tag.

Parameters:
sectorThe sector to get the number of blocks in.
Returns:
The number of blocks in a given sector. If the handle is not a Mifare Classic tag, MA_NFC_INVALID_TAG_TYPE will be returned.

References maIOCtl().

int maNFCMifareSectorToBlock ( MAHandle  tagHandle,
int  sector 
)

Returns the first block of a sector of a MIFARE Classic tag.

Parameters:
sectorThe sector of which to get the first block.
Returns:
The index of the first block of the sector is returned. If the handle is not a Mifare Classic tag, MA_NFC_INVALID_TAG_TYPE will be returned.

References maIOCtl().

int maNFCReadMifareBlocks ( MAHandle  tagHandle,
int  firstBlock,
void *  dst,
int  len 
)

Reads a number of blocks of a MIFARE Classic tag. The operation is asyncronous and will result in an EVENT_TYPE_NFC_TAG_READ event, unless part of a batch operation.

Parameters:
firstBlockThe first block to read from.
dstThe memory address to write to.
lenThe number of bytes to read. Several blocks may be read, depending on len (A block is 16 bytes). If the handle is not a Mifare Classic tag, MA_NFC_INVALID_TAG_TYPE will be returned.

References maIOCtl().

int maNFCWriteMifareBlocks ( MAHandle  tagHandle,
int  firstBlock,
const void *  dst,
int  len 
)

Writes a number of blocks to a MIFARE Classic tag. The operation is asyncronous and will result in an EVENT_TYPE_NFC_TAG_WRITE event, unless part of a batch operation.

Parameters:
firstBlockThe first block to write to.
dstThe memory address to read from.
lenThe number of bytes to write. Several blocks may be written, depending on len (A block is 16 bytes). If the handle is not a Mifare Classic tag, MA_NFC_INVALID_TAG_TYPE will be returned.

References maIOCtl().

int maNFCReadMifarePages ( MAHandle  tagHandle,
int  firstPage,
void *  dst,
int  len 
)

Reads a number of blocks of a MIFARE Ultralight tag. The operation is asyncronous and will result in an EVENT_TYPE_NFC_TAG_READ event, unless part of a batch operation.

Parameters:
firstBlockThe first block to read from.
dstThe memory address to write to.
lenThe number of bytes to read. Several pages may be read, depending on len (A page is 16 bytes). If the handle is not a Mifare Ultralight tag, MA_NFC_INVALID_TAG_TYPE will be returned.

References maIOCtl().

int maNFCWriteMifarePages ( MAHandle  tagHandle,
int  firstPage,
const void *  dst,
int  len 
)

Writes a number of blocks of a MIFARE Ultralight tag. The operation is asyncronous and will result in an EVENT_TYPE_NFC_TAG_WRITE event, unless part of a batch operation.

Parameters:
firstBlockThe first block to write to.
dstThe memory address to read from.
lenThe number of bytes to write. Several pages may be written, depending on len (A page is 16 bytes). If the handle is not a Mifare Ultralight tag, MA_NFC_INVALID_TAG_TYPE will be returned.

References maIOCtl().

 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines