FCL/sf/app/im: comparison inc/ImpsFundCli.h

equal deleted inserted replaced

--1:000000000000
+:094583676ce7
+/*
+* 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