application.h

/*************************************************************************** application.h - description ------------------- begin : Thu Mar 20 2003 copyright : (C) 2003 by Mike K. Bennett email : mkb137b@hotmail.com ***************************************************************************//*************************************************************************** * * * This program is free software; you can redistribute it and/or modify * * it under the terms of the GNU General Public License as published by * * the Free Software Foundation; either version 2 of the License, or * * (at your option) any later version. * * * ***************************************************************************/#ifndef APPLICATION_H#define APPLICATION_H#include "../chatmessage.h"#include <QObject>// Forward declarationsclass Chat;
class MimeMessage;
/** * @brief Base class for all application invitations. * This class only provides the essentials like accept/cancel notifications. * * Application invitations can be used to start an out-of-band * session such as file transfers, voice and webcam conversations. * Other contacts are invited by creating an instance of an Application class, * and calling the start() method afterwards. * Responses from the other contact are passed to the <code>gotMessage()</code> method. * Both MimeApplication and P2PApplication implement their own version of this method. * The <code>gotMessage()</code> method also detects whether the contact sent the invitation. * * To implement your own application handler, create a new class which derives * from either MimeApplication or P2PApplication. The new application class should * implement the missing <code>contactStarted*</code> and <code>userStarted*</code> methods. * The <code>contactStarted*</code> methods are used for sessions started by the other contact (the chat buddy), * while the <code>userStarted*</code> methods are used for sessions started by the user itself (the KMess user). * Also note how each Application subclass implements a static <code>getAppId()</code> * method to return the Application GUID. This GUID is used to detect the invitation type. * * @author Mike K. Bennett, Diederik van der Boor (mime/p2p stuff) * @ingroup Applications */00055class Application : public QObject
{
Q_OBJECT
public:
00061enumApplicationMode
{
00063APP_MODE_NORMAL, ///< Normal mode (all messages should appear in the Chat Window)//APP_MODE_BACKGROUND, // /< Background mode (status messages shouldn't appear)00065APP_MODE_ERROR_HANDLER, ///< Application instance is started to handle an error.00066APP_MODE_DATACAST///< Application instance is started to emulate a datacast message (ink receiving, winks in msn6). };
// The constructorApplication(const QString &contactHandle);
// The destructorvirtual~Application();
// The contact cancelled the sessionvirtualvoidcontactAborted(const QString &message = QString::null);
// Return the chat the application was originally created for (may be null).Chat *getChat() const;
// Return the handle of the other contactconst QString& getContactHandle() const;
// Return the application's identifying cookieconst QString& getCookie() const;
// A command for the application was received (i.e. "Accept" or "Reject")voidgotCommand(QString command);
// Read the current mode of the applicationintgetMode() const;
// Indicate whether the application is closing or not.boolisClosing() const;
// Returns whether the application can operate in a multi-chat session, or requires a private chat.virtualboolisPrivateChatRequired() const;
// Set the chat the application was originally created for.voidsetChat( Chat *chat );
// Set the current mode of the applicationvoidsetMode(ApplicationMode mode);
// Start the applicationvoidstart();
// The user cancelled the sessionvirtualvoiduserAborted();
protected: // Protected methods// Reasons why invitations get cancelled.00102enumApplicationCancelReason
{
00104CANCEL_INVITATION, ///< User cancelled the invitation (aka rejected)00105CANCEL_ABORT, ///< User cancelled the session before it completed (real cancel)00106CANCEL_NOT_INSTALLED, ///< Requested service is not installed00107CANCEL_TIMEOUT, ///< Timeout waiting for contact to accept / send data00108CANCEL_FAILED, ///< Failed to initialize the session / start the app00110CANCEL_INVALID_SLP_CONTENT_TYPE///< Got an invalid content-type, abort the session (P2P only) };
// The contact rejected the invitationvoidcontactRejected(const QString &message = QString::null);
// Step one of a contact-started chat: the contact invites the uservirtualvoidcontactStarted1_ContactInvitesUser(constMimeMessage& message);
// Step two of a contact-started chat: the user acceptsvirtualvoidcontactStarted2_UserAccepts();
// Step three of a contact-started chat: the contact confirms the acceptvirtualvoidcontactStarted3_ContactConfirmsAccept(constMimeMessage& message);
// Close the appliation (asks switchboard to delete this object)voidendApplication();
// Request the application to not delete itself while doing external work, like displaying a dialog.void delayDeletion( bool doDelay );
// Return an reject message to display.virtual QString getContactAbortMessage() const;
// Return a reject message to display.virtual QString getContactRejectMessage() const;
// Return an abort message to displayvirtual QString getUserAbortMessage() const;
// Return a reject message to displayvirtual QString getUserRejectMessage() const;
// Generate a random invitation or authorization cookie.
QString generateCookie() const;
// Return the external IP addressconst QString& getExternalIp() const;
// Return the local IP addressconst QString& getLocalIp() const;
// Read the "user started this app" state.boolisUserStartedApp() const;
// Return true if the user should press accept/cancel soon.boolisWaitingForUser() const;
// Replace an application's accept/reject/cancel links with another textvoidmodifyOfferMessage( const QString& newMessage = QString() );
// Let the user accept or reject the applicationvoidofferAcceptOrReject(const QString& appHtml);
// Let the user cancel the applicationvoidofferCancel(const QString& appHtml); /** * @brief Send a cancel message and terminate the application. * * This method needs to be implemented in the derived classes to send the correct cancel messages. * After sending a cancel message, the application should eventually be aborted * (either because of a timeout, or direct call to endApplication()). * * @param cancelReason Reason for sending the cancel message. */virtualvoidsendCancelMessage(constApplicationCancelReason cancelReason) = 0;
// Set the type of application we're startingvoidsetApplicationType( ChatMessage::MessageType type );
// Indicate the application is closing or not.voidsetClosing(bool closing);
// Show a message to notify the user of a event (e.g. user invited, cancelled,connecting to host, the transfer is complete, etc..)virtualvoidshowEventMessage(const QString &message, const ChatMessage::ContentsClass contents, bool isIncoming = true );
// Show a message to notify about a system error (e.g. invitation not supported)virtualvoidshowSystemMessage(const QString &message, const ChatMessage::ContentsClass contents, bool isIncoming = true );
// Called when the transfer is complete.virtualvoidshowTransferComplete();
// Show a message to inform about a transfer event (shown in the transfer dialog, e.g. connecting to host)virtualvoidshowTransferMessage(const QString &message);
// Show the progress made during a transfer.virtualvoidshowTransferProgress( const ulong bytesTransferred );
// Set the cookie from an INVITE commandvoidstartByInvite(const QString &invitationCookie);
// The user rejected the invitationvirtualvoiduserRejected();
// Step one of a user-started chat: the user invites the contactvirtualvoiduserStarted1_UserInvitesContact();
// Step two of a user-started chat: the contact acceptsvirtualvoiduserStarted2_ContactAccepts(constMimeMessage& message);
// Step three of a user-started chat: the user prepares for the sessionvirtualvoiduserStarted3_UserPrepares();
private: // Private attributes// The chat the application was originally initiatialized in.Chat *chat_;
// The application is closingbool closing_;
// The applications identifying cookie
QString cookie_;
// Contact handle
QString contactHandle_;
// The application is closingbool doDelayDeletion_;
// The current modeApplicationMode mode_;
// Current application type
ChatMessage::MessageType type_;
// Whether or not the user answered the invitation alreadybool userAnswered_;
// Whether or not the user started the appbool userStartedApp_;
// True if waiting for the user to acceptbool waitingForUser_;
signals: // Signals /** * Signal that this application likes to display a message * @param message The message to display. */voidapplicationMessage( constChatMessage &message ); /** * Signal that this application needs to update its accept/cancel links with another text * @param newMessage The new message to display. */voidupdateApplicationMessage( const QString &messageId, const QString &newMessage );
/** * Signal that this application's activity has ended and that it should be deleted. * @param object Reference to the this object. */voiddeleteMe(Application *object);
};
#endif