| /* |
| * Copyright (C) 2007-2008 Esmertec AG. |
| * Copyright (C) 2007-2008 The Android Open Source Project |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package com.android.im.engine; |
| |
| import java.util.HashMap; |
| import java.util.concurrent.CopyOnWriteArrayList; |
| |
| /** |
| * An <code>ImConnection</code> is an abstract representation of a connection |
| * to the IM server. |
| */ |
| public abstract class ImConnection { |
| /** |
| * Connection state that indicates the connection is not connected yet. |
| */ |
| public static final int DISCONNECTED = 0; |
| |
| /** |
| * Connection state that indicates the user is logging into the server. |
| */ |
| public static final int LOGGING_IN = 1; |
| |
| /** |
| * Connection state that indicates the user has logged into the server. |
| */ |
| public static final int LOGGED_IN = 2; |
| |
| /** |
| * Connection state that indicates the user is logging out the server. |
| */ |
| public static final int LOGGING_OUT = 3; |
| |
| /** |
| * Connection state that indicate the connection is suspending. |
| */ |
| public static final int SUSPENDING = 4; |
| |
| /** |
| * Connection state that indicate the connection has been suspended. |
| */ |
| public static final int SUSPENDED = 5; |
| |
| /** |
| * The capability of supporting group chat. |
| */ |
| public static final int CAPABILITY_GROUP_CHAT = 1; |
| /** |
| * The capability of supporting session re-establishment. |
| */ |
| public static final int CAPABILITY_SESSION_REESTABLISHMENT = 2; |
| |
| /** |
| * The current state of the connection. |
| */ |
| protected int mState; |
| |
| protected CopyOnWriteArrayList<ConnectionListener> mConnectionListeners; |
| protected Presence mUserPresence; |
| |
| protected ImConnection() { |
| mConnectionListeners = new CopyOnWriteArrayList<ConnectionListener>(); |
| mState = DISCONNECTED; |
| } |
| |
| public void addConnectionListener(ConnectionListener listener) { |
| if (listener != null) { |
| mConnectionListeners.add(listener); |
| } |
| } |
| |
| public void removeConnectionListener(ConnectionListener listener) { |
| mConnectionListeners.remove(listener); |
| } |
| |
| public abstract Contact getLoginUser(); |
| |
| public String getLoginUserName() { |
| Contact loginUser = getLoginUser(); |
| return loginUser == null ? null : loginUser.getName(); |
| } |
| |
| public abstract int[] getSupportedPresenceStatus(); |
| |
| public Presence getUserPresence() { |
| 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 void updateUserPresenceAsync(Presence newPresence) throws ImException { |
| if (mState != LOGGED_IN) { |
| throw new ImException(ImErrorInfo.NOT_LOGGED_IN, "NOT logged in"); |
| } |
| |
| doUpdateUserPresenceAsync(newPresence); |
| } |
| |
| /** |
| * 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. |
| */ |
| public void networkTypeChanged(){ |
| } |
| |
| /** |
| * Tells the current state of the connection. |
| */ |
| public int getState() { |
| return mState; |
| } |
| |
| /** |
| * 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. |
| */ |
| protected void setState(int state, ImErrorInfo error) { |
| if(state < DISCONNECTED || state > SUSPENDED){ |
| throw new IllegalArgumentException("Invalid state: " + state); |
| } |
| if(mState != state){ |
| mState = state; |
| for(ConnectionListener listener : mConnectionListeners){ |
| listener.onStateChanged(state, error); |
| } |
| } |
| } |
| |
| protected void notifyUserPresenceUpdated() { |
| for (ConnectionListener listener : mConnectionListeners) { |
| listener.onUserPresenceUpdated(); |
| } |
| } |
| |
| protected void notifyUpdateUserPresenceError(ImErrorInfo error) { |
| for (ConnectionListener listener : mConnectionListeners) { |
| listener.onUpdatePresenceError(error); |
| } |
| } |
| |
| /** |
| * 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 int getCapability(); |
| |
| /** |
| * Log in to the IM server. |
| * |
| * @param loginInfo the login information. |
| */ |
| public abstract void loginAsync(LoginInfo loginInfo); |
| |
| /** |
| * 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. |
| * <p> |
| * 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 abstract void reestablishSessionAsync(HashMap<String, String> sessionContext); |
| |
| /** |
| * Log out from the IM server. |
| */ |
| public abstract void logoutAsync(); |
| |
| /** |
| * Suspend connection with the IM server. |
| */ |
| public abstract void suspend(); |
| |
| /** |
| * 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 <code>null</code> if the |
| * user has not logged in yet. |
| * @throws UnsupportedOperationException |
| * if session re-establishment is not supported by the |
| * underlying protocol. |
| */ |
| public abstract HashMap<String, String> getSessionContext(); |
| |
| /** |
| * Gets the instance of ChatSessionManager for the connection. |
| * |
| * @return the instance of ChatSessionManager for the connection. |
| */ |
| public abstract ChatSessionManager getChatSessionManager(); |
| |
| /** |
| * Gets the instance of ContactListManager for the connection. |
| * |
| * @return the instance of ContactListManager for the connection. |
| */ |
| public abstract ContactListManager getContactListManager(); |
| |
| /** |
| * 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 ChatGroupManager getChatGroupManager(); |
| |
| protected abstract void doUpdateUserPresenceAsync(Presence presence); |
| |
| } |