diff options
Diffstat (limited to 'src/phHal4Nfc.h')
| -rw-r--r-- | src/phHal4Nfc.h | 1169 |
1 files changed, 1169 insertions, 0 deletions
diff --git a/src/phHal4Nfc.h b/src/phHal4Nfc.h new file mode 100644 index 0000000..47e3136 --- /dev/null +++ b/src/phHal4Nfc.h @@ -0,0 +1,1169 @@ +/* + * Copyright (C) 2010 NXP Semiconductors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + + +/** + * \file phHal4Nfc.h + * \brief HAL Function Prototypes + * The HAL4.0 API provides the user to have a interface for PN544(PN54x)/PN65N + * NFC device.The API is a non-blocking API, asynchronous API. This means that + * when ever an API function call results in waiting for a response from the + * NFC device, the API function will return immediately with status 'PENDING' + * and the actual result will be returned through specific callback functions + * on receiving the response from the NFC device + * + * \note This is the representative header file of the HAL 4.0. The release + * TAG or label is representing the release TAG (alias) of the entire + * library.A mechanism (see documentation \ref hal_release_label near + * the include guards of this file) is used to propagate the alias to + * the main documentation page. + * + * Project: NFC-FRI-1.1 / HAL4.0 + * + * $Date: Mon Jun 14 11:36:12 2010 $ + * $Author: ing07385 $ + * $Revision: 1.171 $ + * $Aliases: NFC_FRI1.1_WK1023_R35_2,NFC_FRI1.1_WK1023_R35_1 $ + * + */ + +/** page hal_release_label HAL 4.0 Release Label + * SDK_HAL_4.0 v 0.1 Draft + * \note This is the TAG (label, alias) of the HAL. If the string is empty,the + * current documentation has not been generated from an official release. + */ +/*@{*/ +#ifndef PHHAL4NFC_H +#define PHHAL4NFC_H +/*@}*/ + + +/** + * \name HAL4 + * + * File: \ref phHal4Nfc.h + *\def hal + */ + +/*@{*/ +#define PH_HAL4NFC_FILEREVISION "$Revision: 1.171 $" /**< \ingroup grp_file_attributes */ +#define PH_HAL4NFC_FILEALIASES "$Aliases: NFC_FRI1.1_WK1023_R35_2,NFC_FRI1.1_WK1023_R35_1 $" /**< \ingroup grp_file_attributes */ +/*@}*/ + +/* -----------------Include files ---------------------------------------*/ +#include <phNfcStatus.h> +#include <phNfcCompId.h> +#include <phNfcHalTypes.h> +#include <phNfcInterface.h> +#include <phNfcIoctlCode.h> +#include <phNfcConfig.h> +#include <phDbgTrace.h> +#ifdef ANDROID +#include <string.h> +#endif + +/*************************** Includes *******************************/ +/** \defgroup grp_mw_external_hal_funcs NFC HAL4.0 +* +* +* +*/ +/* ---------------- Macros ----------------------------------------------*/ + +/** HAL Implementation Version Macros : Updated for every feature release of + HAL functionality */ +#define PH_HAL4NFC_VERSION 8 +#define PH_HAL4NFC_REVISION 21 +#define PH_HAL4NFC_PATCH 1 +#define PH_HAL4NFC_BUILD 0 + +/** HAL Interface Version Macros : Updated for every external release of + HAL Interface */ +#define PH_HAL4NFC_INTERFACE_VERSION 0 +#define PH_HAL4NFC_INTERFACE_REVISION 6 +#define PH_HAL4NFC_INTERFACE_PATCH 0 +#define PH_HAL4NFC_INTERAFECE_BUILD 0 + +/**Maximum length of receive buffer maintained by HAL*/ +#define PH_HAL4NFC_MAX_RECEIVE_BUFFER 4096U + +/**Send length used for Transceive*/ +#define PH_HAL4NFC_MAX_SEND_LEN PHHAL_MAX_DATASIZE + +/* -----------------Structures and Enumerations -------------------------*/ + +/** + * \ingroup grp_mw_external_hal_funcs + * + * Structure containing information about discovered remote device, like + * the number of remote devices found, device specific information + * like type of device (eg: ISO14443-4A/4B, NFCIP1 target etc) and + * the type sepcific information (eg: UID, SAK etc). This structure is + * returned as part of the disocvery notification. For more info refer + * \ref phHal4Nfc_ConfigureDiscovery, + * \ref phHal4Nfc_RegisterNotification, + * \ref pphHal4Nfc_Notification_t, + * phHal4Nfc_NotificationInfo_t + * + * + */ +typedef struct phHal4Nfc_DiscoveryInfo +{ + uint32_t NumberOfDevices;/**< Number of devices found */ + phHal_sRemoteDevInformation_t **ppRemoteDevInfo;/**< Pointer to Remote + device info list*/ +}phHal4Nfc_DiscoveryInfo_t; + +/** + * \ingroup grp_mw_external_hal_funcs + * + * This is a union returned as part of the \ref pphHal4Nfc_Notification_t + * callback. It contains either discovery information or other event + * information for which the client has registered using the + * \ref phHal4Nfc_RegisterNotification. + */ +typedef union +{ + phHal4Nfc_DiscoveryInfo_t *psDiscoveryInfo; + phHal_sEventInfo_t *psEventInfo; +}phHal4Nfc_NotificationInfo_t; + + + +/** +* \ingroup grp_mw_external_hal_funcs +* +* Prototype for Generic callback type provided by upper layer. This is used +* to return the success or failure status an asynchronous API function which +* does not have any other additional information to be returned. Refer +* specific function for applicable status codes. +*/ +typedef void (*pphHal4Nfc_GenCallback_t)( + void *context, + NFCSTATUS status + ); + +/** +* \ingroup grp_mw_external_hal_funcs +* +* Disconnect callback type provided by upper layer to called on completion +* of disconnect call \ref phHal4Nfc_Disconnect. +* +*/ +typedef void (*pphHal4Nfc_DiscntCallback_t)( + void *context, + phHal_sRemoteDevInformation_t *psDisconnectDevInfo, + NFCSTATUS status + ); + +/** +* \ingroup grp_mw_external_hal_funcs +* +* Notification callback type used by HAL to provide a Discovery or +* Event notification to the upper layer. +* +*/ +typedef void (*pphHal4Nfc_Notification_t) ( + void *context, + phHal_eNotificationType_t type, + phHal4Nfc_NotificationInfo_t info, + NFCSTATUS status + ); + + +/** +* \ingroup grp_mw_external_hal_funcs +* +* Callback type used to provide a Connect Success or Failure indication to +* the upper layer as a result of \ref phHal4Nfc_Connect call used to connect +* to discovered remote device. +* +*/ +typedef void (*pphHal4Nfc_ConnectCallback_t)( + void *context, + phHal_sRemoteDevInformation_t *psRemoteDevInfo, + NFCSTATUS status + ); + +/** +* \ingroup grp_mw_external_hal_funcs +* +* This callback type is used to provide received data and it's size to the +* upper layer in \ref phNfc_sData_t format ,when the upper layer has performed +* a Transceive operation on a tag or when the Device acts as an Initiator in a +* P2P transaction. +* +* +*/ +typedef void (*pphHal4Nfc_TransceiveCallback_t) ( + void *context, + phHal_sRemoteDevInformation_t *ConnectedDevice, + phNfc_sData_t *pRecvdata, + NFCSTATUS status + ); + +/** +* \ingroup grp_mw_external_hal_funcs +* +* This callback type is used to provide received data and it's size to the +* upper layer in \ref phNfc_sData_t structure, when the upper layer when the +* Device acts as a Target in a P2P transaction. +* +* +*/ +typedef void (*pphHal4Nfc_ReceiveCallback_t) ( + void *context, + phNfc_sData_t *pDataInfo, + NFCSTATUS status + ); + +/** +* \ingroup grp_mw_external_hal_funcs +* +* Callback type to inform success or failure of the Ioctl calls +* made by upper layer. It may optionally contain response data +* depending on the Ioctl command issued. +* +*/ +typedef void (*pphHal4Nfc_IoctlCallback_t) (void *context, + phNfc_sData_t *pOutData, + NFCSTATUS status ); + +/** +* \ingroup grp_mw_external_hal_funcs +*\if hal +* \sa \ref pphHal4Nfc_GenCallback_t +* \endif +* +*/ + +/** Same as general callback type, used to inform the completion of +* \ref phHal4Nfc_Send call done by when in NFCIP1 Target mode +*/ +typedef pphHal4Nfc_GenCallback_t pphHal4Nfc_SendCallback_t; + +/** +* \ingroup grp_mw_external_hal_funcs +* +* Enum type to distinguish between normal init and test mode init +* to be done as part of phHal4Nfc_Open +* In test mode init only minimal initialization of the NFC Device +* sufficient to run the self test is performed. +* +* \note Note: No functional features can be accessed when +* phHal4Nfc_Open is called with TestModeOn +* \ref phHal4Nfc_Open +* +*/ +typedef enum{ + eInitDefault = 0x00, /**<Complete initialization for normal + firmware operation*/ + eInitTestModeOn, /**<Limited Initialization used for running self + tests */ + eInitCustom /**<Reserved for Future Use */ +} phHal4Nfc_InitType_t; + +/** +* \ingroup grp_mw_external_hal_funcs +* +* Type to select the type of notification registration +* for Tags, P2P and SecureElement and Host Card Emulation events +* +* \if hal +* \ref phHal4Nfc_RegisterNotification,phHal4Nfc_UnregisterNotification +* \endif +* +*/ +typedef enum{ + eRegisterDefault = 0x00, /**<For All other generic notifications + like Host Wakeup Notification */ + eRegisterTagDiscovery, /**<For Tag Discovery notification*/ + eRegisterP2PDiscovery, /**<For P2P Discovery notification*/ + eRegisterSecureElement, /**<For Secure Element notification*/ + eRegisterHostCardEmulation /**<For notification related to Virtual + Card Emulation from host */ +} phHal4Nfc_RegisterType_t; + +/** +* \ingroup grp_mw_external_hal_funcs +* +* Specifies the Remote Reader type,either initiator or ISO A/B or Felica +* +*/ +typedef struct phHal4Nfc_TransactInfo{ + phHal_eRFDevType_t remotePCDType; +}phHal4Nfc_TransactInfo_t; + +/*preliminary definitions end*/ + +/* -----------------Exported Functions----------------------------------*/ +/** + * \if hal + * \ingroup grp_hal_common + * \else + * \ingroup grp_mw_external_hal_funcs + * \endif + * + * This function initializes and establishes a link to the NFC Device. This is + * a asynchronous call as it requires a series of setup calls with the NFC + * device. The open is complete when the status response callback <em> + * pOpenCallback </em> is called. It uses a Hardware Reference + * \ref phHal_sHwReference, allocated by the upper layer and the p_board_driver + * member initialized with the dal_instance (handle to the communication driver) + * and other members initialized to zero or NULL. + * + * \note + * - The device is in initialized state after the command has completed + * successfully. + * + * + * \param[in,out] psHwReference Hardware Reference, pre-initialized by upper + * layer. Members of this structure are made valid if + * this function is successful. \n + * + * \param[in] InitType Initialization type, used to differentiate between + * test mode limited initialization and normal init. + * + * \param[in] pOpenCallback The open callback function called by the HAL + * when open (initialization) sequence is completed or if there + * is an error in initialization. \n + * + * \param[in] pContext Upper layer context which will be included in the + * call back when request is completed. \n + * + * \retval NFCSTATUS_PENDING Open sequence has been successfully + * started and result will be conveyed + * via the pOpenCallback function. + * \retval NFCSTATUS_ALREADY_INITIALISED Device initialization already in + * progress. + * \retval NFCSTATUS_INVALID_PARAMETER The parameter could not be properly + * interpreted (structure uninitialized?). + * \retval NFCSTATUS_INSUFFICIENT_RESOURCES Insufficient resources for + * completing the request. + * \retval Others Errors related to the lower layers. + * + * \if hal + * \sa \ref phHal4Nfc_Close, + * \endif + */ +extern NFCSTATUS phHal4Nfc_Open( + phHal_sHwReference_t *psHwReference, + phHal4Nfc_InitType_t InitType, + pphHal4Nfc_GenCallback_t pOpenCallback, + void *pContext + ); + + + +/** + * \if hal + * \ingroup grp_hal_common + * \else + * \ingroup grp_mw_external_hal_funcs + * \endif + * + * Retrieves the capabilities of the device represented by the Hardware + * Reference parameter.The HW, FW versions,model-id and other capability + * information are located inside the pDevCapabilities parameter. + * + * \param[in] psHwReference Hardware Reference, pre-initialized + * by upper layer. \n + * \param[out] psDevCapabilities Pointer to the device capabilities structure + * where all relevant capabilities of the + * peripheral are stored. \n + * \param[in] pContext Upper layer context which will be included in + * the call back when request is completed. \n + * + * \retval NFCSTATUS_SUCCESS Success and the psDevCapabilities is + * updated with info. + * \retval NFCSTATUS_INVALID_PARAMETER One or more of the supplied parameters + * could not be properly interpreted. + * \retval NFCSTATUS_NOT_INITIALISED Hal is not yet initialized. + * \retval Others Errors related to the lower layers. + * + */ +extern NFCSTATUS phHal4Nfc_GetDeviceCapabilities( + phHal_sHwReference_t *psHwReference, + phHal_sDeviceCapabilities_t *psDevCapabilities, + void *pContext + ); + + +/** +* \if hal +* \ingroup grp_hal_common +* \else +* \ingroup grp_mw_external_hal_funcs +* \endif +* +* This function is used to Configure discovery wheel (and start if +* required) based on the discovery configuration passed. +* This includes enabling/disabling of the Reader phases (A, B, F), +* NFCIP1 Initiator Speed and duration of the Emulation phase. +* Additional optional parameters for each of the features i.e. Reader, +* Emulation and Peer2Peer can be set using the +* \ref phHal4Nfc_ConfigParameters function +* +* \param[in] psHwReference Hardware Reference, pre-initialized by +* upper layer. \n +* +* \param[in] discoveryMode Discovery Mode allows to choose between: +* discovery configuration and start, stop +* discovery and start discovery (with last +* set configuration). +* \ref phHal_eDiscoveryConfigMode_t +* \note Note: Presently only NFC_DISCOVERY_CONFIG is supported, other values +* are for future use. When in Reader/Initiator mode it mandatory +* to call phHal4Nfc_Connect before any transaction can be performed +* with the discovered device. +* +* \param[in] discoveryCfg Discovery configuration parameters. +* Reader A/Reader B, Felica 212, Felica 424, +* NFCIP1 Speed, Emulation Enable and Duration. +* +* +* \param[in] pConfigCallback This callback has to be called once Hal +* completes the Configuration. +* +* \param[in] pContext Upper layer context to be returned in the +* callback. +* +* \retval NFCSTATUS_INVALID_PARAMETER Wrong Parameter values. +* +* \retval NFCSTATUS_NOT_INITIALISED Hal is not initialized. +* +* \retval NFCSTATUS_BUSY Cannot Configure Hal in +* Current state. +* +* \retval NFCSTATUS_INSUFFICIENT_RESOURCES System Resources insufficient. +* +* \retval NFCSTATUS_PENDING Configuration request accepted +* and Configuration is in progress. +* +* \retval NFCSTATUS_INVALID_PARAMETER One or more of the supplied +* parameters could not be properly +* interpreted. +* \retval Others Errors related to the lower layers +* +* \note Note: When in Reader/Initiator mode it mandatory +* to call phHal4Nfc_Connect before any transaction can be performed +* with the discovered device. Even if the HAL client is not +* interested in using any of the discovered phHal4Nfc_Connect and +* phHal4Nfc_Disconnect should be called to restart the Discovery +* wheel +* +* \ref phHal4Nfc_Connect, phHal4Nfc_Disconnect +* +*/ +extern NFCSTATUS phHal4Nfc_ConfigureDiscovery( + phHal_sHwReference_t *psHwReference, + phHal_eDiscoveryConfigMode_t discoveryMode, + phHal_sADD_Cfg_t *discoveryCfg, + pphHal4Nfc_GenCallback_t pConfigCallback, + void *pContext + ); +/** +* \if hal +* \ingroup grp_hal_common +* \else +* \ingroup grp_mw_external_hal_funcs +* \endif +* +* This function is used to set parameters of various features of the Hal, +* based on the CfgType parameter. Presently following configuration +* types are supported :- +* \n 1. NFC_RF_READER_CONFIG (optional)-> Configure parameters for Reader A +* or Reader B based on the configuration passed +* \n 2. NFC_P2P_CONFIG (optional)-> Congfigure P2P parameters like +* 'General bytes', 'PSL Request' etc. +* \n 3. NFC_EMULATION_CONFIG -> Enable and configure the emulation mode +* parameters for either NFC Target, SmartMX, UICC and +* \n Card Emulation from Host (A, B, F) +* All the configuration modes can be called independent of each other. The +* setting will typically take effect for the next cycle of the relevant +* phase of discovery. For optional configuration internal defaults will be +* used in case the configuration is not set. +* \note Card emulation from Host and Card Emulation from UICC are mutually +* exclusive modes, i.e: only one can be enabled at a time. Using +* this function to enable one of the emulation modes implicitly disables the +* the other. eg. Setting Type A (or Type B) Emulation from Host disables +* card emulation from UICC and vice versa. +* +* \param[in] psHwReference Hardware Reference, pre-initialized by +* upper layer. \n +* +* \param[in] eCfgType Configuration type which can take one of the +* enum values of \ref phHal_eConfigType_t. Each +* config type is associated with its corresponding +* information which is passed using the uCfg structure. +* +* +* \param[in] uCfg Union containing configuration information, +* which will be interpreted based on eCfgType +* parameter. +* +* +* \param[in] pConfigCallback This callback has to be called once Hal +* completes the Configuration. +* +* \param[in] pContext Upper layer context to be returned in the +* callback. +* +* \retval NFCSTATUS_INVALID_PARAMETER Wrong Parameter values. +* +* \retval NFCSTATUS_NOT_INITIALISED Hal is not initialized. +* +* \retval NFCSTATUS_BUSY Cannot Configure Hal in +* Current state. +* +* \retval NFCSTATUS_INSUFFICIENT_RESOURCES System Resources insufficient. +* +* \retval NFCSTATUS_PENDING Configuration request accepted +* and Configuration is in progress. +* +* \retval NFCSTATUS_INVALID_PARAMETER One or more of the supplied +* parameters could not be properly +* interpreted. +* \retval Others Errors related to the lower layers +*/ + +extern NFCSTATUS phHal4Nfc_ConfigParameters( + phHal_sHwReference_t *psHwReference, + phHal_eConfigType_t eCfgType, + phHal_uConfig_t *uCfg, + pphHal4Nfc_GenCallback_t pConfigCallback, + void *pContext + ); + +/** + * \if hal + * \ingroup grp_hal_nfci + * \else + * \ingroup grp_mw_external_hal_funcs + * \endif + * + * This function is called to connect to a one (out of many if multiple + * devices are discovered) already discovered Remote Device notified + * through register notification. The Remote Device Information structure is + * already pre-initialized with data (e.g. from Discovery Notificaiton + * Callback) A new session is started after the connect function returns + * successfully. The session ends with a successful disconnect + * (see \ref phHal4Nfc_Disconnect). + * + * \param[in] psHwReference Hardware Reference, pre-initialized by + * upper layer. \n + * + * \param[in,out] psRemoteDevInfo Points to the Remote Device Information + * structure. The members of it can be + * re-used from a previous session. + * + * \param[in] pNotifyConnectCb Upper layer callback to be called for + * notifying Connect Success/Failure + * + * \param[in] pContext Upper layer context to be returned in + * pNotifyConnectCb. + * + * \retval NFCSTATUS_PENDING Request initiated, result will + * be informed through the callback. + * \retval NFCSTATUS_INVALID_PARAMETER One or more of the supplied + * parameters could not be + * properly interpreted. + * \retval NFCSTATUS_FAILED More than one phHal4Nfc_Connect + * is not allowed during a session + * on the same remote device. The + * session has to be closed before + * (see\ref phHal4Nfc_Disconnect). + * \retval NFCSTATUS_NOT_INITIALIZED Hal is not initialized. + * \retval NFCSTATUS_FEATURE_NOT_SUPPORTED Reactivation is not supported for + * NfcIp target and Jewel/Topaz + * remote device types. + * \retval NFCSTATUS_INVALID_REMOTE_DEVICE The Remote Device Identifier is + * not valid. + * \retval Others Errors related to the lower layers. + * + * \if hal + * \sa \ref phHal4Nfc_Disconnect + * \endif + */ +extern NFCSTATUS phHal4Nfc_Connect( + phHal_sHwReference_t *psHwReference, + phHal_sRemoteDevInformation_t *psRemoteDevInfo, + pphHal4Nfc_ConnectCallback_t pNotifyConnectCb, + void *pContext + ); + + +/** + * \if hal + * \ingroup grp_hal_nfci + * \else + * \ingroup grp_mw_external_hal_funcs + * \endif + * + * The phHal4Nfc_Transceive function allows to send data to and receive data + * from the Remote Device selected by the caller.It is also used by the + * NFCIP1 Initiator while performing a transaction with the NFCIP1 target. + * The caller has to provide the Remote Device Information structure and the + * command in order to communicate with the selected remote device.For P2P + * transactions the command type will not be used. + * + * + * \note the RecvData should be valid until the pTrcvCallback has been called. + * + * + * \param[in] psHwReference Hardware Reference, pre-initialized by + * upper layer. \n + * + * \param[in,out] psTransceiveInfo Information required by transceive is + * concealed in this structure.It contains + * the send,receive buffers and their + * lengths. + * + * \param[in] psRemoteDevInfo Points to the Remote Device Information + * structure which identifies the selected + * Remote Device. + * + * \param[in] pTrcvCallback Callback function for returning the + * received response or error. + * + * \param[in] pContext Upper layer context to be returned in + * the callback. + * + * \retval NFCSTATUS_PENDING Transceive initiated.pTrcvCallback + * will return the response or error. + * \retval NFCSTATUS_NOT_INITIALIZED Hal is not initialized. + * \retval NFCSTATUS_SUCCESS This status is used when send data + * length is zero and HAL contains + * previously more bytes from previous + * receive. \n + * \retval NFCSTATUS_INVALID_PARAMETER One or more of the supplied + * parameters could not be properly + * interpreted or are invalid. + * \retval NFCSTATUS_INVALID_DEVICE The device has not been opened or + * has been disconnected meanwhile. + * \retval NFCSTATUS_FEATURE_NOT_SUPPORTED Transaction on this Device type is + * not supported. + * \retval NFCSTATUS_BUSY Previous transaction is not + * completed. + * \retval NFCSTATUS_INSUFFICIENT_RESOURCES System resources are insufficient + * to complete the request at that + * point in time. + * \retval NFCSTATUS_MORE_INFORMATION Received number of bytes is greater + * than receive buffer provided by the + * upper layer.Extra bytes will be + * retained by Hal and returned on next + * call to transceive. + * \retval Others Errors related to the lower layers. + * + */ +extern NFCSTATUS phHal4Nfc_Transceive( + phHal_sHwReference_t *psHwReference, + phHal_sTransceiveInfo_t *psTransceiveInfo, + phHal_sRemoteDevInformation_t *psRemoteDevInfo, + pphHal4Nfc_TransceiveCallback_t pTrcvCallback, + void *pContext + ); + + + + +/** + * \if hal + * \ingroup grp_hal_nfci + * \else + * \ingroup grp_mw_external_hal_funcs + * \endif + * + * The function allows to disconnect from a specific Remote Device. This + * function closes the session opened with \ref phHal4Nfc_Connect "Connect".It + * is also used to switch from wired to virtual mode in case the discovered + * device is SmartMX in wired mode. The status of discovery wheel after + * disconnection is determined by the ReleaseType parameter. + * + * + * + * \param[in] psHwReference Hardware Reference, pre-initialized by + * upper layer. \n + * \param[in,out] psRemoteDevInfo Points to the valid (connected) Remote + * Device Information structure. + * + * \param[in] ReleaseType Defines various modes of releasing an acquired + * target or tag + * + * \param[in] pDscntCallback Callback function to notify + * disconnect success/error. + * + * \param[in] pContext Upper layer context to be returned in + * the callback. + * + * + * \retval NFCSTATUS_PENDING Disconnect initiated.pDscntCallback + * will return the response or error. + * \retval NFCSTATUS_INVALID_PARAMETER One or more of the supplied + * parameters could not be properly + * interpreted. + * \retval NFCSTATUS_INVALID_REMOTE_DEVICE The device has not been opened + * before or has already been closed. + * \retval NFCSTATUS_NOT_INITIALIZED Hal is not initialized. + * \retval Others Errors related to the lower layers. + * + * \if hal + * \sa \ref phHal4Nfc_Connect + * \endif + */ +extern NFCSTATUS phHal4Nfc_Disconnect( + phHal_sHwReference_t *psHwReference, + phHal_sRemoteDevInformation_t *psRemoteDevInfo, + phHal_eReleaseType_t ReleaseType, + pphHal4Nfc_DiscntCallback_t pDscntCallback, + void *pContext + ); + +/** +* \if hal +* \ingroup grp_hal_common +* \else +* \ingroup grp_mw_external_hal_funcs +* \endif +* +* The function allows to do a one time check on whether the connected target +* is still present in the field of the Reader. The call back returns the +* result of the presence check sequence indicating whether it is still present +* or moved out of the reader field. +* +* \param[in] psHwReference Hardware Reference, pre-initialized by +* upper layer. \n +* +* \param[in] pPresenceChkCb Callback function called on completion of the +* presence check sequence or in case an error +* has occurred.. +* +* \param[in] context Upper layer context to be returned in the +* callback. +* +* \retval NFCSTATUS_PENDING Call successfully issued to lower layer. +* Status will be returned in pPresenceChkCb. +* +* \retval NFCSTATUS_NOT_INITIALISED The device has not been opened or has +* been disconnected meanwhile. +* +* \retval NFCSTATUS_BUSY Previous presence check callback has not +* been received +* +* \retval NFCSTATUS_INVALID_PARAMETER One or more of the supplied parameters +* could not be properly interpreted. +* +* \retval NFCSTATUS_RELEASED P2P target has been released by Initiator. +* \retval Others Errors related to the lower layers +* +*/ +extern NFCSTATUS phHal4Nfc_PresenceCheck( + phHal_sHwReference_t *psHwReference, + pphHal4Nfc_GenCallback_t pPresenceChkCb, + void *context + ); + + +/** + * \if hal + * \ingroup grp_hal_common + * \else + * \ingroup grp_mw_external_hal_funcs + * \endif + * + * The I/O Control function allows the caller to use (vendor-) specific + * functionality provided by the lower layer or by the hardware. Each feature + * is accessible via a specific IOCTL Code and has to be documented by the + * provider of the driver and the hardware. + * See "IOCTL Codes" for the definition of a standard command set.\n + * + * + * \param[in] psHwReference Hardware Reference, pre-initialized by + * upper layer. \n + * \param[in] IoctlCode Control code for the operation. + * This value identifies the specific + * operation to be performed and are defined + * in \ref phNfcIoctlCode.h + * + * \param[in] pInParam Pointer to any input data structure + * containing data which is interpreted + * based on Ioctl code and the length of + * the data. + * + * \param[in] pOutParam Pointer to output data structure + * containing data which is returned as a + * result of the Ioctl operation and the + * length of the data. + * + * \param[in] pIoctlCallback callback function called in case an + * error has occurred while performing + * requested operation,or on successful + * completion of the request + * + * \param[in] pContext Upper layer context to be returned in + * the callback. + * + * \retval NFCSTATUS_SUCCESS Success. + * \retval NFCSTATUS_PENDING Call issued to lower layer.Status will + * be notified in pIoctlCallback. + * \retval NFCSTATUS_INVALID_PARAMETER One or more of the supplied parameters + * could not be properly interpreted. + * \retval NFCSTATUS_NOT_INITIALIZED Hal is not initialized. + * \retval Others Errors related to the lower layers. + * + */ +extern NFCSTATUS phHal4Nfc_Ioctl( + phHal_sHwReference_t *psHwReference, + uint32_t IoctlCode, + phNfc_sData_t *pInParam, + phNfc_sData_t *pOutParam, + pphHal4Nfc_IoctlCallback_t pIoctlCallback, + void *pContext + ); + + + +/** + * \if hal + * \ingroup grp_hal_common + * \else + * \ingroup grp_mw_external_hal_funcs + * \endif + * + * Closes the link to the NFC device. All configurations/setups + * done until now are invalidated.To restart communication, phHal4Nfc_Open + * needs to be called. The pClosecallback is called when all steps + * in the close sequence are completed. + * + * + * \param[in] psHwReference Hardware Reference, pre-initialized by + * upper layer. \n + * + * \param[in] pCloseCallback Callback function called on completion of + * the close sequence or in case an error + * has occurred.. + * + * \param[in] pContext Upper layer context to be returned + * in the callback. + * + * \retval NFCSTATUS_SUCCESS Closing successful. + * \retval NFCSTATUS_NOT_INITIALIZED The device has not been opened or has + * been disconnected meanwhile. + * \retval NFCSTATUS_INVALID_PARAMETER One or more of the supplied parameters + * could not be properly interpreted. + * \retval NFCSTATUS_BUSY Configuration is in progress.Shutdown + * is not allowed until configure complete. + * \retval Others Errors related to the lower layers. + * + * \if hal + * \sa \ref phHal4Nfc_Open + * \endif + */ +extern NFCSTATUS phHal4Nfc_Close( + phHal_sHwReference_t *psHwReference, + pphHal4Nfc_GenCallback_t pCloseCallback, + void *pContext + ); + + +/** + * \if hal + * \ingroup grp_hal_common + * \else + * \ingroup grp_mw_external_hal_funcs + * \endif + * + * Forcibly shutdown the HAl.This API makes a call to forcibly shutdown the + * lower layer and frees all resources in use by Hal before shutting down.The + * API always succeeds.It does not however reset the target. + * + * \param[in] psHwReference Hardware Reference, pre-initialized by + * upper layer. \n + * + * \param[in] pConfig Reserved for future use. + * + * + */ +extern void phHal4Nfc_Hal4Reset( + phHal_sHwReference_t *psHwReference, + void *pConfig + ); + + +/** +* \if hal +* \ingroup grp_hal_common +* \else +* \ingroup grp_mw_external_hal_funcs +* \endif +* +* The function is used by the NFCIP1 Target to respond to packect received +* from NFCIP1 initiator. pSendCallback() +* is called , when all steps in the send sequence are completed. +* +* \param[in] psHwReference Hardware Reference, pre-initialized by +* upper layer. \n +* +* \param[in] psTransactInfo information required for transferring +* the data +* +* \param[in] sTransferData Data and the length of the data to be +* transferred +* +* \param[in] pSendCallback Callback function called on completion +* of the NfcIP sequence or in case an +* error has occurred. +* +* \param[in] pContext Upper layer context to be returned in +* the callback. +* +* \retval NFCSTATUS_PENDING Send is in progress. +* \retval NFCSTATUS_INVALID_DEVICE The device has not been opened or has +* been disconnected meanwhile. +* \retval NFCSTATUS_INVALID_PARAMETER One or more of the supplied parameters +* could not be properly interpreted. +* \retval NFCSTATUS_NOT_INITIALIZED Hal is not initialized. +* \retval Others Errors related to the lower layers. +* +* +*/ +extern +NFCSTATUS +phHal4Nfc_Send( + phHal_sHwReference_t *psHwReference, + phHal4Nfc_TransactInfo_t *psTransactInfo, + phNfc_sData_t sTransferData, + pphHal4Nfc_SendCallback_t pSendCallback, + void *pContext + ); + +/** +* \if hal +* \ingroup grp_hal_common +* \else +* \ingroup grp_mw_external_hal_funcs +* \endif +* +* This function is called by the NfcIP Peer to wait for receiving data from +* the other peer.It is used only by the NfcIP Target. +* \note NOTE: After this function is called, its mandatory to wait for the +* pphHal4Nfc_ReceiveCallback_t callback, before calling any other function. +* Only functions allowed are phHal4Nfc_Close() and phHal4Nfc_Hal4Reset(). +* +* +* \param[in] psHwReference Hardware Reference, pre-initialized by +* upper layer. \n +* +* \param[in] psTransactInfo information required for transferring the +* data +* +* \param[in] pReceiveCallback Callback function called after receiving +* the data or in case an error has +* has occurred. +* +* \param[in] pContext Upper layer context to be returned +* in the callback. +* +* \retval NFCSTATUS_PENDING Receive is in progress. +* \retval NFCSTATUS_INVALID_DEVICE The device has not been opened or has +* been disconnected meanwhile. +* \retval NFCSTATUS_INVALID_PARAMETER One or more of the supplied parameters +* could not be properly interpreted. +* \retval NFCSTATUS_NOT_INITIALIZED Hal is not initialized. +* \retval Others Errors related to the lower layers +* +*/ +extern +NFCSTATUS +phHal4Nfc_Receive( + phHal_sHwReference_t *psHwReference, + phHal4Nfc_TransactInfo_t *psTransactInfo, + pphHal4Nfc_ReceiveCallback_t pReceiveCallback, + void *pContext + ); + + +/** +* \if hal +* \ingroup grp_hal_common +* \else +* \ingroup grp_mw_external_hal_funcs +* \endif +* +* This API is a synchronous call used to register a listener for either tag +* discovery, Secure element notification or P2P Notification or a general +* notification handler for all the three. +* +* +* \param[in] psHwRef Hardware Reference, pre-initialized by +* upper layer. \n +* +* \param[in] eRegisterType Type of Notification registered.Informs +* whether upper layer is interested in Tag +* Discovery,secure element or P2P notification. +* +* \param[in] pNotificationHandler Notification callback.If this parameter is +* NULL,any notification from Hci will be +* ignored and upper layer will not be notified +* of the event. +* +* \param[in] Context Upper layer context. +* +* \retval NFCSTATUS_SUCCESS Notification unregister successful. +* +* \retval NFCSTATUS_INVALID_PARAMETER One or more of the supplied parameters +* could not be properly interpreted. +* \retval NFCSTATUS_NOT_INITIALIZED Hal is not initialized. +* +*/ +extern NFCSTATUS phHal4Nfc_RegisterNotification( + phHal_sHwReference_t *psHwRef, + phHal4Nfc_RegisterType_t eRegisterType, + pphHal4Nfc_Notification_t pNotificationHandler, + void *Context + ); + +/** +* \if hal +* \ingroup grp_hal_common +* \else +* \ingroup grp_mw_external_hal_funcs +* \endif +* +* This API is a synchronous call used to unregister a listener for either tag +* discovery, Secure element notification or P2P Notification, previously +* registered using \ref phHal4Nfc_RegisterNotification. +* +* \param[in] psHwReference Hardware Reference, pre-initialized by +* upper layer. \n +* +* \param[in] eRegisterType Type of registration ,tells whether upper +* layer is interested in unregistering for +* Tag Discovery,Secure element or P2P. \n +* +* \param[in] Context Upper layer context. +* +* \retval NFCSTATUS_SUCCESS Notification unregister successful. +* +* \retval NFCSTATUS_INVALID_PARAMETER One or more of the supplied parameters +* could not be properly interpreted. +* +* \retval NFCSTATUS_NOT_INITIALIZED Hal is not initialized. +* +* +*/ +extern NFCSTATUS phHal4Nfc_UnregisterNotification( + phHal_sHwReference_t *psHwReference, + phHal4Nfc_RegisterType_t eRegisterType, + void *Context + ); + + +/** +* \if hal +* \ingroup grp_hal_common +* \else +* \ingroup grp_mw_external_hal_funcs +* \endif +* +* This function is called to switch the SmartMX to Wired Mode. After switching +* to Wired mode the SmartMX can be discovered through Tag Discovery like a normal +* tag and used in the same manner as a tag. SmartMx returns to previous mode +* (Virtual or Off) when the tag is relased by phHal4Nfc_Disconnect +* +* +* \param[in] psHwReference Hardware Reference, pre-initialized by +* upper layer. \n +* +* \param[in] smx_mode Mode to which the switch should be made. +* +* \param[in] pSwitchModecb Callback for Switch mode complete +* with success/error notification. +* +* \param[in] pContext Upper layer context. +* +* \retval NFCSTATUS_PENDING Switch in progress.Status will be +* returned in pSwitchModecb. +* \retval NFCSTATUS_INVALID_PARAMETER One or more of the supplied +* parameters could not be properly +* interpreted. +* \retval NFCSTATUS_NOT_INITIALIZED Hal is not initialized. +* \retval NFCSTATUS_BUSY Configuration in Progress or +* remote device is connected. +* \retval NFCSTATUS_INSUFFICIENT_RESOURCES System resources are insufficient +* to complete the request at that +* point in time. +* \retval NFCSTATUS_FAILED No listener has been registered +* by the upper layer for Emulation +* before making this call. +* \retval Others Errors related to the lower +* layers. +*/ +extern NFCSTATUS phHal4Nfc_Switch_SMX_Mode( + phHal_sHwReference_t *psHwReference, + phHal_eSmartMX_Mode_t smx_mode, + pphHal4Nfc_GenCallback_t pSwitchModecb, + void *pContext + ); + + +/** +* \if hal +* \ingroup grp_hal_common +* \else +* \ingroup grp_mw_external_hal_funcs +* \endif +* +* This function is called to switch the UICC on or Off. +* +* +* \param[in] psHwReference Hardware Reference, pre-initialized by +* upper layer. \n +* +* \param[in] smx_mode Mode to which the switch should be made. +* +* \param[in] pSwitchModecb Callback for Switch mode complete +* with success/error notification. +* +* \param[in] pContext Upper layer context. +* +* \retval NFCSTATUS_PENDING Switch in progress.Status will be +* returned in pSwitchModecb. +* \retval NFCSTATUS_INVALID_PARAMETER One or more of the supplied +* parameters could not be properly +* interpreted. +* \retval NFCSTATUS_NOT_INITIALIZED Hal is not initialized. +* \retval NFCSTATUS_BUSY Configuration in Progress or +* remote device is connected. +* \retval NFCSTATUS_INSUFFICIENT_RESOURCES System resources are insufficient +* to complete the request at that +* point in time. +* \retval NFCSTATUS_FAILED No listener has been registered +* by the upper layer for Emulation +* before making this call. +* \retval Others Errors related to the lower +* layers. +*/ +extern NFCSTATUS phHal4Nfc_Switch_Swp_Mode( + phHal_sHwReference_t *psHwReference, + phHal_eSWP_Mode_t swp_mode, + pphHal4Nfc_GenCallback_t pSwitchModecb, + void *pContext + ); + +#endif /* end of PHHAL4NFC_H */ + + |