inc/ImpsFundCli.h
author Dremov Kirill (Nokia-D-MSW/Tampere) <kirill.dremov@nokia.com>
Thu, 17 Dec 2009 08:41:52 +0200
changeset 0 094583676ce7
permissions -rw-r--r--
Revision: 200949 Kit: 200951

/*
* Copyright (c) 2002-2005 Nokia Corporation and/or its subsidiary(-ies). 
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description: 
*       Interface for WV fundamental services.
*       The supported features are search and invite.
*
*/


#ifndef CImpsFundCli_H
#define CImpsFundCli_H

// INCLUDES
#include "impsclient.h"
#include "impsfundamental.h"

// FORWARD DECLARATIONS
class CImpsFundCommand2;
class MImpsSearchHandler2;
class MImpsInviteHandler2;

// CLASS DECLARATION

/**
*  RImpsFundClient2 API
*
*  Applications use the subsystem via RImpsFundClient2 class. First, they need
*  to connect to the server by calling RegisterL() member function. 
*  
*  When everything is done, call Unregister() to end
*  the session.
*
*  A user of this API must be aware that raising/releasing
*  the PDP context may affect the response times of called functions.
*
*
*  Observer methods:
*  -----------------------
*  Client can be notified when a certain type of message is received 
*  from the remote server.
*  Client has to be connected in the server in order to get notify events.
*  If the client is disconnected by server by calling Unregister(), all notify
*  requests and possible incoming events are canceled. 
*
*  Notify events are session-specific, ie. if you have several RImpsFundClients
*  connected to the server, each has its own notify requests. 
*
*  In order to use search feature, you need to implement MImpsSearchHandler2 
*  and give a pointer to your class in RegisterL.
*  Observer method doesn't need to do anything else than your application 
*  needs it to do.
*
*/ 


class RImpsFundClient2 : public RImpsClient2
    {

    public: // Constructors and destructor

        /**
        * C++ default constructor.
        */      
        IMPORT_C RImpsFundClient2();

    public: // New functions        

        // INITILIZATION AND CONNECT

        /**
        * Registers the listener objects for Fundamental events and connects
        * to the Symbian OS Server.
        * Leaves with KImpsErrorAlreadyInUse if the client 
        * has already registered.
        * @param aEngine WV Engine server instance
        * @param aSearchObs search result observer. May be NULL.
        * @param aInviteObs invite observer. May be NULL.
        * @param aClientId Client-Id for requests if non zero length.
        * @param aReceiveNew determines if new pushed messages are received.
        *        If EFalse then new messages are filtered out and 
        *        responses to own requests are deliverd only.
        * @param aPriority Observer priority. Refers to CActive priority.
        */
        IMPORT_C void RegisterL( RImpsEng& aEngine, 
                                 MImpsSearchHandler2* aSearchObs,
                                 MImpsInviteHandler2* aInviteObs,
                                 const TDesC& aClientId,
                                 TBool aReceiveNew = ETrue,
                                 TInt aPriority = CActive::EPriorityStandard );

        /**
        * Unregisters the listener objects and disconnects from the server.
        */
        IMPORT_C void Unregister();


        // Fundamental SERVICES

        /**
        * Start search
        * @param aPairs defines what is to be searched
        * @param aSearchLimit how many results you want
        * @return operation-id (positive)
        */
        IMPORT_C TInt SearchFirstL( const CSearchPairs& aPairs,
                                    TInt aSearchLimit );
        
        /**
        * Continue search
        * @param aSearchID which search is to be continued
        * @param aIndex from which index the search is continued
        * @return operation-id (positive)
        */
        IMPORT_C TInt SearchNextL( TInt aSearchID, 
                                   TInt aIndex );


        /**
        * Stop search
        * @param aSearchID which search is to be stopped
        * @return operation-id (positive)
        */
        IMPORT_C TInt StopSearchL( TInt aSearchID );

              
        /* --- Comments on the parameters ---
        *
        *  - aInviteID
        *    Spec says this must be unique in the context of 
        *    the "server domain".
        *    Thus it is possible, though not very likely, that some other
        *    client may send the exact same ID that we did.
        *  
        *  - aUserID, aScreenName & aGroupName
        *    There may be more than one user in more than one group invited
        *    with a single request. The list of the invitees, according to 
        *    the spec, can be "any combination of" user IDs and screen names.
        *    What this means in practice is that the users can be identified 
        *    either by their user ID or screen name. For this reason, 
        *    the indexes of aScreenName and aGroupName
        *    MUST correspond to each other. 
        *    For example, if we want to invite the user <SName="Opa"> in 
        *    <GroupID="Chess">, <SName="Opa"> in <GroupID="Chess">, 
        *    aScreenName[0] must be "Opa" and aUserGroupID[0] "Chess". 
        *    Thus, if user ID is specified, the client does not check the array
        *    for screen names on top of that. If, on the other hand, there 
        *    is no user ID, BOTH screen name AND group ID MUST be present.
        *
        *  --- Comments end --- 
        */

        /** 
        *  Invite users to a group
        *  Primitive: InviteRequest
        *  Note that the aScreenName & aGroupName parameters together form the
        *  actual screen name primitives
        *  @param aInviteID         = Invite ID; unique in the context 
        *                             of the session
        *  @param aUserID           = IDs of the users to invite
        *  @param aScreenName       = Screen names (<SName>) of the users 
        *                             to be invited
        *  @param aGroupName        = The group (<GroupID>) in which the screen 
        *                             name is unique
        *  @param aInviteGroup      = ID of the group to which the users
        *                             are invited to join
        *  @param aOwnScreenName    = SName of the inviter
        *  @param aOwnGroupName     = The group, in which the inviters 
        *                             SName is unique
        *  @param aInviteReason     = Free text
        *  @param aValidityPeriod   = How long is this invitation valid
        *  @return operation-id (positive)
        */
        IMPORT_C TInt GroupInviteL( const TDesC& aInviteID,
                                    const MDesCArray* aUserID,
                                    const MDesCArray* aScreenName,
                                    const MDesCArray* aGroupName,
                                    const TDesC& aInviteGroup,
                                    const TDesC& aOwnScreenName,
                                    const TDesC& aOwnGroupName,
                                    const TDesC& aInviteReason,
                                    const TInt aValidityPeriod );

        /** 
        *  Invite user to IM conversation
        *  Primitive: InviteRequest
        *  @param aInviteID         = Invite ID; unique in the context 
        *                             of the session
        *  @param aInviteReason     = Free text
        *  @param aValidityPeriod   = How long is this invitation valid?
        *  @return operation-id (positive)
        */
        IMPORT_C TInt ImInviteL( const TDesC& aInviteID,
                                 const TDesC& aUserID,                              
                                 const TDesC& aInviteReason,
                                 const TInt aValidityPeriod );
        
        /**
        *  Cancel an invite 
        *  Primitive: CancelInviteRequest
        *  @param aInviteID         = Invite to be cancelled
        *  @param aUserID           = ID(s) of the user(s)
        *  @param aScreenName       = Screen names (<SName>) of the users
        *  @param aGroupName        = Name of the group 
        *  @param aCancelReason     = A short text describing the 
        *                             reason for the cancelling.
        *  @param aOwnScreenName    = Screen name of the canceller
        *  @param aOwnGroupName     = Group name of the canceller.
        *  @return operation-id (positive)
        */
        IMPORT_C TInt CancelInviteL( const TDesC& aInviteId,
                                     const MDesCArray* aUserID,
                                     const MDesCArray* aScreenName,
                                     const MDesCArray* aGroupName,
                                     const TDesC& aCancelReason, 
                                     const TDesC& aOwnScreenName,
                                     const TDesC& aOwnGroupName );

        /**
        *  Send response to invite
        *  Primitive: InviteUserResponse
        *  @param aInviteId         = ID of the invite response
        *  @param aAcceptance       = Do we meet the claim
        *  @param aInviteResponse   = Textual description of the response
        *  @param aOwnScreenName    = Screen name of the responding user
        *  @param aOwnGroupName     = Group name of the responding user
        *  @return operation-id (positive)
        */
        IMPORT_C TInt InviteResponseL( const TDesC& aInviteId,
                                       TBool aAcceptance,
                                       const TDesC& aInviteResponse,
                                       const TDesC& aOwnScreenName,
                                       const TDesC& aOwnGroupName );


        /**
        * Pointer to the search observer handler
        * @return handler
        */
        inline MImpsSearchHandler2* SearchHandler() const;

        /**
        * Pointer to the invite observer handler
        * @return handler
        */
        inline MImpsInviteHandler2* InviteHandler() const;


    private:

        /**
        * Registers the listener object for Fund events and connects to
        * the Symbian OS Server.
        * @param aEngine WV Engine server instance
        * @param aHandler the observer
        * @return general error code
        */
        TInt DoRegister( 
           RImpsEng& aEngine,
           CImpsHandler2* aHandler );

    private: // data

        CImpsFundCommand2*             iCommand;
        MImpsSearchHandler2*           iSearchCallBack;
        MImpsInviteHandler2*           iInviteCallBack;
       

    private: // friend classes

        friend class CImpsFundCommand2;
    
    };

// CLASS DECLARATION

/**
* MImpsSearchHandler2
*
* Abstract interface for handling the search result events from the server.
* User derives his class from this and implements the methods below.
*/

class MImpsSearchHandler2
    {

    public: // New functions

    /**
    * Observer method for search response
    * Primitive: SearchResponse
    * @param aId operation id returned by SearchFirstL or SearchNextL.
    * @param aSearchID search operation id, 
    *        used when search is continued or stopped.
    * @param aIndex indicates the particular index from which the 
    *        next search can start. It is 0 in error case.
    * @param aResultsFound indicates the number of the current findings.
    * @param aCompleted TRUE if server has completed the search, 
    *        FALSE if there are more results available.
    * @param aType which kind of items there are in aResults parameter
    * @param aResults list of results, 
    *        NULL if none.
    * @param aCspId CSP session identifier
    */
    virtual void HandleSearchL( TInt aId, 
                                TInt aSearchId, 
                                TInt aIndex, 
                                TInt aResultsFound, 
                                TBool aCompleted, 
                                TImpsSearchResultType aType,
                                MDesCArray* aResults ,
                                TImpsCspIdentifier& aCspId )  = 0;


    /**
    * Observer for stopped search
    * This is called when WV server has stopped the search after StopSearchL.
    * Notice that a previous search is invalidated 
    * when a new search is started,
    * but this method is not called in that situation.
    * @param aId operation id returned by StopSearchL.
    * @param aSearchID search operation id, 
    *        used when search was stopped.
    * @param aCspId CSP session identifier
    */
    virtual void HandleSearchStoppedL( TInt aId, 
                                       TInt aSearchId,
                                       TImpsCspIdentifier& aCspId )  = 0;

    };

/**
* MImpsInviteHandler2
*
* Abstract interface for handling invite events from the server.
* User derives from this and implements the pure virtual methods below.
*/
class MImpsInviteHandler2
    {
    public:

        /**
        *  Handle invite to a group
        *  Primitive: InviteUserRequest
        *  @param aInviteID         = ID of the invite request
        *  @param aUserID           = User ID of the inviter
        *  @param aScreenName       = SName of the inviter
        *  @param aGroupName        = GroupID of the inviter
        *  @param aInviteReason     = Textual description of the invitation
        *  @param aValidityPeriod   = Time that the invitation is valid
        *  @param aCspId CSP session identifier
        */
        virtual void HandleGroupInviteL( const TDesC& aInviteID,
                                         const TDesC& aUserID,
                                         const TDesC& aScreenName,
                                         const TDesC& aGroupName,
                                         const TDesC& aInviteReason,
                                         const TInt aValidityPeriod,
                                         TImpsCspIdentifier& aCspId )  = 0;

        /**
        *  Handle invite to a conversation
        *  Primitive: InviteUserRequest
        *  @param aInviteID         = ID of the invite request
        *  @param aUserID           = User ID of the inviter
        *  @param aInviteReason     = Textual description of the invitation
        *  @param aValidityPeriod   = Time that the invitation is valid
        *  @param aCspId CSP session identifier
        */
        virtual void HandleImInviteL( const TDesC& aInviteID,
                                      const TDesC& aUserID,
                                      const TDesC& aInviteReason,
                                      const TInt aValidityPeriod,
                                      TImpsCspIdentifier& aCspId )  = 0;

        /**
        *  Meaning of this method is to provide a way that SAP can use to ask 
        *  if the user accepts multimedia content in incoming messages. If the
        *  url is something else than a fixed one ( stored in CenRep ) the
        *  client should use browser to message retrieving. If the url is 
        *  the fixed one the client should either accept or deny the multimedia
        *  content receiving by sending InviteResponse.
        *  Primitive: InviteUserRequest
        *  @param aInviteID         = ID of the invite request
        *  @param aUserID           = User ID of the inviter
        *  @param aUrlList          = List of url's
        *  @param aInviteReason     = Textual description of the invitation
        *  @param aValidityPeriod   = Time that the invitation is valid
        *  @param aCspId CSP session identifier
        */
        virtual void HandleContentInviteL( const TDesC& aInviteID,
                                           const TDesC& aUserID,
                                           MDesCArray* aUrlList,
                                           const TDesC& aInviteReason,
                                           const TInt aValidityPeriod,
                                           TImpsCspIdentifier& aCspId )  = 0;

        /**
        *  Handle invite response  
        *  Primitive: HandleInviteResponse
        *  @param aInviteId             = ID of the invite request
        *  @param aAcceptance           = Was the invitation accepted or not
        *  @param aUserID               = UserID of the responding user
        *  @param aScreenName           = SName of the responding user
        *  @param aGroupName            = Group ID of the responding user
        *  @param aInviteResponse       = Textual description of the response
        * @param aCspId CSP session identifier
        */
        virtual void HandleInviteResponseL( const TDesC& aInviteID,
                                            const TBool aAcceptance,
                                            const TDesC& aUserID,
                                            const TDesC& aScreenName,
                                            const TDesC& aGroupName,
                                            const TDesC& aResponse,
                                            TImpsCspIdentifier& aCspId )  = 0;

        /**
        * Handle cancelled invite
        * Primitive: CancelInviteUserRequest
        * @param aInviteID              = ID of the invitation request
        * @param aUserID                = ID of the cancelling user
        * @param aScreenName            = SName of the canceller
        * @param aGroupName             = GroupID of the canceller
        * @param aCancelReason          = Textual description of 
        *                                 the cancellation
        * @param aCspId CSP session identifier
        */
        virtual void HandleInviteCancelL( const TDesC& aInviteID,
                                          const TDesC& aUserID,
                                          const TDesC& aScreenName,
                                          const TDesC& aGroupName,
                                          const TDesC& aResponse,
                                          TImpsCspIdentifier& aCspId )  = 0;

        /**
        * Handle server response after request
        * @param aOpId  operation id to map responses to the requests.
        * @param aCspId CSP session identifier
        */
        virtual void  HandleCompleteL( TInt aOperationId, 
                                       TImpsCspIdentifier& aCspId )  = 0;
    };

#include "impsfundcli.inl"

#endif