mesibo Client-side APIs

Now that we have quickly explored how to write basic applications using mesibo API, let’s quickly look at key client side APIs in various categories.

All the APIs have exactly the same name and parameters across the platform, they only differ in the way they have been called in Java (Android), Objective-C (iOS) and Swit (iOS). For example,

On Android

mesibo.setPath(path)

On IOS,

						Objective-C
						[mesiboInstance setPath:path];
						
						Swift
						mesibo.getInstance().setPath(path)

Initialization

You need to call one or more initialization API before using any other mesibo APIs.

Method Description Parameters
init [Android Only] This is the first API function you must call
before you use any other mesibo API.
Application Context
setAccessToken Set access token for the user. Access Token
setPath(Optional) Path where all the databases and files will be stored.
Default Path will be used if this API is not called.
Path
setDatabase(Optional) Enable local database to store messages, and other information.
If setDatabase is called before setAccessToken(), same database will be used for all the users. It is recommended to call it after setAccessToken() API.
Name or complete path of the database.
If path is not specified, the database will be stored in the default path or the path set by setPath API.
addListener Add a listener listener
removeListener(Optional) Remove a listener listener
Reset(Optional) Reset mesibo object Void
setSecureConnection Enable encrypted connection. Enable
start Start mesibo connection establishment. mesibo will not establish network connection till the start() is called. However, once the start() is called, mesibo will automatically manage any future reconnections till stop() is called. Void
stop Disconnect any existing connection and also prevent future reconnections. Void

Messaging

Sending messages using mesibo API only requires initializing MesssageParams object and invoke one of the messaging API with it, message id and message itself.

Message ID is 32-bit unique id. It will be converted into a 64-bit globally unique id by the system. The id which you have originally passed will be preserved in the lower 32-bit of the globally unique id. For example, if you send a message with id 0x12345678, it will be converted into global id 0xXXXXXXXX12345678 while sending message to the receiver.

API Function Description Parameters
sendMessage Send a message.
There are overloaded functions to send message in
different formats, for example, string, byte array etc.
1. Params
2. Message ID
3. Message
sendFile Send a message with file & location 1. MessageParams
2. Message ID
3. FileInfo
sendLocation Send a location 1. MessageParams
2. Message ID
3. Location
forwardMessage Forward a message. 1. MessageParams
2. Message ID
3. ID of message to be forwared
resend Resend a failed message 1. MessageParams
2. Message ID of failed message
cancel Cancel a message
Message can not be canceled if already sent & delivered
1. MessageParams
2. Message ID
newMessageID Returns a new unique message ID void

Message Management

These set of APIs deal with managing stored messages in the database and sending read receipts.

To read stored messages from the database, you need to tell mesibo about a set of messages you need to read; for example, all messages, OR messages from a sender, OR for a particular group, OR messages matching a search query etc. This can be achieved by setting a read session. Once you set a read session, you can start reading messages by calling read() api.

You can enable automatic sending of read receipts every time you read a message. This you can be achieved by setting a read session with READ_RECEIPT flag. On reading or receiving a message, read receipts will be be automatically send if

  1. Sending Read Receipt is enabled while setting reading session, AND
  2. Read receipt requested by the sender, AND
  3. A new real-time or database message matches the read session.

Any messages read will have the status READ instead of NEW.

API Function Description Parameters
setReadingSession Set a reading session
  • MessageParams
  • Flag
endReadingSession End reading session.
Automatic read receipt will not be send.
void
read Read messages. All subsequent read() will read next messages. Number of messages to be read
deleteMessage Delete a message Message ID
deleteMessages Delete messages matching criteria MessageParams
sendReadReceipt Manually send a read receipt 1. MessageParams
2. Message ID
isReading Check if a reading session is set MessageParams

File Transfer

Sending files is no different than sending plain messages. All you need 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.

mesibo provides you set of APIs to abstract out the entire process and also let you choose how and where to store your files; for example, Amazon Cloud, Google Cloud, Microsoft Azure, Akamai or your own servers.

To start a file transfer (download or upload), you must initialize a FileInfo object and pass it to sendFile() or startFileTransfer() 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 avoid sending duplicate files.

file-transfer-floe-sample

API Function Description Parameters
getFileInstance Create a new FileInfo instance for file transfer 1. Type
2. Download URL
3. FilePath
startFileTransfer Start a File Transfer FileInfo object
stopFileTransfer Stop a File Transfer FileInfo object
updateFileTransferProgress Update the progress of current file Transfer.
This API should be called by the FileTransferHandler to update
the progress of the file transfer or any error. In turn, it invokes
FileTransferProgressListener so that application can update
the state, UI etc.
FileInfo object
isFileTransferEnabled Returns true if FileTransferHandler is implemented by the application void

User Profile Management [Optional]

You can create and associate a social profile for every known peers or groups. mesibo will set profile fields in MessageParams every time you receive a message from those peers.

API Function Description Parameters
setProfile Set a user or group profile UserProfile Object
getProfile Get a user or group profile Peer Address
Group id (for group profile)
createUserProfile Create a user profile Peer Address
Group id (for group profile)
deleteUserProfile Delete a user profile Peer Address
Group id (for group profile)
setSelfProfile Set self profile UserProfile Object
getSelfProfile returns self profile void
getUserProfilePicturePath Get absolute path of user profile picture UserProfile Object
startUserProfilePictureTransfer Start user profile picture transfer, handled by FileTransferHandler UserProfile Object
deleteUserProfilePicture Delete user profile picture UserProfile Object
getProfiles Get all the profiles void
getSortedUserProfiles Get sorted profiles void
getRecentProfiles Get recent profiles void

Networking, Timings and other Utility APIs

API Function Description Parameters
getNetworkConnectivity Returns current network connectivity. It can be one of the following.
  • CONNECTIVITY_UNKNOWN
  • CONNECTIVITY_DISCONNECTED
  • CONNECTIVITY_WIFI
  • CONNECTIVITY_2G
  • CONNECTIVITY_3G
  • CONNECTIVITY_4G
void
getTimestamp Get current timestamp (in ms) void
getUpTime Get UP time void
getConnectedTime Get last connected timestamp void
random Returns 32-bit pseudo-random number void
isUiThread Check if current thread is an UI thread. void
loadImage Load image from the file path File Path
getThumbnailBitmap Get thumbnail from an image Bitmap object

Filesystem APIs

API Function Description Parameters
createFile Create a file Filename and path
fileExists Check if a file exists Filename and path
renameFile Rename a file
  • Old path
  • New Path
copyFile Copy a file
  • src path
  • dest Path
deleteFile Delete a file Filename and path

Data Structures

MessageParams

Android: mesibo.MessageParams
iOS: mesiboParams

mid Message id
This should be used for incoming messages only. For outgoing messages, mid should be specified in send_xxx() functions.
groupid Group ID, 0 for one-to-one messages
peer
  • Recipient user address for outgoing messages
  • Sender user address for incoming messages
expiry Message Expiry for outgoing message (time to live).
type Message Type
ts Timestamp when the message was received - in milli seconds
flag Message Flag - can be the combination of one or more flag

  • FLAG_DELIVERYRECEIPT- delivery receipt is required (default, set)
  • FLAG_READRECEIPT - read receipt is required (default, set)
  • FLAG_TRANSIENT - transient message which should not be stored in the database.
  • FLAG_QUEUE - enqueue this message for sending but don’t really send unless send() is called or the queue is full.
  • FLAG_NONBLOCKING - don’t block while queueing message for sending.
  • FLAG_EOM (incoming only) - no more messages, can be used to update UI.
  • FLAG_FILETRANSFERRED (incoming only) - File was transferred and saved
  • FLAG_FILEFAILED (incoming only) - File transfer was failed.
origin Origin of the message. Can be one of the following

  • ORIGIN_REALTIME - realtime message
  • ORIGIN_DBMESSAGE - message from the database.
  • ORIGIN_DBSUMMARY - summary message from the database
  • ORIGIN_FILTER - message for filtering (moderation)
status Message Status - Can be one of the following

  • MSGSTATUS_OUTBOX - Message is pending to send
  • MSGSTATUS_SENT - Message sent to server
  • MSGSTATUS_DELIVERED - Message delivered to recipient
  • MSGSTATUS_READ - Message was read by the recipient
  • MSGSTATUS_RECEIVEDNEW - Message Received and not read earlier
  • MSGSTATUS_RECEIVEDREAD - Message Received and read earlier
  • MSGSTATUS_FAIL - Message Failed
  • MSGSTATUS_USEROFFLINE - Recipient is not active
  • MSGSTATUS_INBOXFULL - Inbox Full
  • MSGSTATUS_INVALIDDEST - Invalid Destination
  • MSGSTATUS_EXPIRED - Expiry reached before message could be sent

FileInfo

mode File Transfer Mode can be one of the following

  • MODE_DOWNLOAD
  • MODE_UPLOAD
progress File Transfer Progress (in percent)
url File URL - it can be an absolute URL or anything which your file transfer handler can interpret.
filePath File Path
type File Type. Can be one of the followings

  • TYPE_AUTO
  • TYPE_IMAGE
  • TYPE_VIDEO
  • TYPE_AUDIO
  • TYPE_OTHER
size File Size, in bytes

UserProfile

address Address of Peer, null for group
groupid Group ID, 0 for user.
name User or Group Name
status Social Status
picturePath Profile Picture path
draft Draft message
unread Count of unread messages
other User object
flag Flags. Can be one of the followings

  • FLAG_ARCHIVE
  • FLAG_MUTE
  • FLAG_SELFPROFILE
  • FLAG_HIDDEN
  • FLAG_TEMPORARY
  • FLAG_DELETED = 0x80;

mesibo Listeners

Message Listener

Android: mesibo.MessageListener interface
iOS: mesiboListener delegate

mesibo_onMessage Invoked on receiving a new message or reading database messages
  • MessageParams
  • Data
mesibo_onFile Invoked on receiving a new file message or reading database messages
  • MessageParams
  • FileInfo
mesibo_onLocation Invoked on receiving a new location message or reading database messages
  • MessageParams
  • Location
mesibo_onActivity Invoked on receiving a new activity
  • MessageParams
  • Activity
mesibo_onMessageStatus Invoked when the status of outgoing or sent message is changed MessageParams

Connection Listener

Android: mesibo.ConnectionListener interface
iOS: mesiboListener delegate

mesibo_onConnectionStatus Invoked when the connection status is changed.
It is also invoked when the token is about to be expired.
status

File Transfer Handler

Android: mesibo.FileTransferHandler interface
iOS: mesiboListener delegate

mesibo_onStartFileTransfer Invoked to start a file transfer. FileInfo Object
mesibo_onStopFileTransfer Invoked to start a file transfer. FileInfo Object

File Transfer Progress Listener

Android: mesibo.FileTransferProgressListner interface
iOS: mesiboListener delegate

mesibo_onFilerTransferProgress Invoked when file transfer status is updated. FileInfo Object

Message Filter Listener

Android: mesibo.MessageFilter interface
iOS: mesiboListener delegate

mesibo_onMessageFilter Invoked when a new real-time message is received.
Return false to filter out the message.
  • MessageParams
  • Data