/*
* Copyright (c) 2006 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:
* xSP View client-side API.
*
*/
#ifndef __XSPVIEWSERVICES_H__
#define __XSPVIEWSERVICES_H__
// INCLUDES
#include <e32cmn.h>
#include <e32svr.h>
#include <MVPbkContactLink.h>
// CLASS DECLARATION
/**
* The xSP View API, which is used to bring a certain
* view in front and get tab-view information.
*
* There is an issue with KErrServerTerminated error code
* sometimes returned by this API functions. This situation
* may arise when server object is terminated with the
* Phonebook process but clients outside the Phonebook
* are not informed and their handles remain open. A way to
* deal with this KErrServerTerminated error is to close
* the handle first by calling Close() and then reopen it
* by calling Open() or Activate() methods which do not
* require explicit Open() calls.
*
* The following panic codes are possible in case the API is abused:
*
* Panic category xSPViewActivator. These panics represent programming errors
* which are detected by the view activator service that activates a tab view.
* Possible panic codes for this category are: EBadDescriptorLength = 0
* (descriptor length was illegal), EBadDescriptor = 1 (descriptor type was
* not correct; could not write to client side descriptor buffer).
*/
class RxSPViewServices : public RSessionBase
{
public: // Implementation
/**
* Opens a session to the server. Launches Phonebook in the background.
* @return Error code
*/
IMPORT_C TInt Open();
/**
* Closes the session.
*/
IMPORT_C void Close();
/**
* Triggers xSP extension view activation. Starts the Phonebook
* if it was not running already. Designed to be used by
* the xSP extension view activator. If the session was not
* open, this method will open one and close it afterwards.
* If the session was open, this method will not close it
* afterwards.
* @param aEComID xSP extension ECom implementation ID
* @param aOriginalViewID view original / old ID
* @return KErrNone if successful, error code otherwise
*/
IMPORT_C TInt Activate( TUint32 aEComID,
TInt aOriginalViewID);
/**
* Triggers xSP extension view activation. Starts the Phonebook
* if it was not running already. Designed to be used by
* the xSP extension view activator. If the session was not
* open, this method will open one and close it afterwards.
* If the session was open, this method will not close it
* afterwards.
* @param aEComID xSP extension ECom implementation ID
* @param aOriginalViewID view original / old ID
* @param aContactLink which contact item to show
* @param aFocusedField which field gets the focus
*/
IMPORT_C void ActivateL( TUint32 aEComID,
TInt aOriginalViewID,
MVPbkContactLink* aContactLink,
TInt aFocusedField );
/**
* Triggers xSP extension view activation. Starts the Phonebook
* if it was not running already. Designed to be used by
* the xSP extension view activator. If the session was not
* open, this method will open one and close it afterwards.
* If the session was open, this method will not close it
* afterwards.
* @param aEComID xSP extension ECom implementation ID
* @param aOriginalViewID view original / old ID
* @param aParamBuf specifies which contact to show (see CPbk2ViewState.h or
* CPbkViewState.h for details)
* @return KErrNone if successful, error code otherwise
*/
IMPORT_C TInt Activate( TUint32 aEComID,
TInt aOriginalViewID,
TPtr8& aParamBuf);
/**
* Triggers view activation asynchronously.
*
* @param aEComID xSP extension ECom implementation ID
* @param aOriginalViewID view original / old ID
* @param aParamBuf specifies which contact to show (see CPbk2ViewState.h or
* CPbkViewState.h for details)
* @param aStatus contains the status of the request on completion
*/
IMPORT_C void Activate( TUint32 aEComID,
TInt aOriginalViewID,
TPtr8& aParamBuf,
TRequestStatus& aStatus );
/**
* Cancel activate
* @return KErrNone if successful, error code otherwise
*/
IMPORT_C TInt CancelActivate() const;
/**
* Constructor
*/
IMPORT_C RxSPViewServices();
/**
* Opens a session to the server. Async version.
* Launches Phonebook in the background.
* @param aAsyncMessageSlots The number of message slots available to session.
* @param aType type of session to create.
* @param aStatus request status
* @return Error code
*/
IMPORT_C TInt Open( TInt aAsyncMessageSlots,
TIpcSessionType aType,
TRequestStatus& aStatus );
/**
* Get view count
* @param aCount placeholder for view count
* @return KErrNone if successful, error code otherwise
*/
IMPORT_C TInt GetViewCount( TInt& aCount ) const;
/**
* Get view count. Async version.
* @param aCount placeholder for view count
* @param aStatus request status
* @return KErrNone if successful, error code otherwise
*/
IMPORT_C TInt GetViewCount( TInt& aCount,
TRequestStatus& aStatus );
/**
* Cancel async get view count
* @return KErrNone if successful, error code otherwise
*/
IMPORT_C TInt CancelGetViewCount() const;
/**
* Get packed view data buffer length
* @param aIndex view index
* @param aLength placeholder for buffer length
* @return KErrNone if successful, error code otherwise
*/
IMPORT_C TInt GetPackedViewDataBufferLength( TInt aIndex,
TInt& aLength ) const;
/**
* Get packed view data buffer length. Async version.
* @param aIndex view index
* @param aLength placeholder for buffer length
* @param aStatus request status
* @return KErrNone if successful, error code otherwise
*/
IMPORT_C TInt GetPackedViewDataBufferLength( TInt aIndex,
TInt& aLength,
TRequestStatus& aStatus );
/**
* Cancel async get packed view data buffer length
* @return KErrNone if successful, error code otherwise
*/
IMPORT_C TInt CancelGetPackedViewDataBufferLength() const;
/**
* Get packed view data
* @param aIndex view index
* @param aPackedViewData reference to allocated buffer.
* The buffer will contain packed data on successful return
* @return KErrNone if successful, error code otherwise
*/
IMPORT_C TInt GetPackedViewData( TInt aIndex, TDes8& aPackedViewData ) const;
/**
* Get packed view data. Async version.
* @param aIndex view index
* @param aPackedViewData reference to allocated buffer.
* The buffer will contain packed data on successful completion
* @param aStatus request status
* @return KErrNone if successful, error code otherwise
*/
IMPORT_C TInt GetPackedViewData( TInt aIndex,
TDes8& aPackedViewData,
TRequestStatus& aStatus );
/**
* Cancel get packet view data
* @return KErrNone if successful, error code otherwise
*/
IMPORT_C TInt CancelGetPackedViewData() const;
private: // Private methods
/**
* Returns the client side API version.
*/
TVersion Version() const;
/**
* Starts the Phonebook if it is not already running.
*/
void StartPhonebookL();
private: // data
/// Own: pointer to view count
TPtr8 iViewCount;
/// Own: pointer to packed view data buffer length
TPtr8 iPackedViewDataBufferLength;
};
#endif // __XSPVIEWSERVICES_H__
// End of file.