protocols/bundles/org.eclipse.ecf.protocol.msn/src/org/eclipse/ecf/protocol/msn/MsnClient.java

/*******************************************************************************
 * Copyright (c) 2005, 2007 Remy Suen
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *    Remy Suen <remy.suen@gmail.com> - initial API and implementation
 ******************************************************************************/
package org.eclipse.ecf.protocol.msn;

import java.io.IOException;
import java.net.URLEncoder;
import java.util.Iterator;
import org.eclipse.ecf.protocol.msn.events.ISessionListener;
import org.eclipse.ecf.protocol.msn.internal.encode.ResponseCommand;
import org.eclipse.ecf.protocol.msn.internal.encode.StringUtils;

/**
 * <p>
 * The MsnClient class allows a developer to easily create a client that will
 * authenticate the user and establish a connection with the MSN servers.
 * </p>
 * 
 * <p>
 * <b>Note:</b> This class/interface is part of an interim API that is still
 * under development and expected to change significantly before reaching
 * stability. It is being made available at this early stage to solicit feedback
 * from pioneering adopters on the understanding that any code that uses this
 * API will almost certainly be broken (repeatedly) as the API evolves.
 * </p>
 */
public final class MsnClient {

	/**
	 * The default hostname that will be used to connect to the MSN servers -
	 * messenger.hotmail.com
	 */
	private static final String HOSTNAME = "messenger.hotmail.com"; //$NON-NLS-1$

	/**
	 * The default port that will be used to connect to the MSN servers - 1863
	 */
	private static final int PORT = 1863;

	/**
	 * The NotificationSession that will be connect to the notification server
	 * to handle most non-messaging related incoming and outgoing requests.
	 */
	private NotificationSession notification;

	/**
	 * The list of contacts that are on this user's list.
	 */
	private final ContactList list;

	/**
	 * The user's email address.
	 */
	private String username;

	/**
	 * The name the user displays to other contacts.
	 */
	private String displayName;

	/**
	 * The hostname to use to connect to the dispatch server.
	 */
	private final String hostname;

	/**
	 * The user's personal message.
	 */
	private String personalMessage = ""; //$NON-NLS-1$

	/**
	 * The media that the user is currently playing.
	 */
	private final String currentMedia = "";//$NON-NLS-1$

	/**
	 * The port to use to connect to the dispatch server.
	 */
	private final int port;

	/**
	 * The current status of the user.
	 */
	private Status status;

	/**
	 * Instantiate a new MsnClient that defaults to setting the user as being
	 * online and available when signing in.
	 * 
	 */
	public MsnClient() {
		this(Status.ONLINE);
	}

	/**
	 * Instantiate a new MsnClient that set the user to the specified status
	 * when signing in.
	 * 
	 * @param initialStatus
	 *            the status that a user would like to sign on to the servers
	 *            as, refer to {@link Status#ONLINE} and other static variables
	 *            for the available options.
	 */
	public MsnClient(Status initialStatus) {
		status = initialStatus;
		hostname = HOSTNAME;
		port = PORT;
		list = new ContactList(this);
		notification = new NotificationSession(this);
	}

	/**
	 * Connects the client to the MSN servers.
	 * 
	 * @param userEmail
	 *            the user's email address that is associated with an MSN
	 *            account
	 * @param password
	 *            the email's corresponding password
	 * @throws IOException
	 *             If an I/O error occurred while connecting to the dispatch or
	 *             notification servers.
	 */
	public void connect(String userEmail, String password) throws IOException {
		this.username = userEmail;
		final DispatchSession dispatch = new DispatchSession(hostname, port);
		// get the address of the notification server by first authenticating
		// ourselves
		final String address = dispatch.authenticate(userEmail);
		// close the session
		dispatch.close();
		// connect the notification session to the received address
		notification.openSocket(address);
		try {
			// keep looping until we've connected successfully
			while (!notification.login(userEmail, password)) {
				notification.reset();
			}
		} catch (final RuntimeException e) {
			if (!notification.isClosed()) {
				throw e;
			}
		} catch (final IOException e) {
			if (!notification.isClosed()) {
				throw e;
			}
		}
	}

	/**
	 * Disconnects the user from the MSN servers. Please note that any
	 * {@link ChatSession}s that may have been created since the client was
	 * instantiated are not disconnected automatically in this method.
	 */
	public void disconnect() {
		if (notification != null) {
			try {
				notification.write("OUT"); //$NON-NLS-1$
			} catch (final Exception e) {
				// ignored since we're disconnecting anyway
			}
			notification.close();
		}
		notification = null;
	}

	/**
	 * Changes the user's status to the provided status flag.
	 * 
	 * @param status
	 *            the status that the user wishes to change to
	 * @throws IOException if some problem setting status (e.g. disconnected).
	 */
	public void setStatus(Status status) throws IOException {
		if (this.status != status) {
			if (status == Status.OFFLINE) {
				disconnect();
			} else {
				notification.write("CHG", status.getLiteral() + " 268435488"); //$NON-NLS-1$ //$NON-NLS-2$
			}
			this.status = status;
		}
	}

	/**
	 * Returns the status that the user is currently in.
	 * 
	 * @return the user's current status
	 */
	public Status getStatus() {
		return status;
	}

	void add(String email, String userName) throws IOException {
		notification.write("ADC", "FL N=" + email + " F=" + userName); //$NON-NLS-1$ //$NON-NLS-2$ //$NON-NLS-3$
	}

	void remove(Contact contact) throws IOException {
		final String guid = contact.getGuid();
		for (final Iterator it = contact.getGroups().iterator(); it.hasNext();) {
			notification.write("REM", "FL " + guid + " " //$NON-NLS-1$ //$NON-NLS-2$ //$NON-NLS-3$
					+ list.getGuid((Group) it.next()));
		}
		notification.write("REM", "FL " + guid); //$NON-NLS-1$ //$NON-NLS-2$
	}

	void remove(String guid) throws IOException {
		notification.write("RMG", "FL " + guid); //$NON-NLS-1$ //$NON-NLS-2$
	}

	/**
	 * Returns the contact list that is associated with this client.
	 * 
	 * @return this client's contact list
	 */
	public ContactList getContactList() {
		return list;
	}

	/**
	 * Creates a {@link ChatSession} to connect to the specified contact.
	 * 
	 * @param email
	 *            the contact to connect to
	 * @return the created ChatSession
	 * @throws IOException
	 *             If an I/O error occurred
	 */
	public ChatSession createChatSession(String email) throws IOException {
		final ResponseCommand cmd = notification.getChatSession();
		final ChatSession cs = new ChatSession(cmd.getParam(2), this, username, cmd.getParam(4));
		// reset the ResponseCommand so that the next XFR request won't conflict
		cmd.process(null);
		cs.invite(email);
		return cs;
	}

	void internalSetDisplayName(String newName) {
		displayName = newName;
	}

	/**
	 * Sets the display name of this user.
	 * 
	 * @param newName
	 *            the new name of this user
	 * @throws IOException 
	 */
	public void setDisplayName(String newName) throws IOException {
		notification.write("PRP", "MFN " + URLEncoder.encode(newName)); //$NON-NLS-1$ //$NON-NLS-2$
		displayName = newName;
	}

	/**
	 * Returns the displayed name of this user.
	 * 
	 * @return the name that this user is using
	 */
	public String getDisplayName() {
		return displayName;
	}

	/**
	 * Returns the user's account's email address.
	 * 
	 * @return the email address the user is using for MSN login
	 */
	public String getUserEmail() {
		return username;
	}

	private void sendStatusData() throws IOException {
		final String message = "<Data><PSM>" + personalMessage //$NON-NLS-1$
				+ "</PSM><CurrentMedia>" + currentMedia //$NON-NLS-1$
				+ "</CurrentMedia></Data>"; //$NON-NLS-1$
		notification.write("UUX", message.length() + "\r\n" //$NON-NLS-1$ //$NON-NLS-2$
				+ message, false);
	}

	/**
	 * Sets the user's personal message to the specified string.
	 * 
	 * @param personalMessage
	 *            the new message to use as the user's personal message
	 * @throws IOException
	 *             If an I/O error occurred while sending the data to the
	 *             notification server
	 */
	public void setPersonalMessage(String personalMessage) throws IOException {
		if (personalMessage == null) {
			personalMessage = ""; //$NON-NLS-1$
		} else {
			personalMessage = StringUtils.xmlEncode(personalMessage);
		}
		if (!this.personalMessage.equals(personalMessage)) {
			this.personalMessage = personalMessage;
			sendStatusData();
		}
	}

	/**
	 * Retrieves the user's current personal message.
	 * 
	 * @return the personal message that the user is currently using
	 */
	public String getPersonalMessage() {
		return StringUtils.xmlDecode(personalMessage);
	}

	/**
	 * Add an ISessionListener to this client.
	 * 
	 * @param listener
	 *            the listener to be added
	 */
	public void addSessionListener(ISessionListener listener) {
		notification.addSessionListener(listener);
	}

	/**
	 * Removes an ISessionListener from this client.
	 * 
	 * @param listener
	 *            the listener to be removed
	 */
	public void removeSessionListener(ISessionListener listener) {
		notification.removeSessionListener(listener);
	}
}