NXP NFC Reader Library v4.040.05.011646

Functions
NXP NFC Library Functions
Simplified API Layer » NXP NFC Library Top Level API

All Public Functions of the NFC Library. More...

Collaboration diagram for NXP NFC Library Functions:

## 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...

## Detailed Description

All Public Functions of the NFC Library.

## Function Documentation

## § phNfcLib_Init()

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.

Precondition
  NFC library must be in state RESET

Postcondition
  All APIs are allowed to be called. NFC Library is in state INITIALIZED

Return values

  PH_NFCLIB_STATUS_INVALID_STATE | NFC Library had been in a wrong state when calling this function.

## § phNfcLib_DeInit()

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.

Precondition
  NFC Library must be in state INITIALIZED

Postcondition
  NFC Library is in state RESET. Only phNfcLib_Init is allowed to be called.

Return values

  PH_NFCLIB_STATUS_INVALID_STATE | NFC Library had been in a wrong state when calling this function.

## § phNfcLib_Activate()

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.

Note
  - The activation procedure will always try to resolve collisions (except for activation profile PH_NFCLIB_ACTIVATION_PROFILE_EMVCO). So even if there a multiple peers in proximity (except in case of ISO156936 and ISO18000p3m3), the activation procedure will activate only one peer. The priority (i.e. the order in which technology detection is performed) depends on the configured activation_profile and additionally on the configured activation_prio
  - When polling for multiple technologies, activation procedure always uses bail out after first technology is detected and doesn't poll further for other technologies.
  - When multiple tags/peers are detected, activation procedure uses different mechanism for each technology to resolve and activate tag/peer. Type A : Collision resolution of Type A always resolves the tag with highest UID value, Type B : The first tag to reply to the slot marker command which can be any random tag will be activated ISO 15693 : In Type V, when single tag is placed in vicinity, tag will be moved to selected state using select command (TBD : If detected tag doesn't support Select command) and in case of multiple tags in vicinity, based on discovery loop PHAC_DISCLOOP_CFG_MAX_VICINITY_CARDS_SUPPORTED macro value collision will be resolved and PHAC_DISCLOOP_CFG_MAX_VICINITY_CARDS_SUPPORTED number of tag UID's in proximity are returned to User. ISO 18000p3m3 : When single tag is placed in vicinity, tag will be moved to Open state using Req_Rn command and handle is available which is used to communicate with tag. In case of multiple tags in vicinity, based on discovery loop PHAC_DISCLOOP_CFG_MAX_VICINITY_CARDS_SUPPORTED macro value collision will be resolved and PHAC_DISCLOOP_CFG_MAX_VICINITY_CARDS_SUPPORTED number of tag UII's in proximity are returned to User.
  - In case PH_NFCLIB_ACTIVATION_PROFILE_NFC is configured as activation_profile and underlying protocol is ISO18092 this procedure also tries to perform LLCP activation in order to be able to transmit NDEF messages over SNEP when using phNfcLib_Transmit and phNfcLib_Receive.

Precondition
  NFC Library must be in state INITIALIZED or ACTIVATED

Postcondition
  After successful activation (PH_NFCLIB_STATUS_PEER_ACTIVATION_DONE) NFC library is in state ACTIVATED.

Return values

  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.

Parameters

  [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_Transmit()

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 .

Note
  - Depending on the activation_profile this function may block until a response has actually been sent back by the peer. For instance PH_NFCLIB_ACTIVATION_PROFILE_EMVCO requires acknowledgment from the peer for a sent frame, so phNfcLib_Transmit will only return once this acknowledgment has been received.

Behavior in NFC PROFILE

Behavior in case of activation_profile is PH_NFCLIB_ACTIVATION_PROFILE_NFC

- In case underlying protocol is ISO18092 this function acts as a SNEP client, i.e. connecting to a server in order to push the NDEF record.
- In case underlying protocol is ISO14443-4 host card emulation, this function is used to read the record of the NDEF emulation.

Behavior in ISO PROFILE

Behavior in case of activation_profile is PH_NFCLIB_ACTIVATION_PROFILE_ISO

- In case detected card is Mifare Ultralight, Classic or Desfire, input to phNfcLib_Transmit will be pointer of type nfc_lib_transmit_metadata. User needs to provide correct information in metadata to communicate with tags.

Precondition
  NFC Library must be in state ACTIVATED

Return values

  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.

Parameters

  [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_Receive()

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.

Note
  - Caller is responsible for implementing correct sequence of phNfcLib_Transmit and phNfcLib_Receive. So depending on the underlying protocol the two APIs have the be called alternately, starting with either transmit or receive, depending on the underlying technology (initiator vs. target).
  - Similar to phNfcLib_Transmit, in case PH_NFCLIB_ACTIVATION_PROFILE_NFC is the active activation_profile and underlying protocol is ISO18092 calling

Behavior in case of NFC PROFILE

Behavior in case of activation_profile is PH_NFCLIB_ACTIVATION_PROFILE_NFC

- In case underlying protocol is ISO18092 this API waits for receiving an NDEF message via SNEP (i.e. phNfcLib_Activate starts a SNEP server and data received via that server socket can be read by this function).
- In case underlying protocol is ISO14443-4 host card emulation, this function is used to write the record of the NDEF emulation.
  Precondition
    NFC Library must be in state ACTIVATED
  See also
    phNfcLib_Transmit
  Return values

    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.

Parameters

  [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_SetConfig()

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`.

Note
  - For pure integer parameter the helper function phNfcLib_SetConfig_Value can be used instead.
  - phNfcLib_Init resets all configuration parameters to its default value.

Precondition
  NFC Library need to be in state INITIALIZED, i.e. after calling phNfcLib_Init, phNfcLib_Deactivate or as long as no activation happened.

Return values

  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.

Parameters

  [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`

## § phNfcLib_SetConfig_Value()

phNfcLib_Status_t phNfcLib_SetConfig_Value | ( | uint8_t | bConfigTag,
|  | uint32_t | dwValue
| ) |  |

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.

Note
  - phNfcLib_Init resets all configuration parameters to its default value.

Precondition
  NFC Library need to be in state INITIALIZED, i.e. after calling phNfcLib_Init, phNfcLib_Deactivate or as long as no activation happened for Activation configurations. In case of De-activation configuration NFC Library should not be in state RESET state.

See also
  phNfcLib_SetConfig

Return values

  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.

Parameters

  [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_GetConfig()

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.

See also
  phNfcLib_SetConfig

Precondition
  NFC Library need to be in state INITIALIZED or ACTIVATED as no activation happened.

Return values

  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.

Parameters

  [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_Deactivate()

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.

Precondition
  NFC Library must be in state ACTIVATED

Postcondition
  NFC Library is in state INITIALIZED

Return values

  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.

Parameters

  [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.

## § phNfcLib_GetDataParams()

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`.

Example
  phNfcLib_Init();
  // manually switch on the RF field
  phhalHw_FieldOn(phNfcLib_GetDataParams(PH_COMP_HAL));

Returns
  Pointer to the component's dataparam structure. NULL in case phNfcLib is not managing the component indicated by `wComponent` or NFC library is in state RESET.

Parameters

  [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_AsyncAbort()

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.

Return values

  PH_NFCLIB_STATUS_SUCCESS | Operation successful.