--- /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 <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