/*
* (standard BSD license)
*
* Copyright (c) 2002, Chad Myers, et al.
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without modification,
* are permitted provided that the following conditions are met:
*
* Redistributions of source code must retain the above copyright notice, this
* list of conditions and the following disclaimer. Redistributions in binary form
* must reproduce the above copyright notice, this list of conditions and the
* following disclaimer in the documentation and/or other materials provided with
* the distribution. Neither the name of SourceForge, nor Microsoft nor the names
* of its contributors may be used to endorse or promote products derived from
* this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
* WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
* IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
* INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
* BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
* OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
* THE POSSIBILITY OF SUCH DAMAGE.
*/
using System;
namespace MSNP{
/// <summary>
/// Interface for defining a class that will handle sessions when they are created or requested.
/// </summary>
/// <remarks>
/// <para>This interface is used to define the class that will be passed in to the <see cref="MSNPHelper"/> and will be
/// used whenever a session is created (either the user is called or is calling).</para>
/// <para>The implementing class should be created and passed in to the <see cref="MSNPHelper"/>. It is expected that this
/// class will be called multiple times by multiple threads. Each method should be completely thread-safe as they will
/// get called frequently by whatever sessions are open at the time.</para>
/// <para>Each time a function is called, the <see cref="Session"/> is passed in to give the function context.
/// The <see cref="Session"/> object contains a <see cref="Session.SessionIdentifier"/> that can be used to distingush one session from another.
/// It is up to the implementer to ensure that these session identifiers are unique or useful to the app.</para>
/// <para>When a session is started by calling <see cref="MSNPHelper.RequestSession"/> a session identifier can be
/// passed in to identify the session when it is created. Sessions that are created because another user called in
/// will have a null session identifier. The implementer can then set an identifier on the session at that time.</para>
/// <para>Sessions are not exclusive between two users. At any time, this user or the other user could add another user
/// to the session forming a party-line situation. The <see cref="UserJoined"/> method will alert you to the joining of another
/// user to the session.</para>
/// </remarks>
public interface ISessionHandler
{
/// <summary>
/// Called when a session is starting.
/// </summary>
/// <remarks>
/// <para>If this session is starting because the user requested a session with a user (called another user),
/// then the session will have no users in it (as the CAL command has not yet been placed). Sending messages
/// at this time is pointless. Wait for the <see cref="UserJoined"/> method to be called before communicating.</para>
/// <para>If this session was the result of being called (as opposed to calling, or a request to start a new session),
/// the <see cref="Session.SessionIdentifier"/> property on the <see cref="Session"/> will be null. Otherwise,
/// it will be whatever was passed into the <see cref="MSNPHelper.RequestSession"/> method.
/// </para>
/// </remarks>
/// <param name="session">The session which has been created.</param>
void SessionStarted(Session session);
/// <summary>
/// Called when a message has been received by one of the other users in the session.
/// </summary>
/// <param name="session">The session on which the message arrived</param>
/// <param name="message">The message that was sent.</param>
void MessageReceived(Session session, MimeMessage message);
/// <summary>
/// Called when a user has joined the session.
/// </summary>
/// <remarks>
/// Multiple users can join a session if they are invited by one of the users already in the session.
/// </remarks>
/// <param name="session">The session to which the user has joined.</param>
/// <param name="userHandle">The handle of the user who joined. This is usually the email of the user (johndoe@msn.com)</param>
/// <param name="userFriendlyName">The friendly name of the user who joined (John Doe).</param>
void UserJoined(Session session, String userHandle, String userFriendlyName);
/// <summary>
/// Called when a user has left the session.
/// </summary>
/// <remarks>
/// <para>This can be the only other user, or one of the users in a multi-user chat.</para>
/// <para>When the last user has left, the session will expire and end after the timeout perid (default 30 seconds)</para>
/// </remarks>
/// <param name="session">The session from which the user left</param>
/// <param name="userHandle">The handle (or email) of the user that left.</param>
void UserDeparted(Session session, String userHandle);
/// <summary>
/// Called when a session is terminating.
/// </summary>
/// <remarks>
/// <para>
/// The session has ended and been disconnected. No messages or commands can be sent at this point.</para>
/// <para>This call is merely to allow the implementer to remove the session from any lists being kept.</para>
/// </remarks>
/// <param name="session">The session which has just ended</param>
void SessionEnded(Session session);
/// <summary>
/// Called when an error is returned from the server
/// </summary>
/// <param name="session">The session on which the error occured</param>
/// <param name="errorDescription">The description of the error</param>
void ErrorReceived(Session session, String errorDescription);
}
}
|