Abstract interface for managing NFC device data. More...

#include <stddef.h>
#include <stdint.h>
#include <stdbool.h>
#include "protocols/nfc_device_base.h"
#include "protocols/nfc_protocol.h"

Typedefs
typedef struct NfcDevice	NfcDevice
	NfcDevice opaque type definition.

typedef void(*	NfcLoadingCallback) (void *context, bool state)
	Loading callback function signature.

Functions
NfcDevice *	nfc_device_alloc (void)
	Allocate an NfcDevice instance.

void	nfc_device_free (NfcDevice *instance)
	Delete an NfcDevice instance.

void	nfc_device_clear (NfcDevice *instance)
	Clear an NfcDevice instance.

void	nfc_device_reset (NfcDevice *instance)
	Reset an NfcDevice instance.

NfcProtocol	nfc_device_get_protocol (const NfcDevice *instance)
	Get the protocol identifier from an NfcDevice instance.

const NfcDeviceData *	nfc_device_get_data (const NfcDevice *instance, NfcProtocol protocol)
	Get the protocol-specific data from an NfcDevice instance.

const char *	nfc_device_get_protocol_name (NfcProtocol protocol)
	Get the protocol name by its identifier.

const char *	nfc_device_get_name (const NfcDevice *instance, NfcDeviceNameType name_type)
	Get the name of an NfcDevice instance.

const uint8_t *	nfc_device_get_uid (const NfcDevice instance, size_t uid_len)
	Get the unique identifier (UID) of an NfcDevice instance.

bool	nfc_device_set_uid (NfcDevice instance, const uint8_t uid, size_t uid_len)
	Set the unique identifier (UID) of an NfcDevice instance.

void	nfc_device_set_data (NfcDevice instance, NfcProtocol protocol, const NfcDeviceData protocol_data)
	Set the data and protocol of an NfcDevice instance.

void	nfc_device_copy_data (const NfcDevice instance, NfcProtocol protocol, NfcDeviceData protocol_data)
	Copy (export) the data contained in an NfcDevice instance to an outside NfcDeviceData instance.

bool	nfc_device_is_equal_data (const NfcDevice instance, NfcProtocol protocol, const NfcDeviceData protocol_data)
	Check whether an NfcDevice instance holds certain data.

bool	nfc_device_is_equal (const NfcDevice instance, const NfcDevice other)
	Compare two NfcDevice instances to determine whether they are equal.

void	nfc_device_set_loading_callback (NfcDevice instance, NfcLoadingCallback callback, void context)
	Set the loading callback function.

bool	nfc_device_save (NfcDevice instance, const char path)
	Save NFC device data form an NfcDevice instance to a file.

bool	nfc_device_load (NfcDevice instance, const char path)
	Load NFC device data to an NfcDevice instance from a file.

Detailed Description

Abstract interface for managing NFC device data.

Under the hood, it makes use of the protocol-specific functions that each one of them provides and abstracts it with a protocol-independent API.

It does not perform any signal processing, but merely serves as a container with some handy operations such as loading and saving from and to a file.

Typedef Documentation

◆ NfcLoadingCallback

typedef void(* NfcLoadingCallback) (void *context, bool state)

Loading callback function signature.

A function with such signature can be set as a callback to indicate the completion (or a failure) of nfc_device_load() and nfc_device_save() functions.

This facility is commonly used to control GUI elements, such as progress dialogs.

Parameters

[in]	context	user-defined context that was passed in nfc_device_set_loading_callback().
[in]	state	true if the data was loaded successfully, false otherwise.

Function Documentation

◆ nfc_device_alloc()

NfcDevice * nfc_device_alloc ( void )

Allocate an NfcDevice instance.

A newly created instance does not hold any data and thus is considered invalid. The most common use case would be to set its data by calling nfc_device_set_data() right afterwards.

Returns: pointer to the allocated instance.

◆ nfc_device_clear()

void nfc_device_clear ( NfcDevice * instance )

Clear an NfcDevice instance.

All data contained in the instance will be deleted and the instance itself will become invalid as if it was just allocated.

Parameters

[in,out] instance pointer to the instance to be cleared.

◆ nfc_device_copy_data()

void nfc_device_copy_data	(	const NfcDevice *	instance,
		NfcProtocol	protocol,
		NfcDeviceData *	protocol_data )

Copy (export) the data contained in an NfcDevice instance to an outside NfcDeviceData instance.

This function does the inverse of nfc_device_set_data().

The protocol identifier passed as the protocol parameter MUST match the one stored in the instance, otherwise a crash will occur. This is to improve type safety.

Parameters

[in]	instance	pointer to the instance to be copied from.
[in]	protocol	numeric identifier of the instance's protocol.
[out]	protocol_data	pointer to the destination data.

◆ nfc_device_free()

void nfc_device_free ( NfcDevice * instance )

Delete an NfcDevice instance.

Parameters

[in,out] instance pointer to the instance to be deleted.

◆ nfc_device_get_data()

const NfcDeviceData * nfc_device_get_data	(	const NfcDevice *	instance,
		NfcProtocol	protocol )

Get the protocol-specific data from an NfcDevice instance.

The protocol parameter's behaviour is a bit tricky. The function will check whether there is such a protocol somewhere in the protocol hierarchy and return the data exactly from that level.

Example: Call nfc_device_get_data() on an instance with Mf DESFire protocol. The protocol hierarchy will look like the following:

Mf DESFire --> ISO14443-4A --> ISO14443-3A

Thus, the following values of the protocol parameter are valid:

NfcProtocolIso14443_3a
NfcProtocolIso14443_4a
NfcProtocolMfDesfire

and passing them to the call would result in the respective data being returned.

However, supplying a protocol identifier which is not in the hierarchy will result in a crash. This is to improve type safety.

Parameters

instance	pointer to the instance to be queried
protocol	protocol identifier of the data to be retrieved.

Returns: pointer to the instance's data.

◆ nfc_device_get_name()

const char * nfc_device_get_name	(	const NfcDevice *	instance,
		NfcDeviceNameType	name_type )

Get the name of an NfcDevice instance.

The return value may change depending on the instance's internal state and the name_type parameter.

Parameters

[in]	instance	pointer to the instance to be queried.
[in]	name_type	type of the name to be displayed.

Returns: pointer to a statically allocated string containing the device name.

◆ nfc_device_get_protocol()

NfcProtocol nfc_device_get_protocol ( const NfcDevice * instance )

Get the protocol identifier from an NfcDevice instance.

If the instance is invalid, the return value will be NfcProtocolInvalid.

Parameters

[in] instance pointer to the instance to be queried.

Returns: protocol identifier contained in the instance.

◆ nfc_device_get_protocol_name()

const char * nfc_device_get_protocol_name ( NfcProtocol protocol )

Get the protocol name by its identifier.

This function does not require an instance as its return result depends only the protocol identifier.

Parameters

[in] protocol numeric identifier of the protocol in question.

Returns: pointer to a statically allocated string containing the protocol name.

◆ nfc_device_get_uid()

const uint8_t * nfc_device_get_uid	(	const NfcDevice *	instance,
		size_t *	uid_len )

Get the unique identifier (UID) of an NfcDevice instance.

The UID length is protocol-dependent. Additionally, a particular protocol might support several UID lengths.

Parameters

[in]	instance	pointer to the instance to be queried.
[out]	uid_len	pointer to the variable to contain the UID length.

Returns: pointer to the byte array containing the instance's UID.

◆ nfc_device_is_equal()

bool nfc_device_is_equal	(	const NfcDevice *	instance,
		const NfcDevice *	other )

Compare two NfcDevice instances to determine whether they are equal.

Parameters

[in]	instance	pointer to the first instance to be compared.
[in]	other	pointer to the second instance to be compared.

Returns: true if both instances are considered equal, false otherwise.

◆ nfc_device_is_equal_data()

bool nfc_device_is_equal_data	(	const NfcDevice *	instance,
		NfcProtocol	protocol,
		const NfcDeviceData *	protocol_data )

Check whether an NfcDevice instance holds certain data.

This function's behaviour is similar to nfc_device_is_equal(), with the difference that it takes NfcProtocol and NfcDeviceData* instead of the second NfcDevice*.

The following code snippets [1] and [2] are equivalent:

[1]

bool is_equal = nfc_device_is_equal(device1, device2);

[2]

NfcProtocol protocol = nfc_device_get_protocol(device2);
const NfcDeviceData* data = nfc_device_get_data(device2, protocol);
bool is_equal = nfc_device_is_equal_data(device1, protocol, data);

Parameters

[in]	instance	pointer to the instance to be compared.
[in]	protocol	protocol identifier of the data to be compared.
[in]	protocol_data	pointer to the NFC device data to be compared.

Returns: true if the instance is of the right type and the data matches, false otherwise.

◆ nfc_device_load()

bool nfc_device_load	(	NfcDevice *	instance,
		const char *	path )

Load NFC device data to an NfcDevice instance from a file.

Parameters

[in,out]	instance	pointer to the instance to be loaded into.
[in]	path	pointer to a character string with a full file path.

Returns: true if the data was successfully loaded, false otherwise.

◆ nfc_device_reset()

void nfc_device_reset ( NfcDevice * instance )

Reset an NfcDevice instance.

The data contained in the instance will be reset according to the protocol-defined procedure. Unlike the nfc_device_clear() function, the instance will remain valid.

Parameters

[in,out] instance pointer to the instance to be reset.

◆ nfc_device_save()

bool nfc_device_save	(	NfcDevice *	instance,
		const char *	path )

Save NFC device data form an NfcDevice instance to a file.

Parameters

[in]	instance	pointer to the instance to be saved.
[in]	path	pointer to a character string with a full file path.

Returns: true if the data was successfully saved, false otherwise.

◆ nfc_device_set_data()

void nfc_device_set_data	(	NfcDevice *	instance,
		NfcProtocol	protocol,
		const NfcDeviceData *	protocol_data )

Set the data and protocol of an NfcDevice instance.

Any data previously contained in the instance will be deleted.

Parameters

[in,out]	instance	pointer to the instance to be modified.
[in]	protocol	numeric identifier of the data's protocol.
[in]	protocol_data	pointer to the protocol-specific data.

◆ nfc_device_set_loading_callback()

void nfc_device_set_loading_callback	(	NfcDevice *	instance,
		NfcLoadingCallback	callback,
		void *	context )

Set the loading callback function.

Parameters

[in,out]	instance	pointer to the instance to be modified.
[in]	callback	pointer to a function to be called when the load operation completes.
[in]	context	pointer to a user-specific context (will be passed to the callback).

◆ nfc_device_set_uid()

bool nfc_device_set_uid	(	NfcDevice *	instance,
		const uint8_t *	uid,
		size_t	uid_len )

Set the unique identifier (UID) of an NfcDevice instance.

The UID length must be supported by the instance's protocol.

Parameters

[in,out]	instance	pointer to the instance to be modified.
[in]	uid	pointer to the byte array containing the new UID.
[in]	uid_len	length of the UID.

Returns: true if the UID was valid and set, false otherwise.

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ NfcLoadingCallback

Function Documentation

◆ nfc_device_alloc()

◆ nfc_device_clear()

◆ nfc_device_copy_data()

◆ nfc_device_free()

◆ nfc_device_get_data()

◆ nfc_device_get_name()

◆ nfc_device_get_protocol()

◆ nfc_device_get_protocol_name()

◆ nfc_device_get_uid()

◆ nfc_device_is_equal()

◆ nfc_device_is_equal_data()

◆ nfc_device_load()

◆ nfc_device_reset()

◆ nfc_device_save()

◆ nfc_device_set_data()

◆ nfc_device_set_loading_callback()

◆ nfc_device_set_uid()