diff -r 000000000000 -r 094583676ce7 inc/MPEngTransactionStatus2.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/inc/MPEngTransactionStatus2.h Thu Dec 17 08:41:52 2009 +0200 @@ -0,0 +1,461 @@ +/* +* 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 + + +//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 + +