NXP NFC Reader Library
v4.040.05.011646
|
All Public Functions of the NFC Library. More...
![]() |
Functions | |
phNfcLib_Status_t | phNfcLib_Init (void) |
Initialize the NFC Library. More... | |
phNfcLib_Status_t | phNfcLib_DeInit (void) |
Deinitialize the NFC Library. More... | |
phNfcLib_Status_t | phNfcLib_Activate (uint16_t wTechnologyMask, phNfcLib_PeerInfo_t *peerInfo, pphNfcLib_ErrCallbck ErrCallbck) |
Run the Activation Procedure. More... | |
phNfcLib_Status_t | phNfcLib_Transmit (void *const pTxBuffer, uint16_t wTxBufferLength) |
Send Data to an Activated Peer. More... | |
phNfcLib_Status_t | phNfcLib_Receive (uint8_t *const pRxBuffer, uint16_t *pNumberOfBytes, uint8_t *pMoreDataAvailable) |
Receive Data from an Activated Peer. More... | |
phNfcLib_Status_t | phNfcLib_SetConfig (uint8_t bConfigTag, const uint8_t *pConfigParam, uint16_t wConfigParamLength) |
Set Configuration Parameter. More... | |
phNfcLib_Status_t | phNfcLib_SetConfig_Value (uint8_t bConfigTag, uint32_t dwValue) |
Set Configuration Parameter using a Value. More... | |
phNfcLib_Status_t | phNfcLib_GetConfig (uint8_t bConfigTag, uint8_t *pConfigParam, uint16_t *pConfigParamLength) |
Retrieve a configuration parameter value. More... | |
phNfcLib_Status_t | phNfcLib_Deactivate (uint8_t bDeactivateMode, phNfcLib_PeerInfo_t *peerInfo) |
Deactivate an Activated Peer. More... | |
void * | phNfcLib_GetDataParams (uint16_t wComponent) |
Retrieve the pointer to the dataparams structure of an internal NFC Reader Library component. More... | |
phNfcLib_Status_t | phNfcLib_AsyncAbort (void) |
Used to asynchronously stop HAL waiting for RF event and exit from HAL. More... | |
All Public Functions of the NFC Library.
phNfcLib_Status_t phNfcLib_Init | ( | void | ) |
Initialize the NFC Library.
Calling this function initializes the NFC library including all its relevant protocol and hardware abstraction layers. It also calls the initialization functions for the underlying platform. After calling this function all other functions of the phNfcLib module may be used.
PH_NFCLIB_STATUS_INVALID_STATE | NFC Library had been in a wrong state when calling this function. |
phNfcLib_Status_t phNfcLib_DeInit | ( | void | ) |
Deinitialize the NFC Library.
Calling this function resets all internal structures to its default values, releases all allocated resources and calls DeInit of all underlying layers.
PH_NFCLIB_STATUS_INVALID_STATE | NFC Library had been in a wrong state when calling this function. |
phNfcLib_Status_t phNfcLib_Activate | ( | uint16_t | wTechnologyMask, |
phNfcLib_PeerInfo_t * | peerInfo, | ||
pphNfcLib_ErrCallbck | ErrCallbck | ||
) |
Run the Activation Procedure.
This command starts the activation procedure which in fact implements a discovery loop. This loop performs technology detection (for given technologies using bit mask wTechnologyMask
) and, if a technology has been detected, the activation with the associated peer is performed.
The activation procedure can be configured by calling phNfcLib_SetConfig_Value or phNfcLib_SetConfig and appropriate configuration tags (see nfc_lib_config_tags_activation), for instance PH_NFCLIB_CONFIG_ACTIVATION_BLOCKING. These configuration parameters influence the behavior of the activation procedure. The activation procedure also establishes a logical channel which depends on the configured activation_profile. This channel defines how data is being encapsulated when calling phNfcLib_Transmit or phNfcLib_Receive, respectively.
Once a peer has been activated and a channel could be established peerInfo
is set with peer_info about the peer and the established link. phNfcLib_Transmit and phNfcLib_Receive may then be used in order to perform data exchange over the established link. In order to deactivate an activated peer/connection phNfcLib_Deactivate has to be called.
PH_NFCLIB_STATUS_PEER_ACTIVATION_DONE | Activation procedure could activate a peer and establish a channel. peerInfo holds detailed information about the peer and the associated connection. |
PH_NFCLIB_STATUS_MULTIPLE_PEERS_DETECTED | Activation procedure detected multiple peers in RF field based on the discovery loop macro PHAC_DISCLOOP_CFG_MAX_VICINITY_CARDS_SUPPORTED for Type V and 18000p3m3 and these tag identifiers are returned to user as collision need not be resolved to communicate in case of activation_profile is ISO. Detected a collision and was not able to resolve it in case of activation_profile is EMVCo. |
PH_NFCLIB_STATUS_PEER_ACTIVATION_FAILED | Activation procedure detected a peer/technology but was not able to properly activate it. Example: PH_NFCLIB_ACTIVATION_PROFILE_NFC is the configure profile but peer does not support LLCP. |
PH_NFCLIB_STATUS_NO_PEER_DISCOVERED | In case activation procedure is configured for activation_blocking non-blocking execution and no peer has been detected within one iteration, activation returns with this status code. |
PH_NFCLIB_STATUS_INVALID_STATE | NFC Library had been in a wrong state when calling this function. |
[in] | wTechnologyMask | A bit mask indicating all nfc_lib_definitions_rf_techno activation procedure shall handle during its discovery loop execution. |
[out] | peerInfo | Pointer to a phNfcLib_PeerInfo_t structure, to be allocated by the caller. On successful activation of a peer, activation procedure fills the structure with detailed information. |
[in] | ErrCallbck | Error callback specific to PH_NFCLIB_ACTIVATION_PROFILE_EMVCO to intimate about errors during polling for EMVCo. |
phNfcLib_Status_t phNfcLib_Transmit | ( | void *const | pTxBuffer, |
uint16_t | wTxBufferLength | ||
) |
Send Data to an Activated Peer.
Once a peer has been activated this function can be used to send data to the peer. The channel over which the data is sent to the peer is defined by the configured activation_profile .
Behavior in case of activation_profile is PH_NFCLIB_ACTIVATION_PROFILE_NFC
Behavior in case of activation_profile is PH_NFCLIB_ACTIVATION_PROFILE_ISO
PH_NFCLIB_STATUS_SUCCESS | wTxBufferLength bytes given in pTxBuffer have been successfully sent to the peer. |
PH_NFCLIB_STATUS_BUFFER_OVERFLOW | Received bytes could not be stored in NFCLIB buffer. User needs to call phNfcLib_Receive API to copy data from NFCLIB buffer to application and then call phNfcLib_Transmit API with pTxBuffer as NULL to receive next set of data. |
PH_NFCLIB_STATUS_RF_TIMEOUT_ERROR | Sent data not acknowledged in time. |
PH_NFCLIB_STATUS_RF_PEER_LOST | Peer lost during communication. |
PH_NFCLIB_STATUS_RF_PROTOCOL_ERROR | General RF protocol violation. |
PH_NFCLIB_STATUS_INVALID_STATE | NFC Library had been in a wrong state when calling this function. |
[in] | pTxBuffer | Byte array containing the data to be sent or Metadata in ISO mode. |
[in] | wTxBufferLength | Number of bytes to be sent, in fact size of byte array or Zero in case Metadata is sent. |
phNfcLib_Status_t phNfcLib_Receive | ( | uint8_t *const | pRxBuffer, |
uint16_t * | pNumberOfBytes, | ||
uint8_t * | pMoreDataAvailable | ||
) |
Receive Data from an Activated Peer.
This function can be called in order to receive data from an activated peer, in fact after phNfcLib_Activate returned with status PH_NFCLIB_STATUS_PEER_ACTIVATION_DONE. Like phNfcLib_Transmit, data received using this function may get decapsulated from underlying protocol headers, depending on activation_profile configured. See phNfcLib_Transmit for more details.
Behavior in case of activation_profile is PH_NFCLIB_ACTIVATION_PROFILE_NFC
PH_NFCLIB_STATUS_SUCCESS | pNumberOfBytes bytes read from peer and stored in pRxBuffer . |
PH_NFCLIB_STATUS_RF_TIMEOUT_ERROR | Timeout waiting for data from peer. |
PH_NFCLIB_STATUS_RF_PEER_LOST | Peer lost during communication (for ISO18092 target and or active communication). |
PH_NFCLIB_STATUS_RF_PROTOCOL_ERROR | General RF protocol violation. |
PH_NFCLIB_STATUS_RF_TRANSMISSION_ERROR | Transmission error detected, e.g. RF integrity error. |
PH_NFCLIB_STATUS_INVALID_STATE | NFC Library had been in a wrong state when calling this function. |
PH_NFCLIB_STATUS_BUFFER_OVERFLOW | pMoreDataAvailable parameter is set to NULL and pRxBuffer is too small to receive all data. |
[out] | pRxBuffer | Allocated byte array to which the received data has to be written. |
[in,out] | pNumberOfBytes | Maximum receive size, in fact size of pRxBuffer . On function return it contains the actual number of bytes received, but in case when receiving from 18000p3m3 tag actual number of bits are returned. |
[out] | pMoreDataAvailable | Set to 1, if not all data could be stored and phNfcLib_Receive needs to be called again to receive the remaining data. If all data could be received, this parameter is set to 0. If this parameter is set to NULL and pRxBuffer is too small to receive all data, PH_NFCLIB_STATUS_BUFFER_OVERFLOW is returned. |
phNfcLib_Status_t phNfcLib_SetConfig | ( | uint8_t | bConfigTag, |
const uint8_t * | pConfigParam, | ||
uint16_t | wConfigParamLength | ||
) |
Set Configuration Parameter.
This function is used to configure the phNfcLib module. It takes the parameter indicated by bConfigTag
which should be one of the available configuration tags and sets it to the value given by pConfigParam
.
PH_NFCLIB_STATUS_SUCCESS | Parameter Value successfully set. |
PH_NFCLIB_STATUS_INVALID_PARAMETER | Unknown configuration tag or wrong length given (wConfigParamLength ) |
PH_NFCLIB_STATUS_INVALID_STATE | NFC Library had been in a wrong state when calling this function. |
[in] | bConfigTag | A configuration tag indicating the parameter to set. |
[in] | pConfigParam | An array holding the value to be set for the given parameter. |
[in] | wConfigParamLength | Length of the parameter value, in fact length of pConfigParam |
Set Configuration Parameter using a Value.
Like phNfcLib_SetConfig this function is used to configure the phNfcLib module. All configuration tags which take an unsigned integer as value can be set using this function. In fact it's a convenient short cut for the actual phNfcLib_SetConfig function, which does not require passing in a pointer in case only an integer value needs to be set.
PH_NFCLIB_STATUS_SUCCESS | Parameter Value successfully set. |
PH_NFCLIB_STATUS_INVALID_PARAMETER | Unknown configuration tag. |
PH_NFCLIB_STATUS_INVALID_STATE | NFC Library had been in a wrong state when calling this function. |
[in] | bConfigTag | A configuration tag indicating the parameter to set. |
[in] | dwValue | The value which has to be set for parameter indicated by bConfigTag |
phNfcLib_Status_t phNfcLib_GetConfig | ( | uint8_t | bConfigTag, |
uint8_t * | pConfigParam, | ||
uint16_t * | pConfigParamLength | ||
) |
Retrieve a configuration parameter value.
This is the counterpart to phNfcLib_SetConfig, i.e. it can be used to read out the value for a given parameter.
PH_NFCLIB_STATUS_SUCCESS | Parameter Value successfully read out. |
PH_NFCLIB_STATUS_INVALID_PARAMETER | Unknown configuration tag or provided buffer too small. |
PH_NFCLIB_STATUS_INVALID_STATE | NFC Library had been in a wrong state when calling this function. |
[in] | bConfigTag | A configuration tag indicating the parameter whose value needs to be read out. |
[out] | pConfigParam | Allocated byte array to which the read out value will be written to. |
[in,out] | pConfigParamLength | Size of pConfigParam . On function return, it holds the actual number of bytes read. |
phNfcLib_Status_t phNfcLib_Deactivate | ( | uint8_t | bDeactivateMode, |
phNfcLib_PeerInfo_t * | peerInfo | ||
) |
Deactivate an Activated Peer.
The deactivation procedure can be configured by calling phNfcLib_SetConfig_Value with configuration tag De-activation_blocking. This configuration parameter influence the behavior of the deactivation procedure only in EMVCo profile.
After a peer has been activated using phNfcLib_Activate and the caller wants to release it again (e.g. after communication sequences using phNfcLib_Transmit and phNfcLib_Receive have been finished) this API has to be called. Depending on bDeactivateMode parameter the peer gets released using defined release procedure according to the activation_profile. This for instance could indicate if the removal procedure should be performed for PH_NFCLIB_ACTIVATION_PROFILE_EMVCO. In ISO profile, deactivation procedures like HLTA, HLTB, DSL_REQ etc is performed and allows starting a new activation procedure. To releases all RF related resources this function should be called with bDeactivateMode parameter as PH_NFCLIB_DEACTIVATION_MODE_RF_OFF. If Deactivation with bDeactivateMode parameter as PH_NFCLIB_DEACTIVATION_MODE_RELEASE fails due to card being removed out of proximity or due to some RF irregularity the user may call Deactivation with bDeactivateMode parameter as PH_NFCLIB_DEACTIVATION_MODE_RELEASE again or Deactivation with bDeactivateMode parameter as PH_NFCLIB_DEACTIVATION_MODE_RF_OFF according to the scenario requirements.
PH_NFCLIB_STATUS_SUCCESS | Peer successfully deactivated and released. |
PH_NFCLIB_STATUS_INVALID_STATE | NFC Library had been in a wrong state when calling this function. |
PH_NFCLIB_STATUS_PEER_DEACTIVATION_FAILED | Peer deactivation is not successful (this error code is returned only when config De-activation_blocking is set to PH_OFF). Internal state move to Deactivation Ongoing State. phNfcLib_Deactivate has to be called in loop to check if peer deactivation is successful. |
[in] | bDeactivateMode | Deactivation mode/behavior. Refer to nfc_lib_definitions_deactivation_mode for more information. |
[in] | peerInfo | Pointer to a phNfcLib_PeerInfo_t structure updated by /ref phNfcLib_Activate API. |
void* phNfcLib_GetDataParams | ( | uint16_t | wComponent | ) |
Retrieve the pointer to the dataparams structure of an internal NFC Reader Library component.
The NfcLib encapsulates all relevant NFC Reader Library components. In case a caller needs to directly access one of the components a pointer to the dataparams is required. This function returns the pointer to the dataparams structure of the component indicated with wComponent
.
wComponent
or NFC library is in state RESET. [in] | wComponent | The component ID for which the data params pointer should be returned. For possible value refer to ph_Status.h, PH_COMP_* |
phNfcLib_Status_t phNfcLib_AsyncAbort | ( | void | ) |
Used to asynchronously stop HAL waiting for RF event and exit from HAL.
Note: This function will post an 'abort' event which is used by the HAL to move into 'Idle' state and exit from polling for RF Event. The functions that were waiting for a HAL event will return PH_ERR_ABORTED error code once this function is executed.
This function shall be called in a task other than the task where reader library is running. This API can be called at any time after the phNfcLib_Init(); and any of the NFCLIB operations like transmit and receive are in progress.
PH_NFCLIB_STATUS_SUCCESS | Operation successful. |