xref: /external/libnfc-nci/src/nfa/include/nfa_snep_api.h

/******************************************************************************
 *
 *  Copyright (C) 2010-2013 Broadcom Corporation
 *
 *  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.
 *
 ******************************************************************************/


/******************************************************************************
 *
 *  This is the public interface file for NFA SNEP, Broadcom's NFC
 *  application layer for mobile phones.
 *
 ******************************************************************************/
#ifndef NFA_SNEP_API_H
#define NFA_SNEP_API_H

#include "nfa_api.h"

/*****************************************************************************
**  Constants and data types
*****************************************************************************/
#define NFA_SNEP_VERSION                0x10    /* SNEP Version 1.0          */

#define NFA_SNEP_REQ_CODE_CONTINUE      0x00    /* send remaining fragments         */
#define NFA_SNEP_REQ_CODE_GET           0x01    /* return an NDEF message           */
#define NFA_SNEP_REQ_CODE_PUT           0x02    /* accept an NDEF message           */
#define NFA_SNEP_REQ_CODE_REJECT        0x7F    /* do not send remaining fragments  */

#define tNFA_SNEP_REQ_CODE  UINT8

#define NFA_SNEP_RESP_CODE_CONTINUE     0x80    /* continue send remaining fragments    */
#define NFA_SNEP_RESP_CODE_SUCCESS      0x81    /* the operation succeeded              */
#define NFA_SNEP_RESP_CODE_NOT_FOUND    0xC0    /* resource not found                   */
#define NFA_SNEP_RESP_CODE_EXCESS_DATA  0xC1    /* resource exceeds data size limit     */
#define NFA_SNEP_RESP_CODE_BAD_REQ      0xC2    /* malformed request not understood     */
#define NFA_SNEP_RESP_CODE_NOT_IMPLM    0xE0    /* unsupported functionality requested  */
#define NFA_SNEP_RESP_CODE_UNSUPP_VER   0xE1    /* unsupported protocol version         */
#define NFA_SNEP_RESP_CODE_REJECT       0xFF    /* do not send remaining fragments      */

#define tNFA_SNEP_RESP_CODE UINT8

/* NFA SNEP callback events */
#define NFA_SNEP_REG_EVT                    0x00    /* Server/client Registeration Status   */
#define NFA_SNEP_ACTIVATED_EVT              0x01    /* LLCP link has been activated, client only   */
#define NFA_SNEP_DEACTIVATED_EVT            0x02    /* LLCP link has been deactivated, client only */
#define NFA_SNEP_CONNECTED_EVT              0x03    /* Data link has been created           */
#define NFA_SNEP_GET_REQ_EVT                0x04    /* GET request from client              */
#define NFA_SNEP_PUT_REQ_EVT                0x05    /* PUT request from client              */
#define NFA_SNEP_GET_RESP_EVT               0x06    /* GET response from server             */
#define NFA_SNEP_PUT_RESP_EVT               0x07    /* PUT response from server             */
#define NFA_SNEP_DISC_EVT                   0x08    /* Failed to connect or disconnected    */

#define NFA_SNEP_ALLOC_BUFF_EVT	            0x09    /* Request to allocate a buffer for NDEF*/
#define NFA_SNEP_GET_RESP_CMPL_EVT          0x0A    /* GET response sent to client          */

#define NFA_SNEP_DEFAULT_SERVER_STARTED_EVT 0x0B    /* SNEP default server is started       */
#define NFA_SNEP_DEFAULT_SERVER_STOPPED_EVT 0x0C    /* SNEP default server is stopped       */

typedef UINT8 tNFA_SNEP_EVT;

#define NFA_SNEP_ANY_SAP         LLCP_INVALID_SAP

/* Data for NFA_SNEP_REG_EVT */
typedef struct
{
    tNFA_STATUS         status;
    tNFA_HANDLE         reg_handle;         /* handle for registered server/client */
    char                service_name[LLCP_MAX_SN_LEN + 1];      /* only for server */
} tNFA_SNEP_REG;

/* Data for NFA_SNEP_ACTIVATED_EVT */
typedef struct
{
    tNFA_HANDLE         client_handle;      /* handle for registered client    */
} tNFA_SNEP_ACTIVATED;

/* Data for NFA_SNEP_DEACTIVATED_EVT */
typedef tNFA_SNEP_ACTIVATED tNFA_SNEP_DEACTIVATED;

/* Data for NFA_SNEP_CONNECTED_EVT */
/*
** for server, new handle will be assigned for conn_handle
** for client, handle used in NFA_SnepConnect () is returned in conn_handle
*/
typedef struct
{
    tNFA_HANDLE         reg_handle;         /* server/client handle            */
    tNFA_HANDLE         conn_handle;        /* handle for data link connection */
} tNFA_SNEP_CONNECT;

/* Data for NFA_SNEP_GET_REQ_EVT */
typedef struct
{
    tNFA_HANDLE         conn_handle;        /* handle for data link connection */
    UINT32              acceptable_length;  /* acceptable length from client   */
    UINT32              ndef_length;        /* NDEF message length             */
    UINT8               *p_ndef;            /* NDEF message                    */
} tNFA_SNEP_GET_REQ;

/* Data for NFA_SNEP_PUT_REQ_EVT */
typedef struct
{
    tNFA_HANDLE         conn_handle;        /* handle for data link connection */
    UINT32              ndef_length;        /* NDEF message length             */
    UINT8               *p_ndef;            /* NDEF message                    */
} tNFA_SNEP_PUT_REQ;

/* Data for NFA_SNEP_GET_RESP_EVT */
typedef struct
{
    tNFA_HANDLE         conn_handle;        /* handle for data link connection */
    tNFA_SNEP_RESP_CODE resp_code;          /* response code from server       */
    UINT32              ndef_length;        /* NDEF message length             */
    UINT8               *p_ndef;            /* NDEF message                    */
} tNFA_SNEP_GET_RESP;

/* Data for NFA_SNEP_PUT_RESP_EVT */
typedef struct
{
    tNFA_HANDLE         conn_handle;        /* handle for data link connection */
    tNFA_SNEP_RESP_CODE resp_code;          /* response code from server       */
} tNFA_SNEP_PUT_RESP;

/* Data for NFA_SNEP_DISC_EVT */
typedef struct
{
    tNFA_HANDLE         conn_handle;        /* handle for data link connection */
                                            /* client_handle if connection failed */
} tNFA_SNEP_DISC;

/* Data for NFA_SNEP_ALLOC_BUFF_EVT */
typedef struct
{
    tNFA_HANDLE         conn_handle;        /* handle for data link connection                */
    tNFA_SNEP_REQ_CODE  req_code;           /* NFA_SNEP_REQ_CODE_GET or NFA_SNEP_REQ_CODE_PUT */
    tNFA_SNEP_RESP_CODE resp_code;          /* Response code if cannot allocate buffer        */
    UINT32              ndef_length;        /* NDEF message length                            */
    UINT8               *p_buff;            /* buffer for NDEF message                        */
} tNFA_SNEP_ALLOC;

/* Data for NFA_SNEP_GET_RESP_CMPL_EVT */
typedef struct
{
    tNFA_HANDLE         conn_handle;        /* handle for data link connection */
    UINT8               *p_buff;            /* buffer for NDEF message         */
} tNFA_SNEP_GET_RESP_CMPL;

/* Union of all SNEP callback structures */
typedef union
{
    tNFA_SNEP_REG           reg;            /* NFA_SNEP_REG_EVT             */
    tNFA_SNEP_ACTIVATED     activated;      /* NFA_SNEP_ACTIVATED_EVT       */
    tNFA_SNEP_DEACTIVATED   deactivated;    /* NFA_SNEP_DEACTIVATED_EVT     */
    tNFA_SNEP_CONNECT       connect;        /* NFA_SNEP_CONNECTED_EVT       */
    tNFA_SNEP_GET_REQ       get_req;        /* NFA_SNEP_GET_REQ_EVT         */
    tNFA_SNEP_PUT_REQ       put_req;        /* NFA_SNEP_PUT_REQ_EVT         */
    tNFA_SNEP_GET_RESP      get_resp;       /* NFA_SNEP_GET_RESP_EVT        */
    tNFA_SNEP_PUT_RESP      put_resp;       /* NFA_SNEP_PUT_RESP_EVT        */
    tNFA_SNEP_DISC          disc;           /* NFA_SNEP_DISC_EVT            */
    tNFA_SNEP_ALLOC         alloc;          /* NFA_SNEP_ALLOC_BUFF_EVT      */
    tNFA_SNEP_GET_RESP_CMPL get_resp_cmpl;  /* NFA_SNEP_GET_RESP_CMPL_EVT   */
} tNFA_SNEP_EVT_DATA;

/* NFA SNEP callback */
typedef void (tNFA_SNEP_CBACK) (tNFA_SNEP_EVT event, tNFA_SNEP_EVT_DATA *p_data);

/*****************************************************************************
**  External Function Declarations
*****************************************************************************/
#ifdef __cplusplus
extern "C"
{
#endif

/*******************************************************************************
**
** Function         NFA_SnepStartDefaultServer
**
** Description      This function is called to listen to SAP, 0x04 as SNEP default
**                  server ("urn:nfc:sn:snep") on LLCP.
**
**                  NFA_SNEP_DEFAULT_SERVER_STARTED_EVT without data will be returned.
**
** Note:            If RF discovery is started, NFA_StopRfDiscovery()/NFA_RF_DISCOVERY_STOPPED_EVT
**                  should happen before calling this function
**
** Returns          NFA_STATUS_OK if successfully initiated
**                  NFA_STATUS_FAILED otherwise
**
*******************************************************************************/
NFC_API extern tNFA_STATUS NFA_SnepStartDefaultServer (tNFA_SNEP_CBACK *p_cback);

/*******************************************************************************
**
** Function         NFA_SnepStopDefaultServer
**
** Description      This function is called to stop SNEP default server on LLCP.
**
**                  NFA_SNEP_DEFAULT_SERVER_STOPPED_EVT without data will be returned.
**
** Note:            If RF discovery is started, NFA_StopRfDiscovery()/NFA_RF_DISCOVERY_STOPPED_EVT
**                  should happen before calling this function
**
** Returns          NFA_STATUS_OK if successfully initiated
**                  NFA_STATUS_FAILED otherwise
**
*******************************************************************************/
NFC_API extern tNFA_STATUS NFA_SnepStopDefaultServer (tNFA_SNEP_CBACK *p_cback);

/*******************************************************************************
**
** Function         NFA_SnepRegisterServer
**
** Description      This function is called to listen to a SAP as SNEP server.
**
**                  If server_sap is set to NFA_SNEP_ANY_SAP, then NFA will allocate
**                  a SAP between LLCP_LOWER_BOUND_SDP_SAP and LLCP_UPPER_BOUND_SDP_SAP
**
**                  NFC Forum default SNEP server ("urn:nfc:sn:snep") may be launched
**                  by NFA_SnepStartDefaultServer ().
**
**                  NFA_SNEP_REG_EVT will be returned with status, handle and service name.
**
** Note:            If RF discovery is started, NFA_StopRfDiscovery()/NFA_RF_DISCOVERY_STOPPED_EVT
**                  should happen before calling this function
**
** Returns          NFA_STATUS_OK if successfully initiated
**                  NFA_STATUS_INVALID_PARAM if p_service_name or p_cback is NULL
**                  NFA_STATUS_FAILED otherwise
**
*******************************************************************************/
NFC_API extern tNFA_STATUS NFA_SnepRegisterServer (UINT8           server_sap,
                                                   char            *p_service_name,
                                                   tNFA_SNEP_CBACK *p_cback);

/*******************************************************************************
**
** Function         NFA_SnepRegisterClient
**
** Description      This function is called to register SNEP client.
**                  NFA_SNEP_REG_EVT will be returned with status, handle
**                  and zero-length service name.
**
** Returns          NFA_STATUS_OK if successfully initiated
**                  NFA_STATUS_INVALID_PARAM if p_cback is NULL
**                  NFA_STATUS_FAILED otherwise
**
*******************************************************************************/
NFC_API extern tNFA_STATUS NFA_SnepRegisterClient (tNFA_SNEP_CBACK *p_cback);

/*******************************************************************************
**
** Function         NFA_SnepDeregister
**
** Description      This function is called to stop listening as SNEP server
**                  or SNEP client. Application shall use reg_handle returned in
**                  NFA_SNEP_REG_EVT.
**
** Note:            If this function is called to de-register a SNEP server and RF
**                  discovery is started, NFA_StopRfDiscovery()/NFA_RF_DISCOVERY_STOPPED_EVT
**                  should happen before calling this function
**
** Returns          NFA_STATUS_OK if successfully initiated
**                  NFA_STATUS_BAD_HANDLE if handle is not valid
**                  NFA_STATUS_FAILED otherwise
**
*******************************************************************************/
NFC_API extern tNFA_STATUS NFA_SnepDeregister (tNFA_HANDLE reg_handle);

/*******************************************************************************
**
** Function         NFA_SnepConnect
**
** Description      This function is called by client to create data link connection
**                  to SNEP server on peer device.
**
**                  Client handle and service name of server to connect shall be provided.
**                  A conn_handle will be returned in NFA_SNEP_CONNECTED_EVT, if
**                  successfully connected. Otherwise NFA_SNEP_DISC_EVT will be returned.
**
** Returns          NFA_STATUS_OK if successfully initiated
**                  NFA_STATUS_BAD_HANDLE if handle is not valid
**                  NFA_STATUS_INVALID_PARAM if p_service_name or p_cback is NULL
**                  NFA_STATUS_FAILED otherwise
**
*******************************************************************************/
NFC_API extern tNFA_STATUS NFA_SnepConnect (tNFA_HANDLE     client_handle,
                                            char            *p_service_name);

/*******************************************************************************
**
** Function         NFA_SnepGet
**
** Description      This function is called by client to send GET request.
**
**                  Application shall allocate a buffer and put NDEF message with
**                  desired record type to get from server. NDEF message from server
**                  will be returned in the same buffer with NFA_SNEP_GET_RESP_EVT.
**                  The size of buffer will be used as "Acceptable Length".
**
**                  NFA_SNEP_GET_RESP_EVT or NFA_SNEP_DISC_EVT will be returned
**                  through registered p_cback. Application may free the buffer
**                  after receiving these events.
**
**
** Returns          NFA_STATUS_OK if successfully initiated
**                  NFA_STATUS_BAD_HANDLE if handle is not valid
**                  NFA_STATUS_FAILED otherwise
**
*******************************************************************************/
NFC_API extern tNFA_STATUS NFA_SnepGet (tNFA_HANDLE     conn_handle,
                                        UINT32          buff_length,
                                        UINT32          ndef_length,
                                        UINT8           *p_ndef_buff);

/*******************************************************************************
**
** Function         NFA_SnepPut
**
** Description      This function is called by client to send PUT request.
**
**                  Application shall allocate a buffer and put desired NDEF message
**                  to send to server.
**
**                  NFA_SNEP_PUT_RESP_EVT or NFA_SNEP_DISC_EVT will be returned
**                  through p_cback. Application may free the buffer after receiving
**                  these events.
**
** Returns          NFA_STATUS_OK if successfully initiated
**                  NFA_STATUS_BAD_HANDLE if handle is not valid
**                  NFA_STATUS_INVALID_PARAM if p_service_name or p_cback is NULL
**                  NFA_STATUS_FAILED otherwise
**
*******************************************************************************/
NFC_API extern tNFA_STATUS NFA_SnepPut (tNFA_HANDLE     conn_handle,
                                        UINT32          ndef_length,
                                        UINT8           *p_ndef_buff);

/*******************************************************************************
**
** Function         NFA_SnepGetResponse
**
** Description      This function is called by server to send response of GET request.
**
**                  When server application receives NFA_SNEP_ALLOC_BUFF_EVT,
**                  it shall allocate a buffer for incoming NDEF message and
**                  pass the pointer within callback context. This buffer will be
**                  returned with NFA_SNEP_GET_REQ_EVT after receiving complete
**                  NDEF message. If buffer is not allocated, NFA_SNEP_RESP_CODE_NOT_FOUND
**                  (Note:There is no proper response code for this case)
**                  or NFA_SNEP_RESP_CODE_REJECT will be sent to client.
**
**                  Server application shall provide conn_handle which is received in
**                  NFA_SNEP_GET_REQ_EVT.
**
**                  Server application shall allocate a buffer and put NDEF message if
**                  response code is NFA_SNEP_RESP_CODE_SUCCESS. Otherwise, ndef_length
**                  shall be set to zero.
**
**                  NFA_SNEP_GET_RESP_CMPL_EVT or NFA_SNEP_DISC_EVT will be returned
**                  through registered callback function. Application may free
**                  the buffer after receiving these events.
**
** Returns          NFA_STATUS_OK if successfully initiated
**                  NFA_STATUS_BAD_HANDLE if handle is not valid
**                  NFA_STATUS_FAILED otherwise
**
*******************************************************************************/
NFC_API extern tNFA_STATUS NFA_SnepGetResponse (tNFA_HANDLE         conn_handle,
                                                tNFA_SNEP_RESP_CODE resp_code,
                                                UINT32              ndef_length,
                                                UINT8               *p_ndef_buff);

/*******************************************************************************
**
** Function         NFA_SnepPutResponse
**
** Description      This function is called by server to send response of PUT request.
**
**                  When server application receives NFA_SNEP_ALLOC_BUFF_EVT,
**                  it shall allocate a buffer for incoming NDEF message and
**                  pass the pointer within callback context. This buffer will be
**                  returned with NFA_SNEP_PUT_REQ_EVT after receiving complete
**                  NDEF message.  If buffer is not allocated, NFA_SNEP_RESP_CODE_REJECT
**                  will be sent to client or NFA will discard request and send
**                  NFA_SNEP_RESP_CODE_SUCCESS (Note:There is no proper response code for
**                  this case).
**
**                  Server application shall provide conn_handle which is received in
**                  NFA_SNEP_PUT_REQ_EVT.
**
**                  NFA_SNEP_DISC_EVT will be returned through registered callback
**                  function when client disconnects data link connection.
**
** Returns          NFA_STATUS_OK if successfully initiated
**                  NFA_STATUS_BAD_HANDLE if handle is not valid
**                  NFA_STATUS_FAILED otherwise
**
*******************************************************************************/
NFC_API extern tNFA_STATUS NFA_SnepPutResponse (tNFA_HANDLE         conn_handle,
                                                tNFA_SNEP_RESP_CODE resp_code);

/*******************************************************************************
**
** Function         NFA_SnepDisconnect
**
** Description      This function is called to disconnect data link connection.
**                  discard any pending data if flush is set to TRUE
**
**                  Client application shall provide conn_handle in NFA_SNEP_GET_RESP_EVT
**                  or NFA_SNEP_PUT_RESP_EVT.
**
**                  Server application shall provide conn_handle in NFA_SNEP_GET_REQ_EVT
**                  or NFA_SNEP_PUT_REQ_EVT.
**
**                  NFA_SNEP_DISC_EVT will be returned
**
** Returns          NFA_STATUS_OK if successfully initiated
**                  NFA_STATUS_BAD_HANDLE if handle is not valid
**                  NFA_STATUS_FAILED otherwise
**
*******************************************************************************/
NFC_API extern tNFA_STATUS NFA_SnepDisconnect (tNFA_HANDLE conn_handle,
                                               BOOLEAN     flush);

/*******************************************************************************
**
** Function         NFA_SnepSetTraceLevel
**
** Description      This function sets the trace level for SNEP.  If called with
**                  a value of 0xFF, it simply returns the current trace level.
**
** Returns          The new or current trace level
**
*******************************************************************************/
NFC_API extern UINT8 NFA_SnepSetTraceLevel (UINT8 new_level);

#ifdef __cplusplus
}
#endif

#endif /* NFA_P2P_API_H */