files/include/FTInterface.h

   1 /*
   2  * Copyright (c) 2014 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * PROPRIETARY/CONFIDENTIAL
   5  *
   6  * This software is the confidential and proprietary information of SAMSUNG
   7  * ELECTRONICS ("Confidential Information"). You shall not disclose such
   8  * Confidential Information and shall use it only in accordance with the terms
   9  * of the license agreement you entered into with SAMSUNG ELECTRONICS. SAMSUNG
  10  * make no representations or warranties about the suitability of the software,
  11  * either express or implied, including but not limited to the implied
  12  * warranties of merchantability, fitness for a particular purpose, or
  13  * non-infringement. SAMSUNG shall not be liable for any damages suffered by
  14  * licensee as a result of using, modifying or distributing this software or
  15  * its derivatives.
  16  * licensee arising out of or related to this software.
  17  *
  18  */
  19 #ifndef _FTINTERFACE_H_
  20 #define _FTINTERFACE_H_
  21
  22 #include "SAPInterface.h"
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28 /***************************************************************************//**
  29  @brief  The enum defines the status codes that may be used to convey generic result codes as needed for FT interaction.
  30  @param  TRANSFER_SUCCESS: FT Transfer is successfull.
  31  @param  TRANSFER_COMPLETE_FAIL_FILE_IO: This error is received when the file to be sent/received doesn't exist or the path is invalid
  32  @param  TRANSFER_COMPLETE_FAIL_PEER_UNRESPONSIVE: This error is received during file transfer the remote end is unresponsive
  33  @param  TRANSFER_COMPLETE_FAIL_PEER_CONN_LOST: This error is received when during file transfer service connection was lost (e.g. could be due to BT off)
  34  @param  TRANSFER_COMPLETE_FAIL_PEER_CANCELLED: This error is received when peer cancelled file transfer
  35  @param  TRANSFER_COMPLETE_FAIL_SPACE_NOT_AVAILABLE: This error is received when peer doesn't have enough space to store the file
  36  ****************************************************************************/
  37 typedef enum tagFTResultVal
  38 {
  39         TRANSFER_SUCCESS = 0,
  40         TRANSFER_COMPLETE_FAIL_CHANNEL_IO = 1,
  41         TRANSFER_COMPLETE_FAIL_FILE_IO = 2,
  42         TRANSFER_COMPLETE_FAIL_CMD_DROPPED = 3,
  43         TRANSFER_COMPLETE_FAIL_PEER_UNRESPONSIVE = 4,
  44         TRANSFER_COMPLETE_FAIL_PEER_CONN_LOST = 5,
  45         TRANSFER_COMPLETE_FAIL_PEER_CANCELLED = 9,
  46         TRANSFER_COMPLETE_FAIL_SPACE_NOT_AVAILABLE = 11
  47 }FT_RESULT_VAL;
  48
  49 /*********************************************************************************//**
  50  @brief  The function sendFile is called by app to send a file
  51  @param pFilePath [in]: this is absolute file path for file to be send. If file doesn't exist, permission denied or invalid path,
  52                 App will be notified in FDefOnSendComplete() with error code TRANSFER_COMPLETE_FAIL_FILE_IO
  53  @param pPeerAgent [in]: Peer Agent to which file is to be sent
  54  @returns : returns file transfer dwTransactionId - Application should store this transaction id to track status of file transfer
  55  ****************************************************************************/
  56 int sendFile(char* pFilePath, PeerAgent* pPeerAgent);
  57
  58 /*********************************************************************************//**
  59  @brief  The function pushFile is called by app, which has multiple profile implementations in a single app.
  60  @param pFilePath [in]: this is absolute file path for file to be send. If file doesn't exist, permission denied or invalid path,
  61                 App will be notified in FDefOnSendComplete() with error code TRANSFER_COMPLETE_FAIL_FILE_IO
  62  @param pPeerAgent [in]: Peer Agent to which file is to be sent
  63  @param dwLocalAgentId [in]: Local agent ID of the agent which intents to use file transfer utility.
  64  @returns : returns file transfer dwTransactionId - Application should store this transaction id to track status of file transfer
  65  ****************************************************************************/
  66 int pushFile(char* pFilePath, PeerAgent* pPeerAgent, unsigned int dwLocalAgentId);
  67
  68 /**************************************************************************//**
  69  @brief  The function receiveFile is called by app to accept/reject a file req
  70  @param dwTransactionId [in]: file transfer transaction Id
  71  @param pFilePath [in]: this is absolute file path where file to be saved. If file path is invalid,
  72                 permission denied App will be notified in FDefOnReceiveComplete() with error code TRANSFER_COMPLETE_FAIL_FILE_IO
  73  @param wConfirmReceive [in]: accept/reject status, for accept set 1, for reject set 0
  74  @returns : returns SAP_RESULT_VAL with SAP_SUCCESS in case of success and appropriate failure error if any error as per the SAP_STATUS_CODE ENUM
  75  ****************************************************************************/
  76 SAP_RESULT_VAL receiveFile(int dwTransactionId, char* pFilePath, short int wConfirmReceive);
  77
  78 /**************************************************************************//**
  79  @brief  The function cancelFile is called by app to cancel the file transfer
  80  @param dwTransactionId [in]: transaction Id - Identifies the File transfer transaction to be cancelled
  81                 file sender App will receive this transaction Id as return value of sendFile()
  82                 file receiver App will receive this transaction Id in FDefOnSendFile()
  83   @returns : returns SAP_RESULT_VAL with SAP_SUCCESS in case of success and appropriate failure error if any error as per the SAP_STATUS_CODE ENUM
  84  ****************************************************************************/
  85 SAP_RESULT_VAL cancelFile(int dwTransactionId);
  86
  87 /**************************************************************************//**
  88  @brief This callback function gets triggered when App receive a file req
  89  @param dwTransactionId [in]: transaction Id for file transfer
  90  @param pFilePath [in] : This is source file path at sender side
  91                 Receiver will call receiveFile() to accept/reject the file transfer request
  92                 In receiveFile(), pFilePath is destination file path (Note: Since source file path could be from different File System,
  93                 call receiveFile with a path valid in destination File System. Application should take care of this)
  94  @param dwAgentId [in]:  Agent ID to which the call back is intended.
  95  @returns : returns void.
  96 * ***************************************************************************/
  97 typedef  void (*FDefOnSendFile) (int dwTransactionId, char* pFilePath, unsigned int dwAgentId);
  98
  99
 100 /**************************************************************************//**
 101  @brief This callback function gets triggered when sending file  is completed or error occurred during File transfer
 102  @param dwTransactionId [in]: transaction ID for file transfer
 103  @param pFilePath [in] : file path.
 104  @param uwResult [in] : FT_RESULT_VAL: TRANSFER_SUCCESS if transfer is successful or appropriate Error code
 105  @param dwAgentId [in]:  Agent ID to which the call back is intended.
 106  @returns : returns void
 107 * ***************************************************************************/
 108 typedef  void (*FDefOnSendComplete) (int dwTransactionId, char* pFilePath, unsigned short int uwResult, unsigned int dwAgentId);
 109
 110 /**************************************************************************//**
 111  @brief This callback function gets triggered when receive file is completed
 112  @param dwTransactionId [in]: transaction ID for file transfer
 113  @param pFilePath [in] : Received file path
 114  @param uwResult [in] : FT_RESULT_VAL: TRANSFER_SUCCESS if transfer is successful or appropriate Error code
 115  @param dwAgentId [in]:  Agent ID to which the call back is intended.
 116  @returns : returns void
 117 * ***************************************************************************/
 118 typedef  void (*FDefOnReceiveComplete) (int dwTransactionId, char* pFilePath, unsigned short int uwResult, unsigned int dwAgentId);
 119
 120
 121 /**************************************************************************//**
 122  @brief This callback function gets triggered to update file progress status to App
 123  @param dwTransactionId [in]: transaction ID for file transfer
 124  @param uwProgress [in] : send/receive file progress expressed as % (e.g. 10%, 90%)
 125  @param dwAgentId [in]:  Agent ID to which the call back is intended.
 126  @returns : returns void
 127 * ***************************************************************************/
 128 typedef  void (*FDefOnFileProgress) (int dwTransactionId, unsigned short int uwProgress, unsigned int dwAgentId);
 129
 130
 131 /***************************************************************************//**
 132  @brief  The structure  tagFTNotification holds references to callback for application for various events from framework for file transfer
 133  @param  pFDefOnSendFile: Callback to indicate incoming file transfer request
 134  @param  pFDefOnSendComplete: Callback to indicate status of send file  (both success and error)
 135  @param  pFDefOnReceiveComplete: Callback to indicate status of receive file  (both success and error)
 136  @param  pFDefOnFileProgress: Callback to indicate progress of file transfer
 137  ****************************************************************************/
 138 typedef struct tagFTNotification
 139 {
 140         FDefOnSendFile pFDefOnSendFile;///<Register on send file request function pointer
 141         FDefOnSendComplete pFDefOnSendComplete;///<Register on send complete function pointer
 142         FDefOnReceiveComplete pFDefOnReceiveComplete;///<Register on receive complete function pointer
 143         FDefOnFileProgress pFDefOnFileProgress;///<Register on file progress function pointer
 144 }FTNotification;
 145
 146 /**************************************************************************//**
 147 @brief This function registers all the callbacks in FTNotification. This API needs to be called from the App to get File Transfer notifications.
 148 @param FTNotiFuncs [in] : Notification functions which are to be registered for getting callback.
 149 @returns : returns void
 150 * ***************************************************************************/
 151 void registerFTNotifications(FTNotification FTNotiFuncs);
 152
 153 #ifdef __cplusplus
 154 }
 155 #endif
 156
 157 #endif /*_FTINTERFACE_H_ */
 158