nfc_poller.h File Reference

NFC card reading library. More...

#include <nfc/protocols/nfc_generic_event.h>
#include <nfc/protocols/nfc_device_base.h>

Go to the source code of this file.

Data Structures
struct	NfcGenericEventEx
	Extended generic Nfc event type. More...

Typedefs
typedef struct NfcPoller	NfcPoller
	NfcPoller opaque type definition.
typedef NfcCommand(*	NfcGenericCallbackEx) (NfcGenericEventEx event, void *context)
	Extended generic Nfc event callback type.

Functions
NfcPoller *	nfc_poller_alloc (Nfc *nfc, NfcProtocol protocol)
	Allocate an NfcPoller instance.
void	nfc_poller_free (NfcPoller *instance)
	Delete an NfcPoller instance.
void	nfc_poller_start (NfcPoller *instance, NfcGenericCallback callback, void *context)
	Start an NfcPoller instance.
void	nfc_poller_start_ex (NfcPoller *instance, NfcGenericCallbackEx callback, void *context)
	Start an NfcPoller instance in extended mode.
void	nfc_poller_stop (NfcPoller *instance)
	Stop an NfcPoller instance.
bool	nfc_poller_detect (NfcPoller *instance)
	Detect whether there is a card supporting a particular protocol in the vicinity.
NfcProtocol	nfc_poller_get_protocol (const NfcPoller *instance)
	Get the protocol identifier an NfcPoller instance was created with.
const NfcDeviceData *	nfc_poller_get_data (const NfcPoller *instance)
	Get the data that was that was gathered during the reading process.

Detailed Description

NFC card reading library.

Once started, it will try to activate and read a card using the designated protocol, which is usually obtained by creating and starting an NfcScanner first.

See also

nfc_scanner.h

When running, NfcPoller will generate events that the calling code must handle by providing a callback function. The events passed to the callback are protocol-specific and may include errors, state changes, data reception, special function requests and more.

Typedef Documentation

NfcGenericCallbackEx

typedef NfcCommand(* NfcGenericCallbackEx) (NfcGenericEventEx event, void *context)

Extended generic Nfc event callback type.

A function of this type must be passed as the callback parameter upon extended start of a poller.

Parameters

[in]	event	Nfc extended generic event, passed by value, complete with protocol type and data.
[in,out]	context	pointer to the user-specific context (set when starting a poller/listener instance).

Returns

the command which the event producer must execute.

Function Documentation

nfc_poller_alloc()

NfcPoller * nfc_poller_alloc	(	Nfc *	nfc,
		NfcProtocol	protocol )

Allocate an NfcPoller instance.

Parameters

[in]	nfc	pointer to an Nfc instance.
[in]	protocol	identifier of the protocol to be used.

Returns

pointer to an allocated instance.

See also

nfc.h

nfc_poller_detect()

bool nfc_poller_detect

(

NfcPoller *

instance

)

Detect whether there is a card supporting a particular protocol in the vicinity.

The behaviour of this function is protocol-defined, in general, it will do whatever is necessary to determine whether a card supporting the current protocol is in the vicinity and whether it is functioning normally.

It is used automatically inside NfcScanner, so there is usually no need to call it explicitly.

See also

nfc_scanner.h

Parameters

[in,out]

instance

pointer to the instance to perform the detection with.

Returns

true if a supported card was detected, false otherwise.

nfc_poller_free()

void nfc_poller_free

(

NfcPoller *

instance

)

Delete an NfcPoller instance.

Parameters

[in,out]

instance

pointer to the instance to be deleted.

nfc_poller_get_data()

const NfcDeviceData * nfc_poller_get_data

(

const NfcPoller *

instance

)

Get the data that was that was gathered during the reading process.

Parameters

[in]

instance

pointer to the instance to be queried.

Returns

pointer to the NFC device data.

nfc_poller_get_protocol()

NfcProtocol nfc_poller_get_protocol

(

const NfcPoller *

instance

)

Get the protocol identifier an NfcPoller instance was created with.

Parameters

[in]

instance

pointer to the instance to be queried.

Returns

identifier of the protocol used by the instance.

nfc_poller_start()

void nfc_poller_start	(	NfcPoller *	instance,
		NfcGenericCallback	callback,
		void *	context )

Start an NfcPoller instance.

The callback logic is protocol-specific, so it cannot be described here in detail. However, the callback return value ALWAYS determines what the poller should do next: to continue whatever it was doing prior to the callback run or to stop.

Parameters

[in,out]	instance	pointer to the instance to be started.
[in]	callback	pointer to a user-defined callback function which will receive events.
[in]	context	pointer to a user-specific context (will be passed to the callback).

nfc_poller_start_ex()

void nfc_poller_start_ex	(	NfcPoller *	instance,
		NfcGenericCallbackEx	callback,
		void *	context )

Start an NfcPoller instance in extended mode.

When nfc poller is started in extended mode, callback will be called with parent protocol events and protocol instance. This mode enables to make custom poller state machines.

Parameters

[in,out]	instance	pointer to the instance to be started.
[in]	callback	pointer to a user-defined callback function which will receive events.
[in]	context	pointer to a user-specific context (will be passed to the callback).

nfc_poller_stop()

void nfc_poller_stop

(

NfcPoller *

instance

)

Stop an NfcPoller instance.

The reading process can be stopped explicitly (the other way is via the callback return value).

Parameters

[in,out]

instance

pointer to the instance to be stopped.