libnfc  1.7.1
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 <sys/time.h>
38 
39 # include <stdint.h>
40 # include <stdbool.h>
41 
42 # ifdef _WIN32
43 /* Windows platform */
44 # ifndef _WINDLL
45 /* CMake compilation */
46 # ifdef nfc_EXPORTS
47 # define NFC_EXPORT __declspec(dllexport)
48 # else
49 /* nfc_EXPORTS */
50 # define NFC_EXPORT __declspec(dllimport)
51 # endif
52 /* nfc_EXPORTS */
53 # else
54 /* _WINDLL */
55 /* Manual makefile */
56 # define NFC_EXPORT
57 # endif
58 /* _WINDLL */
59 # else
60 /* _WIN32 */
61 # define NFC_EXPORT
62 # endif
63 /* _WIN32 */
64 
65 # include <nfc/nfc-types.h>
66 
67 # ifndef __has_attribute
68 # define __has_attribute(x) 0
69 # endif
70 
71 # if __has_attribute(nonnull) || defined(__GNUC__)
72 # define __has_attribute_nonnull 1
73 # endif
74 
75 # if __has_attribute_nonnull
76 # define ATTRIBUTE_NONNULL( param ) __attribute__((nonnull (param)))
77 # else
78 # define ATTRIBUTE_NONNULL( param )
79 # endif
80 
81 # ifdef __cplusplus
82 extern "C" {
83 # endif // __cplusplus
84 
85 /* Library initialization/deinitialization */
86 NFC_EXPORT void nfc_init(nfc_context **context) ATTRIBUTE_NONNULL(1);
87 NFC_EXPORT void nfc_exit(nfc_context *context) ATTRIBUTE_NONNULL(1);
88 NFC_EXPORT int nfc_register_driver(const nfc_driver *driver);
89 
90 /* NFC Device/Hardware manipulation */
91 NFC_EXPORT nfc_device *nfc_open(nfc_context *context, const nfc_connstring connstring) ATTRIBUTE_NONNULL(1);
92 NFC_EXPORT void nfc_close(nfc_device *pnd);
93 NFC_EXPORT int nfc_abort_command(nfc_device *pnd);
94 NFC_EXPORT size_t nfc_list_devices(nfc_context *context, nfc_connstring connstrings[], size_t connstrings_len) ATTRIBUTE_NONNULL(1);
95 NFC_EXPORT int nfc_idle(nfc_device *pnd);
96 
97 /* NFC initiator: act as "reader" */
98 NFC_EXPORT int nfc_initiator_init(nfc_device *pnd);
100 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);
101 NFC_EXPORT int nfc_initiator_list_passive_targets(nfc_device *pnd, const nfc_modulation nm, nfc_target ant[], const size_t szTargets);
102 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);
103 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);
104 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);
105 NFC_EXPORT int nfc_initiator_deselect_target(nfc_device *pnd);
106 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);
107 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);
108 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);
109 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);
110 NFC_EXPORT int nfc_initiator_target_is_present(nfc_device *pnd, const nfc_target *pnt);
111 
112 /* NFC target: act as tag (i.e. MIFARE Classic) or NFC target device. */
113 NFC_EXPORT int nfc_target_init(nfc_device *pnd, nfc_target *pnt, uint8_t *pbtRx, const size_t szRx, int timeout);
114 NFC_EXPORT int nfc_target_send_bytes(nfc_device *pnd, const uint8_t *pbtTx, const size_t szTx, int timeout);
115 NFC_EXPORT int nfc_target_receive_bytes(nfc_device *pnd, uint8_t *pbtRx, const size_t szRx, int timeout);
116 NFC_EXPORT int nfc_target_send_bits(nfc_device *pnd, const uint8_t *pbtTx, const size_t szTxBits, const uint8_t *pbtTxPar);
117 NFC_EXPORT int nfc_target_receive_bits(nfc_device *pnd, uint8_t *pbtRx, const size_t szRx, uint8_t *pbtRxPar);
118 
119 /* Error reporting */
120 NFC_EXPORT const char *nfc_strerror(const nfc_device *pnd);
121 NFC_EXPORT int nfc_strerror_r(const nfc_device *pnd, char *buf, size_t buflen);
122 NFC_EXPORT void nfc_perror(const nfc_device *pnd, const char *s);
123 NFC_EXPORT int nfc_device_get_last_error(const nfc_device *pnd);
124 
125 /* Special data accessors */
126 NFC_EXPORT const char *nfc_device_get_name(nfc_device *pnd);
127 NFC_EXPORT const char *nfc_device_get_connstring(nfc_device *pnd);
128 NFC_EXPORT int nfc_device_get_supported_modulation(nfc_device *pnd, const nfc_mode mode, const nfc_modulation_type **const supported_mt);
129 NFC_EXPORT int nfc_device_get_supported_baud_rate(nfc_device *pnd, const nfc_modulation_type nmt, const nfc_baud_rate **const supported_br);
130 
131 /* Properties accessors */
132 NFC_EXPORT int nfc_device_set_property_int(nfc_device *pnd, const nfc_property property, const int value);
133 NFC_EXPORT int nfc_device_set_property_bool(nfc_device *pnd, const nfc_property property, const bool bEnable);
134 
135 /* Misc. functions */
136 NFC_EXPORT void iso14443a_crc(uint8_t *pbtData, size_t szLen, uint8_t *pbtCrc);
137 NFC_EXPORT void iso14443a_crc_append(uint8_t *pbtData, size_t szLen);
138 NFC_EXPORT void iso14443b_crc(uint8_t *pbtData, size_t szLen, uint8_t *pbtCrc);
139 NFC_EXPORT void iso14443b_crc_append(uint8_t *pbtData, size_t szLen);
140 NFC_EXPORT uint8_t *iso14443a_locate_historical_bytes(uint8_t *pbtAts, size_t szAts, size_t *pszTk);
141 
142 NFC_EXPORT void nfc_free(void *p);
143 NFC_EXPORT const char *nfc_version(void);
144 NFC_EXPORT int nfc_device_get_information_about(nfc_device *pnd, char **buf);
145 
146 /* String converter functions */
147 NFC_EXPORT const char *str_nfc_modulation_type(const nfc_modulation_type nmt);
148 NFC_EXPORT const char *str_nfc_baud_rate(const nfc_baud_rate nbr);
149 NFC_EXPORT int str_nfc_target(char **buf, const nfc_target *pnt, bool verbose);
150 
151 /* Error codes */
156 #define NFC_SUCCESS 0
157 
161 #define NFC_EIO -1
162 
166 #define NFC_EINVARG -2
167 
171 #define NFC_EDEVNOTSUPP -3
172 
176 #define NFC_ENOTSUCHDEV -4
177 
181 #define NFC_EOVFLOW -5
182 
186 #define NFC_ETIMEOUT -6
187 
191 #define NFC_EOPABORTED -7
192 
196 #define NFC_ENOTIMPL -8
197 
201 #define NFC_ETGRELEASED -10
202 
206 #define NFC_ERFTRANS -20
207 
211 #define NFC_EMFCAUTHFAIL -30
212 
216 #define NFC_ESOFT -80
217 
221 #define NFC_ECHIP -90
222 
223 
224 # ifdef __cplusplus
225 }
226 # endif // __cplusplus
227 #endif // _LIBNFC_H_
nfc_initiator_init
NFC_EXPORT int nfc_initiator_init(nfc_device *pnd)
Initialize NFC device as initiator (reader)
Definition: nfc.c:452
nfc_init
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:192
nfc_context
NFC library context Struct which contains internal options, references, pointers, etc....
Definition: nfc-internal.h:175
nfc_driver
struct nfc_driver nfc_driver
Definition: nfc-types.h:57
nfc_device
NFC device information.
Definition: nfc-internal.h:190
nfc_version
const NFC_EXPORT char * nfc_version(void)
Returns the library version.
Definition: nfc.c:1218
nfc_target_init
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:933
nfc_device_get_supported_modulation
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:1190
nfc_dep_info
NFC target information in D.E.P. (Data Exchange Protocol) see ISO/IEC 18092 (NFCIP-1)
Definition: nfc-types.h:161
nfc_initiator_poll_dep_target
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:682
nfc_initiator_list_passive_targets
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:561
nfc_initiator_poll_target
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:627
nfc_exit
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:209
nfc_target
NFC target structure.
Definition: nfc-types.h:328
nfc_strerror_r
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:1126
str_nfc_baud_rate
const NFC_EXPORT char * str_nfc_baud_rate(const nfc_baud_rate nbr)
Convert nfc_baud_rate value to string.
Definition: nfc.c:1258
nfc_register_driver
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:170
nfc_target_receive_bits
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:1071
nfc_initiator_select_dep_target
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:657
nfc_initiator_transceive_bits_timed
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:889
nfc_initiator_transceive_bytes
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:764
nfc_device_get_information_about
NFC_EXPORT int nfc_device_get_information_about(nfc_device *pnd, char **buf)
Print information about NFC device.
Definition: nfc.c:1247
nfc_dep_mode
nfc_dep_mode
NFC D.E.P. (Data Exchange Protocol) active/passive mode.
Definition: nfc-types.h:151
nfc_initiator_transceive_bits
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:807
nfc_modulation
NFC modulation structure.
Definition: nfc-types.h:319
nfc_connstring
char nfc_connstring[NFC_BUFSIZE_CONNSTRING]
Definition: nfc-types.h:62
nfc_device_get_connstring
const NFC_EXPORT char * nfc_device_get_connstring(nfc_device *pnd)
Returns the device connection string.
Definition: nfc.c:1176
nfc_device_get_name
const NFC_EXPORT char * nfc_device_get_name(nfc_device *pnd)
Returns the device name.
Definition: nfc.c:1164
nfc_strerror
const NFC_EXPORT char * nfc_strerror(const nfc_device *pnd)
Return the last error string.
Definition: nfc.c:1103
nfc_open
NFC_EXPORT nfc_device * nfc_open(nfc_context *context, const nfc_connstring connstring) ATTRIBUTE_NONNULL(1)
Open a NFC device.
Definition: nfc.c:238
nfc_baud_rate
nfc_baud_rate
NFC baud rate enumeration.
Definition: nfc-types.h:283
nfc_initiator_select_passive_target
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:521
nfc_perror
NFC_EXPORT void nfc_perror(const nfc_device *pnd, const char *s)
Display the last error occured on a nfc_device.
Definition: nfc.c:1138
nfc_list_devices
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:317
nfc_initiator_init_secure_element
NFC_EXPORT int nfc_initiator_init_secure_element(nfc_device *pnd)
Initialize NFC device as initiator with its secure element initiator (reader)
Definition: nfc.c:492
nfc_target_send_bits
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:1049
nfc_initiator_transceive_bytes_timed
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:843
nfc_abort_command
NFC_EXPORT int nfc_abort_command(nfc_device *pnd)
Abort current running command.
Definition: nfc.c:991
nfc_modulation_type
nfc_modulation_type
NFC modulation type enumeration.
Definition: nfc-types.h:295
nfc_device_set_property_int
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:407
nfc_close
NFC_EXPORT void nfc_close(nfc_device *pnd)
Close from a NFC device.
Definition: nfc.c:300
nfc_device_get_last_error
NFC_EXPORT int nfc_device_get_last_error(const nfc_device *pnd)
Returns last error occured on a nfc_device.
Definition: nfc.c:1150
nfc_mode
nfc_mode
NFC mode type enumeration.
Definition: nfc-types.h:310
str_nfc_target
NFC_EXPORT int str_nfc_target(char **buf, const nfc_target *pnt, bool verbose)
Convert nfc_modulation_type value to string.
Definition: nfc.c:1328
nfc_idle
NFC_EXPORT int nfc_idle(nfc_device *pnd)
Turn NFC device in idle mode.
Definition: nfc.c:974
nfc_target_receive_bytes
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:1032
nfc-types.h
Define NFC types.
nfc_target_send_bytes
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:1012
nfc_property
nfc_property
Definition: nfc-types.h:67
nfc_device_set_property_bool
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:426
str_nfc_modulation_type
const NFC_EXPORT char * str_nfc_modulation_type(const nfc_modulation_type nmt)
Convert nfc_modulation_type value to string.
Definition: nfc.c:1287
nfc_initiator_target_is_present
NFC_EXPORT int nfc_initiator_target_is_present(nfc_device *pnd, const nfc_target *pnt)
Check target presence.
Definition: nfc.c:862
nfc_device_get_supported_baud_rate
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.
Definition: nfc.c:1204
nfc_free
NFC_EXPORT void nfc_free(void *p)
Free buffer allocated by libnfc.
Definition: nfc.c:1233