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