diff -r 000000000000 -r 094583676ce7 inc/ImpsFundCli.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/inc/ImpsFundCli.h Thu Dec 17 08:41:52 2009 +0200 @@ -0,0 +1,456 @@ +/* +* 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 in + * , in , + * 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 () of the users + * to be invited + * @param aGroupName = The group () 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 () 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