NXP NFC Reader Library v4.040.05.011646

Modules | Macros | Typedefs | Enumerations | Functions
NFCForum-SNEP
Network Protocol Layer

This component implements the NFC Forum Simple NDEF Exchange Protocol (SNEP) version 1.0. More...

Collaboration diagram for NFCForum-SNEP:

## Modules
| Component : Software
| Implementation of NFC Forum Simple NDEF Exchange Protocol (SNEP) 1.0.

## Macros
#define | PHNP_SNEP_HEADER_SIZE 0x06
| SNEP frame header size.

## Typedefs
typedef enum phnpSnep_Request_Codes | phnpSnep_Request_Codes_t
| SNEP Request Codes The phnpSnep_ServerListen API returns with one of the following request codes. More...

## Enumerations
enum | phnpSnep_Request_Codes { PHNP_SNEP_REQ_CONT = 0x00, PHNP_SNEP_REQ_GET = 0x01, PHNP_SNEP_REQ_PUT = 0x02, PHNP_SNEP_REQ_REJECT = 0x7F }
| SNEP Request Codes The phnpSnep_ServerListen API returns with one of the following request codes. More...

## Functions
phStatus_t | phnpSnep_ClientInit (void *pDataParams, phnpSnep_Server_type_t eServerType, uint8_t *pNonDefaultUri, uint8_t *pbSnepRxBuffer, uint32_t dwSnepRxBufferSize)
| Interface to create and configure SNEP Client. More...
phStatus_t | phnpSnep_ServerInit (void *pDataParams, phnpSnep_Server_type_t eServerType, uint8_t *pNonDefaultUri, uint8_t *pbSnepRxBuffer, uint32_t dwSnepRxBufferSize)
| Interface to create and configure SNEP Server. More...
phStatus_t | phnpSnep_Put (void *pDataParams, uint8_t *pTxBuffer, uint32_t dwTxBufferSize)
| Performs the SNEP PUT Request operation. More...
phStatus_t | phnpSnep_Get (void *pDataParams, uint8_t *pNdefMsg, uint32_t dwNdefMsgLen, uint8_t *pRxBuffer, uint32_t *pdwRxLen, uint32_t dwAppBufSize)
| Performs the SNEP GET Request operation. More...
phStatus_t | phnpSnep_ServerListen (void *pDataParams, uint32_t dwGetReqBuffSize, uint8_t *pGetReqData, uint32_t *dwGetReqLength, uint8_t *pClientReq)
| Used to receive SENP Request from the Remote Client. More...
phStatus_t | phnpSnep_ServerSendResponse (void *pDataParams, uint8_t bClientReq, uint8_t *pRespDataForGet, uint32_t dwRespDataLen, uint32_t dwPutBuffSize, uint8_t *pPutData, uint32_t *pdwPutDataLen)
| Used to send Response to the SNEP Request delivered by phnpSnep_ServerListen. More...
phStatus_t | phnpSnep_ClientDeInit (void *pDataParams)
| SNEP Client De-Initialization. More...
phStatus_t | phnpSnep_ServerDeInit (void *pDataParams)
| SNEP Server De-Initialization. More...

## SNEP specific error codes.
Note Do not change the macro values.
#define | PH_ERR_SNEP_FAILED 0x81
| Status indicating that Received Invalid Request to Server and LLCP Disconnection is done and further communication is not possible over this Link. More...
#define | PH_ERR_SNEP_GET_FAILED 0x82
| Status indicating that Client GET Request Failed as Response sent by Server is other than SUCCESS Response.
#define | PH_ERR_INVALID_VERSION 0x83
| Status indicating that received Client Request contains Invalid Version number.

## Detailed Description

This component implements the NFC Forum Simple NDEF Exchange Protocol (SNEP) version 1.0.

Design Limitation: SNEP implementation will only allow to initialize maximum of one default SNEP server and one non-default SNEP server using phnpSnep_ServerInit API.

This layer follows a multi-threaded RTOS based design using one reader library task and one SNEP Server/Client application task. Reader Library Task calls LLCP API's to establish Link Connection on which SNEP Server/Client Task can send SNEP packets.

A pictorial representation of reader library task and SNEP Server application task used for SNEP Exchange is shown below.

A pictorial representation of reader library task and SNEP Client application task used for SNEP Exchange is shown below.

## Macro Definition Documentation

## § PH_ERR_SNEP_FAILED

#define PH_ERR_SNEP_FAILED 0x81

Status indicating that Received Invalid Request to Server and LLCP Disconnection is done and further communication is not possible over this Link.

If this error is returned then a new LLC Session needs to be created by Server for further communication.

## Typedef Documentation

## § phnpSnep_Request_Codes_t

typedef enum phnpSnep_Request_Codes phnpSnep_Request_Codes_t

SNEP Request Codes The phnpSnep_ServerListen API returns with one of the following request codes.

These are passed to phnpSnep_ServerSendResponse API received from Client to Server.

## Enumeration Type Documentation

## § phnpSnep_Request_Codes

enum phnpSnep_Request_Codes

SNEP Request Codes The phnpSnep_ServerListen API returns with one of the following request codes.

These are passed to phnpSnep_ServerSendResponse API received from Client to Server.

Enumerator
PHNP_SNEP_REQ_CONT | Continue sending remaining fragments.
PHNP_SNEP_REQ_GET | Return an NDEF message.
PHNP_SNEP_REQ_PUT | Accept an NDEF message.
PHNP_SNEP_REQ_REJECT | Client indicates not to send remaining fragments using this request.

## Function Documentation

## § phnpSnep_ClientInit()

phStatus_t phnpSnep_ClientInit | ( | void * | pDataParams,
|  | phnpSnep_Server_type_t | eServerType,
|  | uint8_t * | pNonDefaultUri,
|  | uint8_t * | pbSnepRxBuffer,
|  | uint32_t | dwSnepRxBufferSize
| ) |  |

Interface to create and configure SNEP Client.

This function creates and configures a SNEP Client over LLCP. This has to be called first in a client session/Task after phlnLlcp_WaitForActivation. If the Server Type is Default Server than pNonDefaultUri parameter is Ignored.

Returns
  Status code

Return values

  PH_ERR_SUCCESS | Operation successful.
  PH_ERR_INVALID_DATA_PARAMS | Invalid Component ID.
  Other | Depending on implementation and underlying component.

Parameters

  [in] | pDataParams | Pointer to this layer's parameter structure.
  [in] | eServerType | Type of the SNEP Server to which Client has to connect.
  [in] | pNonDefaultUri | Pointer of Uniform Resource Identifier (URI) of Non-Default Server. NULL terminated URI string should be provided.
  [in] | pbSnepRxBuffer | Pointer to Client Receive Buffer.
  [in] | dwSnepRxBufferSize | Size of Client Receive Buffer.

## § phnpSnep_ServerInit()

phStatus_t phnpSnep_ServerInit | ( | void * | pDataParams,
|  | phnpSnep_Server_type_t | eServerType,
|  | uint8_t * | pNonDefaultUri,
|  | uint8_t * | pbSnepRxBuffer,
|  | uint32_t | dwSnepRxBufferSize
| ) |  |

Interface to create and configure SNEP Server.

This function creates and configures a SNEP Server using eServerType parameter over LLCP. If the Server Type is Default Server than pNonDefaultUri parameter is Ignored.

This API will be called first in a server session/task after phlnLlcp_WaitForActivation.

Returns
  Status code

Return values

  PH_ERR_SUCCESS | Operation successful.
  PH_ERR_INVALID_DATA_PARAMS | Invalid Component ID.
  Other | Depending on implementation and underlying component.

Parameters

  [in] | pDataParams | Pointer to this layer's parameter structure.
  [in] | eServerType | Type of the SNEP Server.
  [in] | pNonDefaultUri | Pointer of Uniform Resource Identifier (URI) of Non-Default Server. NULL terminated URI string should be provided.
  [in] | pbSnepRxBuffer | Pointer to Server Receive Buffer.
  [in] | dwSnepRxBufferSize | Size of Server Receive Buffer.

## § phnpSnep_Put()

phStatus_t phnpSnep_Put | ( | void * | pDataParams,
|  | uint8_t * | pTxBuffer,
|  | uint32_t | dwTxBufferSize
| ) |  |

Performs the SNEP PUT Request operation.

This function has to be called after the phnpSnep_ClientInit is done.

Returns
  Status code

Return values

  PH_ERR_SUCCESS | Operation successful.
  PH_ERR_INVALID_DATA_PARAMS | Invalid Component ID.
  PH_ERR_INVALID_PARAMETER | Invalid input parameters.
  PH_ERR_PROTOCOL_ERROR | Did not receive valid response from Server.
  Other | Depending on underlying component.

Parameters

  [in] | pDataParams | Pointer to this layer's parameter structure.
  [in] | pTxBuffer | Pointer of Buffer to be transmitted.
  [in] | dwTxBufferSize | Length of Buffer to be transmitted.

## § phnpSnep_Get()

phStatus_t phnpSnep_Get | ( | void * | pDataParams,
|  | uint8_t * | pNdefMsg,
|  | uint32_t | dwNdefMsgLen,
|  | uint8_t * | pRxBuffer,
|  | uint32_t * | pdwRxLen,
|  | uint32_t | dwAppBufSize
| ) |  |

Performs the SNEP GET Request operation.

This API should not be called if initialized in phnpSnep_NonDefault_Server. Also this API returns PH_ERR_SNEP_GET_FAILED
if the remote SNEP Server is Default Server.
This function has to be called only after the phnpSnep_ClientInit is done.

NOTE: Sending Client GET Request in fragments is not supported by this API due to which length of NDEF Message (dwNdefMsgLen) in GET Request cannot be more than Remote MIU. If length of NDEF Message is more than remote MIU then PH_ERR_INVALID_PARAMETER error will be returned by this API.

Returns
  Status code

Return values

  PH_ERR_SUCCESS | Operation successful.
  PH_ERR_INVALID_DATA_PARAMS | Invalid Component ID.
  PH_ERR_INVALID_PARAMETER | Invalid input parameters.
  PH_ERR_PROTOCOL_ERROR | Did not receive valid Response from Server.
  PH_ERR_BUFFER_OVERFLOW | If Server Response length is more than the specified dwAppBufSize length.
  PH_ERR_SNEP_GET_FAILED | Received Error response from Remote Server. Client should De-Init and start new session.
  Other | Depending on implementation and underlying component.

Parameters

  [in] | pDataParams | Pointer to this layer's parameter structure.
  [in] | pNdefMsg | Pointer to the NDEF message in the Get Request to be sent to Server.
  [in] | dwNdefMsgLen | Length of the NDEF message in the Get Request to be sent to Server.
  [out] | pRxBuffer | Pointer to the Application Rx Buffer to receive data.
  [out] | pdwRxLen | Number of bytes received from the Server.
  [in] | dwAppBufSize | Maximum acceptable data from Server, normally size of pRxBuffer.

## § phnpSnep_ServerListen()

phStatus_t phnpSnep_ServerListen | ( | void * | pDataParams,
|  | uint32_t | dwGetReqBuffSize,
|  | uint8_t * | pGetReqData,
|  | uint32_t * | dwGetReqLength,
|  | uint8_t * | pClientReq
| ) |  |

Used to receive SENP Request from the Remote Client.

This function Listens for SNEP Client Request and parses the Request type and returns to Application in pbClientReq parameter.

Parameter Usage:
If the Initialized Server Type is Default Server then 'dwGetReqBuffSize', 'pGetReqData', 'dwGetReqLength' parameters are ignored.

This function is immediately called after phnpSnep_ServerInit.

Returns
  Status code

Return values

  PH_ERR_SUCCESS | Operation successful.
  PH_ERR_INVALID_DATA_PARAMS | Invalid Component ID.
  PH_ERR_INVALID_PARAMETER | Invalid input parameters.
  PH_ERR_INVALID_VERSION | Received Client Request with Invalid Version.
  PH_ERR_UNSUPPORTED_COMMAND | Received unsupported Request from Client.
  PH_ERR_BUFFER_OVERFLOW | Message in GET cannot fit in Application Buffer.
  PH_ERR_SNEP_FAILED | Received Invalid Request, Server session will be closed and new session needs to be created.
  Other | Depending on implementation and underlying component.

Parameters

  [in] | pDataParams | Pointer to this layer's parameter structure.
  [in] | dwGetReqBuffSize | Size of Buffer to store received NDEF Message in Get Request.
  [out] | pGetReqData | Pointer to the application Buffer to store received Message in Get Request.
  [out] | dwGetReqLength | Received data length in Message in GET Request from Client.
  [out] | pClientReq | Pointer to the Type of received Client Request phnpSnep_Request_Codes.

## § phnpSnep_ServerSendResponse()

phStatus_t phnpSnep_ServerSendResponse | ( | void * | pDataParams,
|  | uint8_t | bClientReq,
|  | uint8_t * | pRespDataForGet,
|  | uint32_t | dwRespDataLen,
|  | uint32_t | dwPutBuffSize,
|  | uint8_t * | pPutData,
|  | uint32_t * | pdwPutDataLen
| ) |  |

Used to send Response to the SNEP Request delivered by phnpSnep_ServerListen.

This function will receive in chunks if more data to be received in case of PUT Request
and copies it to 'dwPutBuffSize' Buffer and performs the required SNEP Server Response.
This function will send SNEP Success Response for GET Request in chunks based on Remote MIU.
Parameter Usage:

1. If bClientReq is PUT request, then 'pPutData', 'dwPutBuffSize' and 'pdwPutDataLen' have to be provided by the caller where PUT data will be copied to.
2. If the SNEP PUT header indicates that the client is putting more data than the dwBufferSize, then Excess Data response is sent to the client.
3. If bClientReq is GET request, then Message pointed by pRespDataForGet of dwRespDataLen length will be sent as Response to the client.
   If no Data needs to be sent in response for GET Request then dwRespDataLen should be zero.
   Sequence of functions that needs to be called prior to this API are as below:

1. phnpSnep_ServerInit()
2. phnpSnep_ServerListen()
   Returns
     Status code
   Return values

     PH_ERR_SUCCESS | Operation successful.
     PH_ERR_INVALID_DATA_PARAMS | Invalid Component ID.
     PH_ERR_INVALID_PARAMETER | Invalid input parameters.
     PH_ERR_BUFFER_OVERFLOW | Message in PUT cannot be fitted in Application Buffer.
     PH_ERR_PROTOCOL_ERROR | Received wrong SNEP Request from Client.

Parameters

  [in] | pDataParams | Pointer to this layer's parameter structure.
  [in] | bClientReq | Type of received Client Request. Should only be PHNP_SNEP_REQ_GET or PHNP_SNEP_REQ_PUT.
  [in] | pRespDataForGet | Pointer to application provided data to handle GET Request from Client.
  [in] | dwRespDataLen | Data length to be transmitted to Client for GET Request.
  [in] | dwPutBuffSize | Size of the Data buffer given by the application to hold the received PUT Request Data.
  [out] | pPutData | Pointer to Data Buffer given by the application to hold the received PUT Request Data from client.
  [out] | pdwPutDataLen | Actual length of PUT Request Data received from the Client.

## § phnpSnep_ClientDeInit()

phStatus_t phnpSnep_ClientDeInit | ( | void * | pDataParams | ) |

SNEP Client De-Initialization.

This function De-Initializes the SNEP Client session.

Sequence of functions that needs to be called prior to this API are as below:

1. phnpSnep_ClientInit()
2. phnpSnep_Put() or phnpSnep_Get()
   Returns
     Status code
   Return values

     PH_ERR_SUCCESS | Operation successful.
     PH_ERR_INVALID_DATA_PARAMS | Invalid Component ID.
     Other | Depending on implementation and underlying component.

Parameters

  [in] | pDataParams | Pointer to this layer's parameter structure.

## § phnpSnep_ServerDeInit()

phStatus_t phnpSnep_ServerDeInit | ( | void * | pDataParams | ) |

SNEP Server De-Initialization.

This function De-Initializes the SNEP Server session.

Sequence of functions that needs to be called prior to this API are as below:

1. phnpSnep_ServerInit()
2. phnpSnep_ServerListen()
3. phnpSnep_ServerSendResponse()
   Returns
     Status code
   Return values

     PH_ERR_SUCCESS | Operation successful.
     PH_ERR_INVALID_DATA_PARAMS | Invalid Component ID.
     Other | Depending on implementation and underlying component.

Parameters

  [in] | pDataParams | Pointer to this layer's parameter structure.