/*
* Copyright (c) 2004 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: Transaction status container interfaces.
*
*/
#ifndef __MPENGTRANSACTIONSTATUS2_H__
#define __MPENGTRANSACTIONSTATUS2_H__
// INCLUDES
#include <E32Std.h>
//FORWARD DECLARATION
class MPEngDetailedResultEntryExtension2;
class MPEngTransactionStatusExtension2;
class MPEngTransactionStatusCopy2;
// CLASS DECLARATION
/**
* Enumeration defining different description
* texts inside detailed result.
*
* @since 3.0
*/
enum TPEngDetailedResultDescriptionText2
{
// The failed presence id
EPEngDTPresenceID = 1,
// The failed contact list id
EPEngDTContactListID = 2,
//Description of the error if present
EPEngDTErrorDescription = 3
};
/**
* Enumeration defining different description
* integers inside detailed result.
*
* @since 3.0
*/
enum TPEngDetailedResultDescriptionInteger2
{
//The failed attribute id
EPEngDIAttributeID = 1
};
/**
* Detailed result entry.
*
* This interface offers access to one detailed
* result entry.
*
* @since 3.0
*/
class MPEngDetailedResultEntry2
{
public:
/**
* Gets the transaction operation that produced
* this detailed error.
*
* @since 3.0
* @return Error operation.
*/
virtual TInt Operation() const = 0;
/**
* Gets the error code for this detailed error.
*
* Might be error code from common Symbian OS
* error codes, or error code from network transaction.
*
* @since 3.0
* @return Error code.
*/
virtual TInt Error() const = 0;
/**
* Gets descriptive text from detailed result entry.
* If requested description text isn't set, returns
* KErrNotFound, else returns KErrNone and aDescriptionText
* is set to point description value.
*
* @since 3.0
* @param aDescriptionText On the return contains requested
* description text. If requested text isn't set,
* contains on the return empty descriptor. Note:
* No need to construct a local buffer for descriptor,
* pass just TPtrC and on the return TPtrC is set to point
* correct data.
*
* @param aDescriptionID Which description text to get.
* @return If description isn't set: KErrNotFound.
* Else KErrNone.
*/
virtual TInt GetDetailedDesc( TPtrC& aDescriptionText,
TPEngDetailedResultDescriptionText2 aDescriptionID ) const = 0;
/**
* Gets description integer from detailed result entry.
* If requested description integer isn't set, returns
* KErrNotFound, else returns KErrNone and aDescriptionInt
* is set to contain description value.
*
* @since 3.0
* @param aDescriptionInt On the return contains requested
* description integer. If requested integer isn't set,
* contains 0 on the return.
* @param aDescriptionID Which description integer to get.
* @return If description isn't set: KErrNotFound:
* Else KErrNone.
*/
virtual TInt GetDetailedInt( TUint32& aDescriptionInt,
TPEngDetailedResultDescriptionInteger2 aDescriptionID ) const = 0;
protected: //Extensions interface
/**
* Detailed result entry extension interface.
*
* @since 3.0
* @return Detailed result entry extension.
* Currently NULL.
*/
virtual MPEngDetailedResultEntryExtension2* EntryExtension() = 0;
protected:
/**
* Virtual destructor.
*
* Detailed result entries can't be destroyed
* using this interface.
*/
virtual ~MPEngDetailedResultEntry2() {};
};
// CLASS DECLARATION
/**
* Enumeration defining different description
* texts inside MPEngTransactionStatus2 container.
*
* Reserved for future use. Currently no texts.
*
* @since 3.0
*/
enum TPEngTransStatusDescriptionText2
{
};
/**
* Enumeration defining different description
* integers inside MPEngTransactionStatus2 container.
*
* Reserved for future use. Currently no integers.
*
* @since 3.0
*/
enum TPEngTransStatusDescriptionInteger2
{
};
// CLASS DECLARATION
/**
* Transaction status container interface. Transaction
* status contains errors from presence transaction
* with the network SAP.
*
* Transaction error might be something like
* partial failure when adding contacts to
* contacts lists or it might be OOM error coming
* from initiating or handling the transaction.
*
* @since 3.0
*/
class MPEngTransactionStatus2
{
public: // New functions
/**
* Transaction result status.
*
* If transaction went ok, without any
* errors, status is KErrNone.
*
* If error code is something else than
* KErrNone, there might be detailed
* result entry giving the more detailed
* information from the error.
*
* @since 3.0
* @return The error code.
*/
virtual TInt Status() const = 0;
/**
* Getter to transaction detailed result count.
*
* If transaction was partially successful, there will
* be one or more detailed results, which describe what went
* wrong in transaction. If the transaction was succesful,
* there isn't any detailed results.
*
* Detailed results are presented by MPEngDetailedResultEntry2.
*
* @since 3.0
* @return The detailed result count.
*/
virtual TInt DetailedResultCount() const = 0;
/**
* Getter for detailed result object.
*
* Gets a detailed result entry. Client may not assume anything
* about the ordering of returned detailed entries.
*
* @since 3.0
* @param aIndex Defines which detailed result element to access
* within the transaction status. The index is relative to
* zero. Zero implies the first detailed result entry.
* If passed index is out of bounds, panics with
* "PEngTransStat", 1.
*
* @return Asked detailed result. Lifetime of returned detailed
* result entry is same as originating MPEngTransactionStatus2 object.
* No ownership transfered.
*/
virtual const MPEngDetailedResultEntry2& DetailedResult( TInt aIndex ) const = 0;
/**
* Getter for detailed result object.
*
* Gets a pointer to "first" detailed result entry of asked operation ID.
* If there isn't any detailed result of asked operation, returns
* KErrNotFound. Else returns KErrNone.
* Subsequent detailed results can be obtained by calling
* GetNextDetailedResultByOperation().
*
* @since 3.0
* @param aTransactionOperation By which transaction operation type
* to get detailed entries. Transaction operation IDs are listed in
* PEngPresenceEngineConsts2.h. TPEngTransactionOperation enumeration
* defines transaction IDs for presence data transactions.
* TPEngNWSessionSlotOperations enumeration defines IDs for NWSessionSlot
* operations.
*
* @param aDetailedResult Pointer to first found detailed result entry
* of asked operation type is returned here. Lifetime of
* returned detailed result entry is same as originating
* MPEngTransactionStatus2 object. If no detailed result of asked
* operation isn't found, NULL is returned. No ownership transfered.
*
* @return Status of getting the detailed result. KErrNone if a
* detailed result of the asked operation is found. Else KErrNotFound.
*/
virtual TInt GetFirstDetailedResultByOperation( TInt aTransactionOperation,
const MPEngDetailedResultEntry2*& aDetailedResult ) = 0;
/**
* Getter for detailed result object.
*
* Gets a pointer to "next" detailed result entry
* of asked operation. (Operation criteria is set by calling
* first GetFirstDetailedResultByOperation(). Once setted operation
* criteria stays in use untill new criteria is set by
* GetFirstDetailedResultByOperation().)
*
* If there isn't any more detailed results of required operation,
* returns KErrNotFound. Else returns KErrNone.
*
* If operation criteria hasn't been set previously, panics with
* "PEngTransStat", 2.
*
* @since 3.0
* @param aDetailedResult Pointer to next found detailed result entry
* of asked operation is returned here. Lifetime of returned detailed
* result entry is same as originating MPEngTransactionStatus2 object.
* If no more detailed results of asked operation isn't found,
* NULL is returned.
*
* @return Status of getting the detailed result. KErrNone if a
* detailed result of the asked operation is found. Else KErrNotFound.
*/
virtual TInt GetNextDetailedResultByOperation( const MPEngDetailedResultEntry2*& aDetailedResult ) = 0;
public: // Access to description fields
/**
* Gets descriptive text from transaction status.
* If requested description text isn't set, returns
* KErrNotFound, else returns KErrNone and aDescriptionText
* is set to point description value.
*
* @since 3.0
* @param aDescriptionText On the return contains requested
* description text. If requested text isn't set, contains on
* the return empty descriptor.
* @param aDescriptionID Which description text to get.
* @return If description isn't set KErrNotFound.
* Else KErrNone.
*/
virtual TInt GetDesc( TPtrC& aDescriptionText,
TPEngTransStatusDescriptionText2 aDescriptionID ) const = 0;
/**
* Gets descriptive integer value from transaction status.
* If requested description integer isn't set, returns
* KErrNotFound, else returns KErrNone and aDescriptionInt
* is set to contain description value.
*
* @since 3.0
* @param aDescriptionInt On the return contains requested
* description integer. If requested integer isn't set,
* contains on the return 0.
* @param aDescriptionID Which description integer to get.
* @return If description isn't set KErrNotFound.
* Else KErrNone.
*/
virtual TInt GetInt( TUint32& aDescriptionInt,
TPEngTransStatusDescriptionInteger2 aDescriptionID ) const = 0;
public: // Cloning support
/**
* Creates a new deep copy from transaction status object.
*
* Creates a deep copy from transaction status object and
* returns it ownership to client. Created object is placed
* on the CleanupStack.
*
* Created copy is derived from MPEngTransactionStatus2Copy
* interface to allow client to delete created object.
*
* Only data is copied. Cached settings like criterias
* used by GetFirstDetailedResultByOperation() and
* GetNextDetailedResultByOperation() are not copied.
*
* @since 3.0
* @return New copy from MPEngTransactionStatus2.
* Ownership of created object is returned to calling client.
*/
virtual MPEngTransactionStatusCopy2* CloneLC() const = 0;
/**
* Transaction status extension interface.
*
* @since 3.0
* @return Transaction status extension.
* Currently NULL.
*/
virtual MPEngTransactionStatusExtension2* StatusExtension() = 0;
protected:
/**
* Virtual inline destructor.
*
* Concrete transaction status can't be
* destroyed using this interface.
*/
virtual ~MPEngTransactionStatus2() {};
};
/**
* This interface offers possibility to client to
* control cloned transaction status object lifetime.
*
* @since 3.0
*/
class MPEngTransactionStatusCopy2 : public MPEngTransactionStatus2
{
public:
/**
* Cleanup support.
*
* Cloned transaction status objects can be
* pushed on the CleanupStack using
* CleanupClosePushL().
*
* @since 3.0
*/
virtual void Close() = 0;
public:
/**
* Virtual destructor.
*
* Transaction status copies can be destroyed
* using this interface.
*/
virtual ~MPEngTransactionStatusCopy2() {};
};
#endif // __MPENGTRANSACTIONSTATUS2_H__
// End of File