Docs > API Reference

ICEspresso Chat Framework API Reference

The ICEspresso Chat Framework API provides the interface to interact with and to manipulate the ICEspresso Service which offers chat-related and web presence functionalities. The ICEspresso Chat Framework aims to free developers from having to deal with low-level socket programming as well as back-end server design thus, through simple API, developers may devote their time and creativity to UI design.

The ICEspresso Chat Framework is built on asynchronous paradigm for most of its parts. In contrary to the conventional synchronous programming, developers will find the API methods heavily rely on callback functions. Those who have worked with Ajax or possess similar experiences in asynchronous programming will adapt to ICEspresso Chat Framework in a quicker pace.

For most of the API methods, developer will call a method (sends command to ICEspresso Service) and set-up a mapping handler to be notified of the results from ICEspresso Service. Depending on the nature of the command, different callback handler will be invoked with appropriate event id to let application identify the type of event.

This API reference mainly focuses on individual method and tries to explain what each method does. Developers looking for big picture or crash course on ICEspresso package should read the Tutorial page.

Table of Contents

ICEspresso Namespace

The icespresso package resides under icespresso namespace. Within the namespace, the icespresso class is defined, but by design it is not directly accessible. The namespace instead exports an entry function icespresso.initialize() to, as the name suggests, prepare the framework components. Developers having background in other modern programming languages will easily find the icespresso.initialize() approach by nature a static type initializer.

Under the icespresso namespace, four classes are defined, being Icespresso, Room, Chatter, and Message respectively. These four classes are the building blocks of the ICEspresso Chat Framework. Developers do not have to create concrete objects from these classes. Depending on the situation, objects of these classes will be created by the framework and passed to application either through explicit method call or event callback handlers.

icespresso.initialize()

This is the entry function that instantiates and returns an Icespresso object. This function needs to be called to initialize the required framework components properly before other operations can kick in. icespresso.initialize() only instructs the framework to set-up its state. The actual initialization process is asynchronous. Under the hood, a Flash object has to be embedded in the web page and its own initialization handler be invoked before the framework is considered initialized. As such, when icespresso.initialize() returns, the internal resources *may not* have completed the initialization process. The framework will signal the ready state via callback handlers.

parameter:

returns:

example:

<script language="javascript">
// The ICEspresso object created through initialization process.
// When the function returns, chat object's state may still be undefined.
// Developers have to be notified of the ready state via event signal.
var chat = icespresso.initialize();

// The following code *can* lead to run-time error because chat object
// is defined but may not have been fully initialized yet
// chat.iAm("foo");
</script>

icespresso.log(logMsg)

This method opens up a floating log pane and displays the messages written to it.

parameter:

returns:

(Figure 1. ICEspresso log pane)

ICEspresso Class

The entry function icespresso.initialize() returns an object with which developers use to manipulate the framework. It has been stressed enough that the initialization process is asynchronous. Some of the following methods are not applicable before initialized signal has been alerted.

Methods which communicate with ICEspresso Service are all asynchronous and thus require connectivity to ICEspresso Service. Absence of connectivity results in immediate "not connected" error throw when asynchronous methods called. Also, these methods will have a corresponding callback handler counterpart.

connect(prop, [uniqueKey], [ip])

Connect to iPush Server.

connect() must be called before other ICEspresso Service related operations can proceed. The parameter prop is a iPush Server specific property that may require further reading which is outside the scope of this API reference. Please refer to [...] for more information. connect() call is asynchronous, meaning that successful or failed connection is notified later in icespresso.onSystemEvent() callback.

The current design only supports one connection per web page. Calling connect() when already connected will result in exception thrown.

parameter:

returns:

throws error when:

mapped callback event:

<script language="javascript">
var prop = {
    host: "www.push4free.com",
    port: 443,
    group: "icespresso",
    product: "chat",
    user: "foo",
    password: "bar1"
};
var uniqueKey = "baz";
chat.connect(prop, uniqueKey);
</script>

disconnect()

disconnect() unregisters from ICEspresso Service and disconnects from iPush Server. disconnect() will also reset Framework's internal state variables.

disconnect() is an asynchronous call because of the ICEspresso Service unregistration part. Completion of disconnection is notified in icespresso.onSystemEvent() callback.

parameter:

returns:

throws error when:

mapped callback event:

<script language="javascript">
chat.disconnect();

icespresso.onSystemEvent(chat, eventId, arg) {
    switch (eventId) {
        case chat.SYS_DISCONNECTED:
        // Perform other application-specific clean-up code here
        break;
    }
}
</script>

isReady()

Query the framework to check for initialization status. Normally, developers do not have to actively check for the initialization status as the framework will send event signal when it has finished initialization. This method exists as a convenient utility function that may come handy when debugging.

parameter:

returns:

isConnected()

Query the framework to see if it has connected to remote iPush Server. As with isReady(), this is a convenient utility that developers can resort to when developing or debugging.

parameter:

returns:

setDebug(mode)

Turn on or turn off the debug mode. When debug mode is on, ICEspresso Chat Framework will output descriptive messages of what is happening to log pane when system level event occurs.

parameter:

returns:

joinRoom(roomName)

Join the room specified by the roomName parameter.

parameter:

returns:

throws error when:

mapped callback event:

<script language="javascript">
// join the room named Olympic
chat.joinRoom("Olympic");
</script>

quitRoom(roomName)

Quit the room currently joined.

parameter:

returns:

throws error when:

mapped callback event:

<script language="javascript">
// quit the room named Olympic
chat.quitRoom("Olympic");
</script>

send2Room(msg, roomName)

Send message to the room specified by roomName.

parameter:

returns:

throws error when:

mapped callback event:

<script language="javascript">
// Send message to the room named Olympic
chat.send2Room("How is everything going?", "Olympic");
</script>

kick(roomName, who)

Remove a chatter from the specified room. If a chatter is associated with multiple sessions in the same room. Those sessions will be removed from the room as well.

parameter:

returns:

throws error when:

mapped callback event:

<script language="javascript">
// Remove the chatter with id 3 from room Olympic.
chat.kick("Olympic", 3);
</script>

getRoom(roomName)

Retrieve the Room object named by roomName. The Room object is a local resource rather than remote resource. That is, getRoom() retrieves the Room object that the application has joined and is still in session.

parameter:

returns:

<script language="javascript">
// retrieve the room named "Olympic"
var room = chat.getRoom("Olympic");
if (room != null) {
  // do something with the room
}
</script>

getMyRoomCount()

Retrieve the number of rooms the applicatoin has joined and is currently in active session.

parameter:

returns:

roomExists(roomName)

Query ICEspresso Service the existence of a room referenced by roomName. Unlike getRoom(), roomExists() queries ICEspresso Service for the availability of the room. The query result is returned via icespresso.onSystemEvent() event handler.

parameter:

returns:

throws error when:

mapped callback event:

getTotalUserCount()

Query ICEspresso Service the number of connected user at system level.

parameter:

returns:

throws error when:

mapped callback event:

getRoomChatterCount(rooms)

Query ICEspresso Service the number of chatters in the rooms specified by the rooms parameter.

parameter:

returns:

throws error when:

mapped callback event:

iAm(handle)

Set the chatter's screen handle to handle.

parameter:

returns:

throws error when:

<script language="javascript">
// Set the chatter's handle to Oliver
chat.setHandle("Oliver");
</script>

getMe()

Obtain a Chatter object that essentially points to the current application user from ICEspresso Chat Framework. Technically speaking, the Chatter object is the one who creates the connection for the application page.

parameter:

returns:

<script language="javascript">
// retrieve me object and test identity against it
var chatter= chat.getMe();
if (chatter.isMe())
    alert("This is me");
else
    alert("This is NOT me"); // won't happen
</script>

setFriends(friends)

Set the elements in friends parameter to watch list so that when the watched entity has signed in, logged off, or joined a chat room, the ICEspresso Service will dispatch a notification message. The technical detail involved in friend-related functions is discussed in [...]. Developers are encouraged to read it to gain an insight into the working mechanism.

setFriends() overwrites the current watch list. That is, a setFriends() call replaces the previous watched list (if any).

parameter:

returns:

throws error when:

<script language="javascript">
var prop = {
    // code omitted for brevity
};
chat.connect(prop, "baz");
// After SYS_CONNECTED event has been signaled.
var friends = new Array();
friends.push("user1");
friends.push("user2");
friends.push("user3");
// watch for chatters whose uniqueKey is set to user1, user2, or user3 respectively.
chat.setFriends(friends);
// chat.setFriends(["user1", "user2", "user3"]);  This will achieve the same result.
</script>

addFriends(friends)

Add the elements in friends parameter to watch list so that when the watched entity has signed in, logged off, or joined a chat room, the ICEspresso Service will dispatch a notification message. The technical detail involved in friend-related functions is discussed in [...]. Developers are encouraged to read it to gain an insight into the working mechanism.

addFriends() appends the elements in friends parameter to the watch list.

parameter:

returns:

throws error when:

<script language="javascript">
var prop = {
    // code omitted for brevity
};
chat.connect(prop, "baz");
// After SYS_CONNECTED event has been signaled.
var friends = new Array();
friends.push("user1");
friends.push("user2");
friends.push("user3");
// watch for chatters whose uniqueKey is set to user1, user2, or user3 respectively.
chat.addFriends(friends);
// chat.addFriends(["user1", "user2", "user3"]);  This will achieve the same result.
</script>

removeFriends(friends)

Remove elements in friends parameter from current watch list. The technical detail involved in friend-related functions is discussed in [...]. Developers are encouraged to read it to gain an insight into the working mechanism.

parameter:

returns:

throws error when:

<script language="javascript">
var prop = {
    // code omitted for brevity
};
chat.connect(prop, "baz");
// After SYS_CONNECTED event has been signaled.
var rmv = new Array();
rmv.push("user1");
rmv.push("user2");
rmv.push("user3");
// remove user1, user2, and user3 from current watch list.
chat.removeFriends(friends);
// chat.removeFriends(["user1", "user2", "user3"]);  This will achieve the same result.
</script>

getFriends(getOffline)

Query the ICEspresso Service to retrieve the status of those who are in my watch list. The default behavior is to list online entities only. The result is returned to application via icespresso.onFriendEvent() handler.

parameter:

returns:

throws error when:

mapped callback event:

<script language="javascript">
var prop = {
    // code omitted for brevity
};
chat.connect(prop, "baz");
// After SYS_CONNECTED event has been signaled.
chat.setFriends(["user1", "user2", "user3"]);
chat.getFriends();
</script>

sendPM(chatterId, msg)

Send a private message to the designated recipient. If the message recipient owns several concurrent sessions, each session will receive a copy of the message.

parameter:

returns:

throws error when:

mapped callback event:

<script language="javascript">
icespresso.onFriendEvent(chat, eventId, arg) {
    switch (eventId) {
        case chat.FRIEND_PMSENT: {
            var to = arg.to; // recipient's connection id (3 in this sample)
            var handle = arg.handle; // recipient's current handle
            var msg = arg.msg; // In this sample, msg translates to "Hi, how are you?"
            break;
        }

        case chat.FRIEND_PMFAILED: {
            var to = arg.to; // recipient's connection id (3 in this sample)
            var msg = arg.msg; // In this sample, msg translates to "Hi, how are you?"
        }
    }
}

chat.sendPM(3, "Hi, how are you?");
</script>

Room Class

The Room class is used to maintain the state of the chatters who participate in the room activity. Under the hood, room objects contain raw data which are linked and kept synchronized with ICEspresso Service. As a result, developers do not create room objects. Instead, the ICEspresso Chat Framework will create and maintain a list of room objects and pass them to application when necessary.

If application needs to inspect a room object, the ICEspresso class provides getRoom(roomName) method for such purpose.

getName()

Get the name of the room.

parameter:

returns:

getMessages()

Get the historic messages before room is created. Technically speaking, room object creation from Framework's perspective happens when application joins a room. Upon room creation, ICEspresso Service will pass messages (20 by default) that were exchanged in the room to the ICESpresso Chat Framework which will in turn assign these messages to the newly created room object. This approach gives application a way to examine the historic messages prior to joining. Hence, what getMessages() returns is a snapshot of those historic messages right before application joins a room.

parameter:

returns:

<script language="javascript">
function output(str) {
    var d = document.createElement("DIV");
    d.innerHTML = msg;
    document.body.appendChild(d);
}

// suppose room object is passed to application from framework
var messages = room.getMessages();
for (var i=0; i<messages.length; ++i) {
    // display messages in ascending order (older message is displayed near top)
    output(messages[i].getMessage());
}
</script>

getChatterCount()

Returns the number of chatters in the room.

parameter:

returns:

Chatter Class

The Chatter class represents users who have connected to ICEspresso Service.

getId()

Return the id associated with this chatter. Id is assigned by ICEspresso Service to guarantee the uniqueness within the system.

parameter:

returns:

getHandle()

Get the screen handle the chatter goes by. Screen handle is synonymous to nickname.

parameter:

returns:

getLastHandle()

The screen handle that is previously used by this chatter.

parameter:

returns:

isMe()

Indicates whether or not this chatter is me.

parameter:

returns:

Message Class

The Message class packs room message exchanged among various sources. Its fundamental properties include message originator, publishing date, message type, and actual message content. There are three pre-defined message types but developer can easily add custom types through prototype inheritance.

getMessage()

Get the raw message content contained in this message.

parameter:

returns:

getBy()

Get the message publisher's handle.

parameter:

returns:

getWhen()

The message's publishing date.

parameter:

returns:

getType()

The type of message which can be thought as an indicator to the nature of the message.

parameter:

returns:

ROOM_MSG

Reflects that the message results from chat input.

JOIN_MSG

Reflects that the message results from chatter join.

QUIT_MSG

Reflects that the message results from chatter quit.

Callback function

These callback functions serve as event sinks. The opening section in this reference states that the ICESpresso Chat Framework is built on asynchronous programming model. This technique allows events occur independently of the main program flow. In an interactive environment where events may take place from different sources at random timeframe, asynchronous programming model may prove to be more versatile as it handles events only when necessary rather than waiting indefinitely for non-anticipatable events to occur.

Having said that, it is also noted that asynchronous programming usually breaks the processing flow into two phases where in phase one a command is sent and in phase two the concerning party responds with the command processing result. This inevitably adds complexity to the program structuring but this is the trade-off for versatility.

The ICESpresso Chat Framework defines three callback functions to handle chat-related and web-presence events. icespresso.onSystemEvent is responsible for responding to action that is a result of system-level request. icespresso.onChatEvent processes events related to chat room activities. icespresso.onFriendEvent deals with friends' presence and their whereabouts.

The three callback handlers bear the same calling interface. What they differ lie within the event type and the argument that maps to the type of event.

function icespresso.onSystemEvent(chat, eventId, arg)

This callback handler is called when system-level events occur.

parameter:

event  SYS_INITIALIZED

This event is a result of icespresso.initialize() call. It is triggered once and only once regardless of number of calls to icespresso.initialize(). This event indicates that ICESpresso Chat Framework has set-up the necessary components. Application can call connect() method after this event has been signaled.

arg contains:

event  SYS_CONNECTED

This event is a result of connect() call. This event is basically informational as it will be immediately followed by SYS_HANDSHAKED event.

arg contains:

event  SYS_DISCONNECTED

This event is a result of disconnect() call.

arg contains:

event  SYS_HANDSHAKED

This event is automatically generated when ICESpresso Chat Framework has registered itself with ICEspresso Service immediately after a successful connection. Upon connection, ICESpresso Chat Framework immediately tries to exchange information with ICEspresso Service. The ICEspresso Service will at this time assign a session-level unique connection id to the Framework.

When this event has been signaled, the Framework can be seen as in-sync with the ICEspresso Service, permitting other server-related operations to take place.

arg contains:

event  SYS_ROOMEXISTS

This event is a result of roomExists() call.

arg contains:

event  SYS_TOTALUSER

This event is a result of getTotalUserCount() call. arg contains the query result.

arg contains:

event  SYS_ROOMCHATTER

This event is a result of getRoomChatterCount() call. arg contains the query result.

arg contains:

<script language="javascript">
// suppose room Olympic and Sport are hosted,
// having 10 and 20 chatters respectively.
// Room Tennis is non-existent.

icespresso.onSystemEvent(chat, eventId, arg) {
    case chat.SYS_ROOMCHATTER:
        var rooms = arg.rooms;
        /**
         * rooms looks like:
         * rooms["Olympic"] = 10;
         * rooms["Sport"] = 20;
         * rooms["Tennis"] = null;
         */
        break;
}

chat.getRoomChatterCount(["Olympic", "Sport", "Tennis"]);
</script>

function icespresso.onChatEvent(chat, eventId, arg)

This callback handler is called when chat events occur.

parameter:

event  CHAT_ROOMJOIN

This event is fired when someone else joins the room. Application can take this opportunity to deliver announcement such as displaying join message or adding the new comer's information to the room user list.

arg contains:

event  CHAT_ROOMREADY

This event is triggered exclusively when application successfully joins a room through joinRoom() call. It will be fired once and only once per each room joined. In this event, the ICEspresso Service will send a snapshot of current list of chatters and messages. Application can make use of these raw data to construct visual information for the application user.

arg contains:

event  CHAT_ROOMMSG

This event is fired whenever a chat-input message is exchanged in the room. The arg parameter contains three objects that allow application to identify who said what in which room.

arg contains:

event  CHAT_HANDLEUPDATE

This event is fired when someone's handle is changed. The "someone" needs to be in the same room that the application is participating in for this event to occur. When this event occurs, application will be passed a Chatter object with which getHandle() returns the new handle and getLastHandle() returns the old handle.

arg contains:

event  CHAT_ROOMQUIT

This event is fired when someone quits the room. The arg parameter contains three objects that allow application to identify who left which room.

arg contains:

event  CHAT_ROOMKICK

This event is fired when room moderator calls kick() method to remove specified chatter from a room.

arg contains:

function icespresso.onFriendEvent(handle, roomName)

This callback handler is called when friends-related events take place.

parameter:

event  FRIEND_ONLINE

This event is fired whenever someone in application's watch list has just registered with ICEspresso Service. In other words, someone in the watch list has signed in.

The watch list is set by using friend-related methods.

arg contains:

event  FRIEND_JOINROOM

This event is fired whenever someone in application's watch list has just joined a chat room.

arg contains:

event  FRIEND_QUITROOM

This event is fired whenever someone in application's watch list has just left a chat room.

arg contains:

event  FRIEND_OFFLINE

This event is fired whenever someone in application's watch list has just unregistered from the ICEspresso System. In other words, someone in the watch list has signed off.

arg contains:

event  FRIEND_LOCATION

This event is fired when application queries friend status. The arg parameter contains the queried result.

arg contains:

<script language="javascript">
/**
 * Suppose we are watching foo, bar, and baz
 * - foo is currently in room A and room B
 * - bar is online but not in any room
 * - baz is offline
 */

// set foo, bar and baz to my watch list
chat.setFriends( ["foo", "bar", "baz"] );

// implement the onFriendEvent handler
icespresso.onFriendEvent = function(chat, eventId, arg) {
    switch (eventId) {
        case chat.FRIEND_LOCATION: {
            var result = arg.friends;
            /** 
             * result would look like this:
             * result["baz"]["connId"] == -1; // baz is offline
             * result["baz"]["rooms"] = null; // baz is offline
             *
             * result["bar"]["connId"] == 1; // bar is online
             * result["bar"]["rooms"] == []; // bar is online but not in any rooms
             *
             * result["foo"]["connId"] == 2; // foo is online
             * result["foo"]["rooms"][0] == "A"; // foo is in room A
             * result["foo"]["rooms"][1] == "B"; // foo is also in room B
             */
            break;
        }
    }
}

// query ICEspresso Service
chat.getFriends();
</script>

event  FRIEND_PRIVATEMSG

This event is fired when a private message is sent to the application user. If application holds several concurrent sessions, each session will receive this message.

arg contains:

<script language="javascript">
icespresso.onFriendEvent(chat, eventId, arg) {
    switch (eventId) {
        case chat.FRIEND_PRIVATEMSG: {
            var msg = arg.msg;
            var from = arg.from;
            var handle = arg.handle; // equivalent to msg.getBy()

            _DEBUG(handle + " sent you a private message: " + msg.getMessage());
            break;
        }
    }
}
</script>

event  FRIEND_PMSENT

This event is fired when private message is sent to the destined recipient.

arg contains:

Please refer to sendPM() for sample code.

event  FRIEND_PMFAILED

This event is fired when ICEspresso Service could not locate the message recipient specified by the id parameter in sendPM().

arg contains:

Please refer to sendPM() for sample code.