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
80 extern "C" {
81 # endif // __cplusplus
82 
83 /* Library initialization/deinitialization */
84 NFC_EXPORT void nfc_init(nfc_context **context) ATTRIBUTE_NONNULL(1);
85 NFC_EXPORT void nfc_exit(nfc_context *context) ATTRIBUTE_NONNULL(1);
86 NFC_EXPORT int nfc_register_driver(const nfc_driver *driver);
87 
88 /* NFC Device/Hardware manipulation */
89 NFC_EXPORT nfc_device *nfc_open(nfc_context *context, const nfc_connstring connstring) ATTRIBUTE_NONNULL(1);
90 NFC_EXPORT void nfc_close(nfc_device *pnd);
91 NFC_EXPORT int nfc_abort_command(nfc_device *pnd);
92 NFC_EXPORT size_t nfc_list_devices(nfc_context *context, nfc_connstring connstrings[], size_t connstrings_len) ATTRIBUTE_NONNULL(1);
93 NFC_EXPORT int nfc_idle(nfc_device *pnd);
94 
95 /* NFC initiator: act as "reader" */
96 NFC_EXPORT int nfc_initiator_init(nfc_device *pnd);
98 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);
99 NFC_EXPORT int nfc_initiator_list_passive_targets(nfc_device *pnd, const nfc_modulation nm, nfc_target ant[], const size_t szTargets);
100 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);
101 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);
102 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);
103 NFC_EXPORT int nfc_initiator_deselect_target(nfc_device *pnd);
104 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);
105 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);
106 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);
107 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);
108 NFC_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. */
111 NFC_EXPORT int nfc_target_init(nfc_device *pnd, nfc_target *pnt, uint8_t *pbtRx, const size_t szRx, int timeout);
112 NFC_EXPORT int nfc_target_send_bytes(nfc_device *pnd, const uint8_t *pbtTx, const size_t szTx, int timeout);
113 NFC_EXPORT int nfc_target_receive_bytes(nfc_device *pnd, uint8_t *pbtRx, const size_t szRx, int timeout);
114 NFC_EXPORT int nfc_target_send_bits(nfc_device *pnd, const uint8_t *pbtTx, const size_t szTxBits, const uint8_t *pbtTxPar);
115 NFC_EXPORT int nfc_target_receive_bits(nfc_device *pnd, uint8_t *pbtRx, const size_t szRx, uint8_t *pbtRxPar);
116 
117 /* Error reporting */
118 NFC_EXPORT const char *nfc_strerror(const nfc_device *pnd);
119 NFC_EXPORT int nfc_strerror_r(const nfc_device *pnd, char *buf, size_t buflen);
120 NFC_EXPORT void nfc_perror(const nfc_device *pnd, const char *s);
121 NFC_EXPORT int nfc_device_get_last_error(const nfc_device *pnd);
122 
123 /* Special data accessors */
124 NFC_EXPORT const char *nfc_device_get_name(nfc_device *pnd);
125 NFC_EXPORT const char *nfc_device_get_connstring(nfc_device *pnd);
126 NFC_EXPORT int nfc_device_get_supported_modulation(nfc_device *pnd, const nfc_mode mode, const nfc_modulation_type **const supported_mt);
127 NFC_EXPORT int nfc_device_get_supported_baud_rate(nfc_device *pnd, const nfc_modulation_type nmt, const nfc_baud_rate **const supported_br);
128 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);
129 
130 /* Properties accessors */
131 NFC_EXPORT int nfc_device_set_property_int(nfc_device *pnd, const nfc_property property, const int value);
132 NFC_EXPORT int nfc_device_set_property_bool(nfc_device *pnd, const nfc_property property, const bool bEnable);
133 
134 /* Misc. functions */
135 NFC_EXPORT void iso14443a_crc(uint8_t *pbtData, size_t szLen, uint8_t *pbtCrc);
136 NFC_EXPORT void iso14443a_crc_append(uint8_t *pbtData, size_t szLen);
137 NFC_EXPORT void iso14443b_crc(uint8_t *pbtData, size_t szLen, uint8_t *pbtCrc);
138 NFC_EXPORT void iso14443b_crc_append(uint8_t *pbtData, size_t szLen);
139 NFC_EXPORT uint8_t *iso14443a_locate_historical_bytes(uint8_t *pbtAts, size_t szAts, size_t *pszTk);
140 
141 NFC_EXPORT void nfc_free(void *p);
142 NFC_EXPORT const char *nfc_version(void);
143 NFC_EXPORT int nfc_device_get_information_about(nfc_device *pnd, char **buf);
144 
145 /* String converter functions */
146 NFC_EXPORT const char *str_nfc_modulation_type(const nfc_modulation_type nmt);
147 NFC_EXPORT const char *str_nfc_baud_rate(const nfc_baud_rate nbr);
148 NFC_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 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 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 const char * nfc_device_get_connstring(nfc_device *pnd)
Returns the device connection string.
Definition: nfc.c:1221
NFC_EXPORT const char * nfc_device_get_name(nfc_device *pnd)
Returns the device name.
Definition: nfc.c:1209
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 const char * nfc_strerror(const nfc_device *pnd)
Return the last error string.
Definition: nfc.c:1148
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 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_baud_rate(const nfc_baud_rate nbr)
Convert nfc_baud_rate value to string.
Definition: nfc.c:1359
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 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