Get Started: File Transfer

Estimated reading time: 9 minutes

In this part, we will describe file transfer.

Prerequisites

You MUST go through the following prerequisites before you read further.

  • Read the First App Guide.
  • Read one of the Android, iOS, JS section of this tutorial.

How to send and receive files

Just like text messages, mesibo allows you to send and receive any arbitrary file (image, audio, video, doc, etc) in real-time. Sending and receiving files is no different from sending and receiving text messages. All an application has to do is to first upload the file to a server and then send the URL and thumbnail [optional] using mesibo in real-time. The receiver then downloads it using that URL. This out-of-band mechanism ensures that no real-time messages are blocked waiting for large files to be uploaded or downloaded.

mesibo offers you the flexibility to store all files on your servers including private servers or cloud services like Amazon Web Services, Google Cloud Storage, Microsoft Azure, etc.

You can use any data structure (for example, JSON) to send rich messages which contain text message, title, picture URL, etc. Mesibo provides a convenient utility function sendFile, which does most of the work and allows you to send various other information along with the file such as title, message, geolocation, etc. Receiver is notified of incoming file in listener function mesibo_onFile()

To start a file transfer (download or upload), you must initialize a FileInfo object and pass it to sendFile API. However, instead of creating this object manually, mesibo provides getFileInstance() API, which checks if an existing file transfer for this particular URL (download) or the file (upload) is in progress and if so, returns that object instead of creating a new object. This highly optimizes sending a file by avoiding duplicate file transfers.

However, Mesibo does not know or mandate how and where you store your files. Hence to use the sendFile function, you must assist mesibo in uploading and downloading files to your server. You can achieve that by implementing upload and download handler functions in FileTransferHandler, which is called by mesibo real-time API whenever it needs to upload or download files. For more information, refer to FileTransferHandler in the File Transfer API reference

Sending a file with Mesibo

Here is a brief set of steps you need to follow, for sending a file with mesibo on Android. We will go through each step, along with a code snippet that you can refer to as an example. You can refer to the Sample App code on GitHub for a complete understanding.

To send a file, create a file object using getFileInstance. To create the file instance pass the mode as upload and provide the path to your file. Then call sendFile(), to send the file to the recipient.

The sendFile function takes the following parameters:

  • params, MessageParams object initialized with required parameters
  • mid, Message-ID. For sending messages, Message-ID should be specified in the function parameters instead of using it from params.
  • file, FileInfo object initialized with file information like path, type, etc.

For Android,

Here is an example in Java

Mesibo.FileInfo file = Mesibo.getFileInstance(mParameter, mId, Mesibo.FileInfo.MODE_UPLOAD, filetype, Mesibo.FileInfo.SOURCE_MESSAGE, filePath, null, this);
file.message = caption;
file.image = bmp;
file.title = null;
file.userInteraction = true;
        
m.setFile(file);

int sendFileresult  = Mesibo.sendFile(mParameter, mId, file);

Here is an example in Kotlin,

val file = Mesibo.getFileInstance(mParameter, mId, Mesibo.FileInfo.MODE_UPLOAD, filetype, Mesibo.FileInfo.SOURCE_MESSAGE, filePath, null, this)

file.message = caption
file.image = bmp
file.title = null
file.userInteraction = true

m.file = file

val sendFileresult = Mesibo.sendFile(mParameter, mId, file)

For iOS,

Here is an example in Objective-C

MesiboFileInfo *mf = [MesiboInstance getFileInstance:mMesiboParam msgid:m.mid mode:MESIBO_FILEMODE_UPLOAD type:picker.fileType source:MESIBO_FILESOURCE_MESSAGE filePath:picker.mp4Path?picker.mp4Path:picker.filePath url:nil listener:self];

mf.mid= m.mid;
mf.message = picker.message;
//mf.filePath = c.mImagePath;
mf.image = picker.image;
mf.asset = picker.phasset;
mf.localIdentifier = picker.localIdentifier;
//[mf setPath:picker.filePath];
mf.userInteraction = YES;
        
MesiboInstance sendFile:mesiboParam msgid:(u_int32_t)c.mMessageID file:mf];

Here is an example in javascript. Here, you need to set the fileurl by uploading your file to your server and then getting the location of the file. Refer to the sample code here which does this in javascript.

var p = {};
p.peer = demo_destination;	
p.type = 0;
p.expiry = 3600*24;
p.flag = MESIBO_FLAG_DELIVERYRECEIPT|MESIBO_FLAG_READRECEIPT;
	
var msg = {}; //create a rich message
msg.filetype = 1; // 1 for image 2 for video, 3 audio, 10 other
msg.size = 1023;	
msg.fileurl = 'https://example.com/your_photo.jpg'
msg.title = 'My Picture';
msg.message = 'Hello from js';
	
api.sendFile(p, api.random(), msg);

Now, mesibo has got the path to your file. As explained earlier, you need to upload the file to a server, get the URL location where the file can be accessed on the server and send that URL in a message to the recipient. So that on the other end, your recipient can access that file URL, download it and view the file.

Since mesibo does not know where or how to upload it! For this, you need to help mesibo by implementing the FileTransferHandler

FileTransferHandler contains functions that will be called by mesibo when you start a file transfer or stop a file transfer.

  • The function Mesibo_onStartFileTransfer is called when mesibo wants your app to start a file transfer.
  • The function Mesibo_onStopFileTransfer is called when mesibo wants your app to stop a file transfer.

For Android, Here is an example in Java

@Override
public boolean Mesibo_onStartFileTransfer(Mesibo.FileInfo file) {
    if(Mesibo.FileInfo.MODE_DOWNLOAD == file.mode)
        return Mesibo_onStartDownload(file.getParams(), file);

    return Mesibo_onStartUpload(file.getParams(), file);
}

Here is an example in Kotlin

override fun Mesibo_onStartFileTransfer(file: Mesibo.FileInfo): Boolean {
    return if (Mesibo.FileInfo.MODE_DOWNLOAD == file.mode) Mesibo_onStartDownload(file.params, file) 
    else Mesibo_onStartUpload(file.params, file)
}

For iOS, Here is an example in Objective-C

-(BOOL) Mesibo_onStartFileTransfer:(MesiboFileInfo *)file {
    
    if(MESIBO_FILEMODE_DOWNLOAD == file.mode) {
        return [self Mesibo_onStartDownload:file];
    }
    
    return [self Mesibo_onStartUpload:file];    
}

Here is an example in Swift

public func mesibo_(onStartFileTransfer file: MesiboFileInfo?) -> Bool {
        
    if MESIBO_FILEMODE_DOWNLOAD == file?.mode {
        return mesibo_(onStartDownload: file)
    }
        
    return mesibo_(onStartUpload: file)
}        

In Mesibo_onStartUpload, you make an HTTP request to upload your file to the server.

Refer to Mesibo_onStartUpload function in messenger app sample code.

As the file is uploading, you can update mesibo with the status by calling updateFileTransferProgress. In turn, mesibo will invoke the listener onFileTransferProgress which can be used in your UI to show progress, for example, to display a spinner or a progress bar to show that the file is uploading.

Once your upload is complete, the URL parameter is set in the file object and your file is sent.

On the recipient end, when a file is received, the listener Mesibo_onFile is called with the FileInfo object. Mesibo also calls Mesibo_onStartFileTransfer from your file transfer handler to download the file from the URL.

The download handler reads the file data from the URL present in the FileInfo object received. In Mesibo_onStartDownload, you need to download the file from the server and read the contents.

Refer to Mesibo_onStartDownload function in messeger app sample code.

Similar to upload, the status of the file downloaded can be updated by calling updateFileTransferProgress.

In the sample upload and download handlers, the Mesibo HTTP Library is being used to handle HTTP requests. However, you can also use your methods to handle HTTP requests and responses instead of using the Mesibo HTTP Library.

If you have any questions, check out the File Handling FAQ

Push Notification >>

mesibo, android, ios