libnfc 1.8.0
nfc.h
Go to the documentation of this file.
1/*-
2 * Free/Libre Near Field Communication (NFC) library
3 *
4 * Libnfc historical contributors:
5 * Copyright (C) 2009 Roel Verdult
6 * Copyright (C) 2009-2013 Romuald Conty
7 * Copyright (C) 2010-2012 Romain Tartière
8 * Copyright (C) 2010-2013 Philippe Teuwen
9 * Copyright (C) 2012-2013 Ludovic Rousseau
10 * See AUTHORS file for a more comprehensive list of contributors.
11 * Additional contributors of this file:
12 *
13 * This program is free software: you can redistribute it and/or modify it
14 * under the terms of the GNU Lesser General Public License as published by the
15 * Free Software Foundation, either version 3 of the License, or (at your
16 * option) any later version.
17 *
18 * This program is distributed in the hope that it will be useful, but WITHOUT
19 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
20 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
21 * more details.
22 *
23 * You should have received a copy of the GNU Lesser General Public License
24 * along with this program. If not, see <http://www.gnu.org/licenses/>
25 */
26
34#ifndef _LIBNFC_H_
35# define _LIBNFC_H_
36
37# include <stdint.h>
38# include <stdbool.h>
39
40# ifdef _WIN32
41/* Windows platform */
42# ifndef _WINDLL
43/* CMake compilation */
44# ifdef nfc_EXPORTS
45# define NFC_EXPORT __declspec(dllexport)
46# else
47/* nfc_EXPORTS */
48# define NFC_EXPORT __declspec(dllimport)
49# endif
50/* nfc_EXPORTS */
51# else
52/* _WINDLL */
53/* Manual makefile */
54# define NFC_EXPORT
55# endif
56/* _WINDLL */
57# else
58/* _WIN32 */
59# define NFC_EXPORT
60# endif
61/* _WIN32 */
62
63# include <nfc/nfc-types.h>
64
65# ifndef __has_attribute
66# define __has_attribute(x) 0
67# endif
68
69# if __has_attribute(nonnull) || defined(__GNUC__)
70# define __has_attribute_nonnull 1
71# endif
72
73# if __has_attribute_nonnull
74# define ATTRIBUTE_NONNULL( param ) __attribute__((nonnull (param)))
75# else
76# define ATTRIBUTE_NONNULL( param )
77# endif
78
79# ifdef __cplusplus
80extern "C" {
81# endif // __cplusplus
82
83/* Library initialization/deinitialization */
84NFC_EXPORT void nfc_init(nfc_context **context) ATTRIBUTE_NONNULL(1);
85NFC_EXPORT void nfc_exit(nfc_context *context) ATTRIBUTE_NONNULL(1);
86NFC_EXPORT int nfc_register_driver(const nfc_driver *driver);
87
88/* NFC Device/Hardware manipulation */
89NFC_EXPORT nfc_device *nfc_open(nfc_context *context, const nfc_connstring connstring) ATTRIBUTE_NONNULL(1);
90NFC_EXPORT void nfc_close(nfc_device *pnd);
91NFC_EXPORT int nfc_abort_command(nfc_device *pnd);
92NFC_EXPORT size_t nfc_list_devices(nfc_context *context, nfc_connstring connstrings[], size_t connstrings_len) ATTRIBUTE_NONNULL(1);
93NFC_EXPORT int nfc_idle(nfc_device *pnd);
94
95/* NFC initiator: act as "reader" */
96NFC_EXPORT int nfc_initiator_init(nfc_device *pnd);
98NFC_EXPORT int nfc_initiator_select_passive_target(nfc_device *pnd, const nfc_modulation nm, const uint8_t *pbtInitData, const size_t szInitData, nfc_target *pnt);
99NFC_EXPORT int nfc_initiator_list_passive_targets(nfc_device *pnd, const nfc_modulation nm, nfc_target ant[], const size_t szTargets);
100NFC_EXPORT int nfc_initiator_poll_target(nfc_device *pnd, const nfc_modulation *pnmTargetTypes, const size_t szTargetTypes, const uint8_t uiPollNr, const uint8_t uiPeriod, nfc_target *pnt);
101NFC_EXPORT int nfc_initiator_select_dep_target(nfc_device *pnd, const nfc_dep_mode ndm, const nfc_baud_rate nbr, const nfc_dep_info *pndiInitiator, nfc_target *pnt, const int timeout);
102NFC_EXPORT int nfc_initiator_poll_dep_target(nfc_device *pnd, const nfc_dep_mode ndm, const nfc_baud_rate nbr, const nfc_dep_info *pndiInitiator, nfc_target *pnt, const int timeout);
103NFC_EXPORT int nfc_initiator_deselect_target(nfc_device *pnd);
104NFC_EXPORT int nfc_initiator_transceive_bytes(nfc_device *pnd, const uint8_t *pbtTx, const size_t szTx, uint8_t *pbtRx, const size_t szRx, int timeout);
105NFC_EXPORT int nfc_initiator_transceive_bits(nfc_device *pnd, const uint8_t *pbtTx, const size_t szTxBits, const uint8_t *pbtTxPar, uint8_t *pbtRx, const size_t szRx, uint8_t *pbtRxPar);
106NFC_EXPORT int nfc_initiator_transceive_bytes_timed(nfc_device *pnd, const uint8_t *pbtTx, const size_t szTx, uint8_t *pbtRx, const size_t szRx, uint32_t *cycles);
107NFC_EXPORT int nfc_initiator_transceive_bits_timed(nfc_device *pnd, const uint8_t *pbtTx, const size_t szTxBits, const uint8_t *pbtTxPar, uint8_t *pbtRx, const size_t szRx, uint8_t *pbtRxPar, uint32_t *cycles);
108NFC_EXPORT int nfc_initiator_target_is_present(nfc_device *pnd, const nfc_target *pnt);
109
110/* NFC target: act as tag (i.e. MIFARE Classic) or NFC target device. */
111NFC_EXPORT int nfc_target_init(nfc_device *pnd, nfc_target *pnt, uint8_t *pbtRx, const size_t szRx, int timeout);
112NFC_EXPORT int nfc_target_send_bytes(nfc_device *pnd, const uint8_t *pbtTx, const size_t szTx, int timeout);
113NFC_EXPORT int nfc_target_receive_bytes(nfc_device *pnd, uint8_t *pbtRx, const size_t szRx, int timeout);
114NFC_EXPORT int nfc_target_send_bits(nfc_device *pnd, const uint8_t *pbtTx, const size_t szTxBits, const uint8_t *pbtTxPar);
115NFC_EXPORT int nfc_target_receive_bits(nfc_device *pnd, uint8_t *pbtRx, const size_t szRx, uint8_t *pbtRxPar);
116
117/* Error reporting */
118NFC_EXPORT const char *nfc_strerror(const nfc_device *pnd);
119NFC_EXPORT int nfc_strerror_r(const nfc_device *pnd, char *buf, size_t buflen);
120NFC_EXPORT void nfc_perror(const nfc_device *pnd, const char *s);
121NFC_EXPORT int nfc_device_get_last_error(const nfc_device *pnd);
122
123/* Special data accessors */
124NFC_EXPORT const char *nfc_device_get_name(nfc_device *pnd);
125NFC_EXPORT const char *nfc_device_get_connstring(nfc_device *pnd);
126NFC_EXPORT int nfc_device_get_supported_modulation(nfc_device *pnd, const nfc_mode mode, const nfc_modulation_type **const supported_mt);
127NFC_EXPORT int nfc_device_get_supported_baud_rate(nfc_device *pnd, const nfc_modulation_type nmt, const nfc_baud_rate **const supported_br);
128NFC_EXPORT int nfc_device_get_supported_baud_rate_target_mode(nfc_device *pnd, const nfc_modulation_type nmt, const nfc_baud_rate **const supported_br);
129
130/* Properties accessors */
131NFC_EXPORT int nfc_device_set_property_int(nfc_device *pnd, const nfc_property property, const int value);
132NFC_EXPORT int nfc_device_set_property_bool(nfc_device *pnd, const nfc_property property, const bool bEnable);
133
134/* Misc. functions */
135NFC_EXPORT void iso14443a_crc(uint8_t *pbtData, size_t szLen, uint8_t *pbtCrc);
136NFC_EXPORT void iso14443a_crc_append(uint8_t *pbtData, size_t szLen);
137NFC_EXPORT void iso14443b_crc(uint8_t *pbtData, size_t szLen, uint8_t *pbtCrc);
138NFC_EXPORT void iso14443b_crc_append(uint8_t *pbtData, size_t szLen);
139NFC_EXPORT uint8_t *iso14443a_locate_historical_bytes(uint8_t *pbtAts, size_t szAts, size_t *pszTk);
140
141NFC_EXPORT void nfc_free(void *p);
142NFC_EXPORT const char *nfc_version(void);
143NFC_EXPORT int nfc_device_get_information_about(nfc_device *pnd, char **buf);
144
145/* String converter functions */
146NFC_EXPORT const char *str_nfc_modulation_type(const nfc_modulation_type nmt);
147NFC_EXPORT const char *str_nfc_baud_rate(const nfc_baud_rate nbr);
148NFC_EXPORT int str_nfc_target(char **buf, const nfc_target *pnt, bool verbose);
149
150/* Error codes */
155#define NFC_SUCCESS 0
160#define NFC_EIO -1
165#define NFC_EINVARG -2
170#define NFC_EDEVNOTSUPP -3
175#define NFC_ENOTSUCHDEV -4
180#define NFC_EOVFLOW -5
185#define NFC_ETIMEOUT -6
190#define NFC_EOPABORTED -7
195#define NFC_ENOTIMPL -8
200#define NFC_ETGRELEASED -10
205#define NFC_ERFTRANS -20
210#define NFC_EMFCAUTHFAIL -30
215#define NFC_ESOFT -80
220#define NFC_ECHIP -90
221
222
223# ifdef __cplusplus
224}
225# endif // __cplusplus
226#endif // _LIBNFC_H_
NFC_EXPORT const char * nfc_device_get_name(nfc_device *pnd)
Returns the device name.
Definition: nfc.c:1209
NFC_EXPORT int nfc_device_get_supported_baud_rate_target_mode(nfc_device *pnd, const nfc_modulation_type nmt, const nfc_baud_rate **const supported_br)
Get supported baud rates for target mode.
Definition: nfc.c:1263
NFC_EXPORT const char * nfc_device_get_connstring(nfc_device *pnd)
Returns the device connection string.
Definition: nfc.c:1221
NFC_EXPORT int nfc_device_get_supported_modulation(nfc_device *pnd, const nfc_mode mode, const nfc_modulation_type **const supported_mt)
Get supported modulations.
Definition: nfc.c:1235
NFC_EXPORT int nfc_device_get_supported_baud_rate(nfc_device *pnd, const nfc_modulation_type nmt, const nfc_baud_rate **const supported_br)
Get supported baud rates (initiator mode).
Definition: nfc.c:1249
NFC_EXPORT void nfc_close(nfc_device *pnd)
Close from a NFC device.
Definition: nfc.c:339
NFC_EXPORT int nfc_idle(nfc_device *pnd)
Turn NFC device in idle mode.
Definition: nfc.c:1019
NFC_EXPORT nfc_device * nfc_open(nfc_context *context, const nfc_connstring connstring) ATTRIBUTE_NONNULL(1)
Open a NFC device.
Definition: nfc.c:277
NFC_EXPORT int nfc_abort_command(nfc_device *pnd)
Abort current running command.
Definition: nfc.c:1036
NFC_EXPORT size_t nfc_list_devices(nfc_context *context, nfc_connstring connstrings[], size_t connstrings_len) ATTRIBUTE_NONNULL(1)
Scan for discoverable supported devices (ie. only available for some drivers)
Definition: nfc.c:356
NFC_EXPORT void nfc_perror(const nfc_device *pnd, const char *s)
Display the last error occured on a nfc_device.
Definition: nfc.c:1183
NFC_EXPORT int nfc_strerror_r(const nfc_device *pnd, char *buf, size_t buflen)
Renders the last error in pcStrErrBuf for a maximum size of szBufLen chars.
Definition: nfc.c:1171
NFC_EXPORT int nfc_device_get_last_error(const nfc_device *pnd)
Returns last error occured on a nfc_device.
Definition: nfc.c:1195
NFC_EXPORT const char * nfc_strerror(const nfc_device *pnd)
Return the last error string.
Definition: nfc.c:1148
NFC_EXPORT int nfc_initiator_transceive_bytes(nfc_device *pnd, const uint8_t *pbtTx, const size_t szTx, uint8_t *pbtRx, const size_t szRx, int timeout)
Send data to target then retrieve data from target.
Definition: nfc.c:809
NFC_EXPORT int nfc_initiator_transceive_bits(nfc_device *pnd, const uint8_t *pbtTx, const size_t szTxBits, const uint8_t *pbtTxPar, uint8_t *pbtRx, const size_t szRx, uint8_t *pbtRxPar)
Transceive raw bit-frames to a target.
Definition: nfc.c:852
NFC_EXPORT int nfc_initiator_transceive_bits_timed(nfc_device *pnd, const uint8_t *pbtTx, const size_t szTxBits, const uint8_t *pbtTxPar, uint8_t *pbtRx, const size_t szRx, uint8_t *pbtRxPar, uint32_t *cycles)
Transceive raw bit-frames to a target.
Definition: nfc.c:934
NFC_EXPORT int nfc_initiator_init(nfc_device *pnd)
Initialize NFC device as initiator (reader)
Definition: nfc.c:493
NFC_EXPORT int nfc_initiator_init_secure_element(nfc_device *pnd)
Initialize NFC device as initiator with its secure element as target (reader)
Definition: nfc.c:533
NFC_EXPORT int nfc_initiator_poll_dep_target(nfc_device *pnd, const nfc_dep_mode ndm, const nfc_baud_rate nbr, const nfc_dep_info *pndiInitiator, nfc_target *pnt, const int timeout)
Poll a target and request active or passive mode for D.E.P. (Data Exchange Protocol)
Definition: nfc.c:727
NFC_EXPORT int nfc_initiator_transceive_bytes_timed(nfc_device *pnd, const uint8_t *pbtTx, const size_t szTx, uint8_t *pbtRx, const size_t szRx, uint32_t *cycles)
Send data to target then retrieve data from target.
Definition: nfc.c:888
NFC_EXPORT int nfc_initiator_target_is_present(nfc_device *pnd, const nfc_target *pnt)
Check target presence.
Definition: nfc.c:907
NFC_EXPORT int nfc_initiator_list_passive_targets(nfc_device *pnd, const nfc_modulation nm, nfc_target ant[], const size_t szTargets)
List passive or emulated tags.
Definition: nfc.c:605
NFC_EXPORT int nfc_initiator_select_dep_target(nfc_device *pnd, const nfc_dep_mode ndm, const nfc_baud_rate nbr, const nfc_dep_info *pndiInitiator, nfc_target *pnt, const int timeout)
Select a target and request active or passive mode for D.E.P. (Data Exchange Protocol)
Definition: nfc.c:702
NFC_EXPORT int nfc_initiator_select_passive_target(nfc_device *pnd, const nfc_modulation nm, const uint8_t *pbtInitData, const size_t szInitData, nfc_target *pnt)
Select a passive or emulated tag.
Definition: nfc.c:562
NFC_EXPORT int nfc_initiator_poll_target(nfc_device *pnd, const nfc_modulation *pnmTargetTypes, const size_t szTargetTypes, const uint8_t uiPollNr, const uint8_t uiPeriod, nfc_target *pnt)
Polling for NFC targets.
Definition: nfc.c:672
int nfc_register_driver(const struct nfc_driver *ndr)
Register an NFC device driver with libnfc. This function registers a driver with libnfc,...
Definition: nfc.c:207
NFC_EXPORT void nfc_exit(nfc_context *context) ATTRIBUTE_NONNULL(1)
Deinitialize libnfc. Should be called after closing all open devices and before your application term...
Definition: nfc.c:248
NFC_EXPORT void nfc_init(nfc_context **context) ATTRIBUTE_NONNULL(1)
Initialize libnfc. This function must be called before calling any other libnfc function.
Definition: nfc.c:231
NFC_EXPORT const char * nfc_version(void)
Returns the library version.
Definition: nfc.c:1319
NFC_EXPORT void nfc_free(void *p)
Free buffer allocated by libnfc.
Definition: nfc.c:1334
NFC_EXPORT int nfc_device_get_information_about(nfc_device *pnd, char **buf)
Print information about NFC device.
Definition: nfc.c:1348
NFC_EXPORT int nfc_device_set_property_int(nfc_device *pnd, const nfc_property property, const int value)
Set a device's integer-property value.
Definition: nfc.c:446
NFC_EXPORT int nfc_device_set_property_bool(nfc_device *pnd, const nfc_property property, const bool bEnable)
Set a device's boolean-property value.
Definition: nfc.c:466
NFC_EXPORT int str_nfc_target(char **buf, const nfc_target *pnt, bool verbose)
Convert nfc_target content to string.
Definition: nfc.c:1421
NFC_EXPORT const char * str_nfc_modulation_type(const nfc_modulation_type nmt)
Convert nfc_modulation_type value to string.
Definition: nfc.c:1383
NFC_EXPORT const char * str_nfc_baud_rate(const nfc_baud_rate nbr)
Convert nfc_baud_rate value to string.
Definition: nfc.c:1359
NFC_EXPORT int nfc_target_send_bytes(nfc_device *pnd, const uint8_t *pbtTx, const size_t szTx, int timeout)
Send bytes and APDU frames.
Definition: nfc.c:1057
NFC_EXPORT int nfc_target_send_bits(nfc_device *pnd, const uint8_t *pbtTx, const size_t szTxBits, const uint8_t *pbtTxPar)
Send raw bit-frames.
Definition: nfc.c:1094
NFC_EXPORT int nfc_target_init(nfc_device *pnd, nfc_target *pnt, uint8_t *pbtRx, const size_t szRx, int timeout)
Initialize NFC device as an emulated tag.
Definition: nfc.c:978
NFC_EXPORT int nfc_target_receive_bytes(nfc_device *pnd, uint8_t *pbtRx, const size_t szRx, int timeout)
Receive bytes and APDU frames.
Definition: nfc.c:1077
NFC_EXPORT int nfc_target_receive_bits(nfc_device *pnd, uint8_t *pbtRx, const size_t szRx, uint8_t *pbtRxPar)
Receive bit-frames.
Definition: nfc.c:1116
Define NFC types.
nfc_mode
NFC mode type enumeration.
Definition: nfc-types.h:333
struct nfc_driver nfc_driver
Definition: nfc-types.h:58
nfc_property
Definition: nfc-types.h:68
char nfc_connstring[NFC_BUFSIZE_CONNSTRING]
Definition: nfc-types.h:63
nfc_dep_mode
NFC D.E.P. (Data Exchange Protocol) active/passive mode.
Definition: nfc-types.h:152
nfc_modulation_type
NFC modulation type enumeration.
Definition: nfc-types.h:315
nfc_baud_rate
NFC baud rate enumeration.
Definition: nfc-types.h:303
NFC library context Struct which contains internal options, references, pointers, etc....
Definition: nfc-internal.h:175
NFC target information in D.E.P. (Data Exchange Protocol) see ISO/IEC 18092 (NFCIP-1)
Definition: nfc-types.h:162
NFC device information.
Definition: nfc-internal.h:190
NFC modulation structure.
Definition: nfc-types.h:342
NFC target structure.
Definition: nfc-types.h:351