How to use Carrier File Transfer API

Brief Introduction

File Transfer is an extension of Carrier which provides functionality of transferring files between two Carrier friends. We provide two sets of APIs:

• Easy File APIs: this set of APIs is higher level. They are easier to use but users get no means to intervene in the file transfer process. They can be used to send one file to one friend.
• File Transfer APIs: These are a set of lower level APIs. They add complexities in programming while providing fine-grained controlling methods to intervene in the file transfer process. The core abstraction is the ElaFileTransfer object. It represents file transfer between two friends. It is half-duplex, which means it is associated with the role(sender/receiver). Five files are supported to be sent/received simultaneously. Users can pend/pause/cancel the process at any stage.

Programming model

• Prerequisites
  • The sender and the receiver are connected to Carrier network and are friends to each other and also see each other online.(refer to other document to see how to accomplish this)
• Easy File APIs
  • Sender
    • Call ela_filetransfer_init() to initialize the file transfer module.
    • Call ela_file_send(), specifying the file to send, the receiver of the file.
    • During the transfer, ElaFileProgressCallbacks::sent() will be invoked to inform the user of the progress.
    • ElaFileProgressCallbacks::state_changed() will be invoked whenever the state of the transfer changes.
    • When the file transfer module is no longer needed, de-initialized the file transfer module by calling ela_filetransfer_cleanup().
  • Receiver
    • Call ela_filetransfer_init() to initialize the file transfer module, specifying the ElaFileTransferConnectCallback invoked when file transfer request is received.
    • When the file transfer request from the sender is received, the ElaFileTransferConnectCallback registered will be invoked. If the request is to be accepted, call ela_file_recv() to start receiving the file, otherwise just ignore the request.
    • During the transfer, ElaFileProgressCallbacks::received() will be invoked to inform the user of the progress.
    • ElaFileProgressCallbacks::state_changed() will be invoked whenever the state of the transfer changes.
    • Call ela_filetransfer_cleanup().
• File Transfer APIs
  • Sender
    • Call ela_filetransfer_init() to initialize the file transfer module.
    • Call ela_filetransfer_new() to create a new ElaFileTransfer object, specifying the receiver and optionally adding a file to be transferred to the ElaFileTransfer object.
    • Call ela_filetransfer_connect() to start establishing a connection between the sender and the receiver.
    • ElaFileTransferCallbacks::state_changed() is invoked with reported state being FileTransferConnection_connected, indicating the connection is established.
    • Optionally call ela_filetransfer_add() to add a file to be transferred to the ElaFileTransfer object(a maximum of five files is supported to be transferred simultaneously).
    • ElaFileTransferCallbacks::pull() is invoked, specifying which file the receiver is requesting, what offset of the file the receiver wants the transfer to start with.
    • Repeatedly call ela_filetransfer_send() to send chunks of a file until the file is transferred. Users are responsible for the progress tracking. Data length is allowed to be zero.
    • Call ela_filetransfer_close() to destroy the ElaFileTransfer object when all files have been transferred.
    • Call ela_filetransfer_cleanup().
    • ElaFileTransferCallbacks::state_changed() will be invoked at any time, informing the state changes of the ElaFileTransfer object. Users should handle various situations accordingly.
    • During the process of file transfer, ElaFileTransferCallbacks::pending()/resume()/cancel() is invoked to inform user of the state change of the individual file transfer in the ElaFileTransfer object.
    • There is no cancelling individual file transfer API provided for the sender. Alternatively, users are allowed to send zero length data to the receiver, and the receiver can interpret the meaning by himself(e.g., cancelling the file transfer).
    • ela_filetransfer_close() can be called at any time.
  • Receiver
    • Call ela_filetransfer_init() to initialize the file transfer module, specifying the ElaFileTransferConnectCallback invoked when file transfer request is received.
    • When the file transfer request from the sender is received, ElaFileTransferConnectCallback registered will be invoked. Users should call ela_filetransfer_new() to create a new ElaFileTransfer object. If the request is to be accepted, call ela_filetransfer_accept_connect() to start establishing a connection between the sender and the receiver, otherwise call ela_filetransfer_close() to reject.
    • ElaFileTransferCallbacks::state_changed() is invoked with reported state being FileTransferConnection_connected, indicating the connection is established.
    • ElaFileTransferCallbacks::file() is invoked to inform user of the sender's request to transfer a file. If the request is to be accepted, call ela_filetransfer_pull() to tell the sender what offset of the file the user wants the file transfer start with, otherwise call ela_filetransfer_cancel().
    • ElaFileTransferCallbacks::data() will be continuously invoked to feed user with the file chunks. Users are responsible for the progress tracking, if more file chunks are expected, return true in the callback, return false otherwise. When the data length is zero, users interpret the meaning freely by their own(e.g., sender wants to cancel the file transfer).
    • Call ela_filetransfer_close() to destroy the ElaFileTransfer object when all files have been transferred.
    • Call ela_filetransfer_cleanup().
    • ela_filetransfer_pend()/ela_filetransfer_resume()/ela_filetransfer_cancel() can be called at any time to pend/resume/cancel an individual file transfer.
    • ela_filetransfer_close() can be called at any time.