FileDocCategorySizeDatePackage
ImConnection.javaAPI DocAndroid 1.5 API8558Wed May 06 22:42:46 BST 2009com.android.im.engine

ImConnection

public abstract class ImConnection extends Object
An ImConnection is an abstract representation of a connection to the IM server.

Fields Summary
public static final int
DISCONNECTED
Connection state that indicates the connection is not connected yet.
public static final int
LOGGING_IN
Connection state that indicates the user is logging into the server.
public static final int
LOGGED_IN
Connection state that indicates the user has logged into the server.
public static final int
LOGGING_OUT
Connection state that indicates the user is logging out the server.
public static final int
SUSPENDING
Connection state that indicate the connection is suspending.
public static final int
SUSPENDED
Connection state that indicate the connection has been suspended.
public static final int
CAPABILITY_GROUP_CHAT
The capability of supporting group chat.
public static final int
CAPABILITY_SESSION_REESTABLISHMENT
The capability of supporting session re-establishment.
protected int
mState
The current state of the connection.
protected CopyOnWriteArrayList
mConnectionListeners
protected Presence
mUserPresence
Constructors Summary
protected ImConnection()


      
        mConnectionListeners = new CopyOnWriteArrayList<ConnectionListener>();
        mState = DISCONNECTED;
Methods Summary
public voidaddConnectionListener(ConnectionListener listener)

        if (listener != null) {
            mConnectionListeners.add(listener);
        }
protected abstract voiddoUpdateUserPresenceAsync(Presence presence)

public abstract intgetCapability()
Gets bit-or of capabilities supported by the underlying protocol. Valid
capability bits are: {@value #CAPABILITY_GROUP_CHAT},
{@value #CAPABILITY_SESSION_REESTABLISHMENT}
return
bit-or of capabilities supported by the underlying protocol
public abstract ChatGroupManagergetChatGroupManager()
Gets the instance of ChatGroupManager for the connection.
return
the instance of ChatGroupManager for the connection.
throws
UnsupportedOperationException
if group chat is not supported by the underlying protocol.
public abstract ChatSessionManagergetChatSessionManager()
Gets the instance of ChatSessionManager for the connection.
return
the instance of ChatSessionManager for the connection.
public abstract ContactListManagergetContactListManager()
Gets the instance of ContactListManager for the connection.
return
the instance of ContactListManager for the connection.
public abstract ContactgetLoginUser()
public java.lang.StringgetLoginUserName()
        Contact loginUser = getLoginUser();
        return loginUser == null ? null : loginUser.getName();
    
public abstract java.util.HashMapgetSessionContext()
Gets the cookie of the current session. The client could store the
context and use it to re-establish the session by
{@link #reestablishSessionAsync(HashMap)}}. The stored context MUST be
removed upon the connection logout/disconnect.
return
the context of the current session or null if the
user has not logged in yet.
throws
UnsupportedOperationException
if session re-establishment is not supported by the
underlying protocol.
public intgetState()
Tells the current state of the connection.
        return mState;
    
public abstract int[]getSupportedPresenceStatus()
public PresencegetUserPresence()
        if (mState == SUSPENDING || mState == SUSPENDED) {
            return new Presence();
        }

        if (mState != LOGGED_IN) {
            // In most cases we have a valid mUserPresence instance also
            // in the LOGGING_OUT state. However there is one exception:
            // if logout() is called before login finishes, the state may
            // jump from LOGGING_IN directly to LOGGING_OUT, skipping the
            // LOGGED_IN state. In this case we won't have a valid Presence
            // in the LOGGING_OUT state.
            return null;
        }

        return new Presence(mUserPresence);
    
public abstract voidloginAsync(LoginInfo loginInfo)
Log in to the IM server.
param
loginInfo the login information.
public abstract voidlogoutAsync()
Log out from the IM server.
public voidnetworkTypeChanged()
Tells the engine that the network type has changed, e.g. switch from gprs
to wifi. The engine should drop all the network connections created before
because they are not available anymore.

The engine might also need to redo authentication on the new network depending
on the underlying protocol.
    
protected voidnotifyUpdateUserPresenceError(ImErrorInfo error)
        for (ConnectionListener listener : mConnectionListeners) {
            listener.onUpdatePresenceError(error);
        }
    
protected voidnotifyUserPresenceUpdated()
        for (ConnectionListener listener : mConnectionListeners) {
            listener.onUserPresenceUpdated();
        }
    
public abstract voidreestablishSessionAsync(java.util.HashMap sessionContext)
Re-establish previous session using the session context persisted by the
client. Only sessions that were dropped unexpectedly(e.g. power loss, crash,
etc) can be re-established using the stored session context. If the
session was terminated normally by either user logging out or server
initiated disconnection, it can't be re-established again therefore the
stored context should be removed by the client.


The client can query if session re-establishment is supported through
{@link #getCapability()}.
param
sessionContext
the session context which was fetched from previous session by
{@link #getSessionContext()} and persisted by the client.
throws
UnsupportedOperationException
if session re-establishment is not supported by the
underlying protocol.
public voidremoveConnectionListener(ConnectionListener listener)
        mConnectionListeners.remove(listener);
    
protected voidsetState(int state, ImErrorInfo error)
Sets the state of the connection.
param
state the new state of the connection.
param
error the error information which caused the state change or null.
        if(state < DISCONNECTED || state > SUSPENDED){
            throw new IllegalArgumentException("Invalid state: " + state);
        }
        if(mState != state){
            mState = state;
            for(ConnectionListener listener : mConnectionListeners){
                listener.onStateChanged(state, error);
            }
        }
    
public abstract voidsuspend()
Suspend connection with the IM server.
public voidupdateUserPresenceAsync(Presence newPresence)
        if (mState != LOGGED_IN) {
            throw new ImException(ImErrorInfo.NOT_LOGGED_IN, "NOT logged in");
        }

        doUpdateUserPresenceAsync(newPresence);