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