diff -r 000000000000 -r c8caa15ef882 pressrv_plat/xdm_api/inc/XdmDocument.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/pressrv_plat/xdm_api/inc/XdmDocument.h Tue Feb 02 01:05:17 2010 +0200 @@ -0,0 +1,538 @@ +/* +* Copyright (c) 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: XDM Document +* +*/ + + + + +#ifndef __XDMDOCUMENT__ +#define __XDMDOCUMENT__ + +#include +#include +#include + +//The supported document types = application usages +enum TXdmDocType + { + EXdmDocGeneral = 0, + EXdmTestDocType, + EXdmPoCGroup, + EXdmPoCUserAccessPolicy, + EXdmDirectory, + EXdmCapabilities, + EXdmSharedXdm, + EXdmRlsServices, + EXdmResourceLists, + EXdmIetfCommonPolicy, + EXdmOmaCommonPolicy, + EXdmIetfPresenceRules, + EXdmOmaPresenceRules, + EXdmPresContent, + EXdmPresContentNSN + }; + +//Helper class for searching documents; 16-bit +struct SXdmAttribute16 + { + TPtrC iName; + TPtrC iValue; + }; + +//Helper class for searching documents; 8-bit +struct SXdmAttribute8 + { + TPtrC8 iName; + TPtrC8 iValue; + }; + +//Constants +const TInt KXdmPathSeparatorChar = 47; + +//Forward declarations +class CXdmEngine; +class MXdmOperation; +class CXdmDocumentNode; +class CXdmNodeAttribute; +class CXdmOperationFactory; + +// CLASS DECLARATION +class CXdmDocument : public CActive, + public MXdmNamespaceContainer + { + public: // Constructors and destructor + + /** + * Returns the name of this document + * @return TPtrC The name of the document this object models + */ + IMPORT_C TPtrC Name() const; + + /** + * Fetch data from the document this object models beginning from the + * element the parameter points to. If the parameter is not specified, + * the operation applies to the whole of the document. + * + * @param CXdmDocumentNode* The element (including its descendants) to fetch. + * @return void + */ + IMPORT_C void FetchDataL( CXdmDocumentNode* aDocNode = NULL ); + + /** + * Replace the document this object models + * + * NOTE: The name of the document MUST remain the same. This is because + * the operation first needs to delete the old document and then + * store the new one. The risk of creating conflicting document + * names is far too great in case this rule is not imposed. + * + * @return void + */ + IMPORT_C void ReplaceL(); + + /** + * Replace a named element in the document this object models + * + * NOTE: Both elements MUST have a common parent element, + * which, in effect, must be the element this document + * model points to. Also note that the operation will + * fail in case the "aOldNode" does not exist in the document. + * + * @param CXdmDocumentNode* The element to replace + * @param CXdmDocumentNode* The replacing element + * @return void + */ + IMPORT_C void ReplaceL( CXdmDocumentNode* aOldNode, + CXdmDocumentNode* aNewNode ); + + /** + * Insert the node identified by the parameter. Note that this + * method cannot be applied to complete documents. Thus the method + * will fail in case the parameter is NULL. If the client needs + * to a) add b) replace a document, it needs to do this through + * the AppendL() or the ReplaceL() method. + * + * NOTE: The operation will fail in case the element identified + * by the aDocNode parameter already exists in the document. + * XDM Engine does not make assumptions in this regard; it + * does not, for instance, change some aspects of the + * request in order to turn it into a valid insert operation. + * Instead, it will re-read the whole document and retry the + * insert operation. If the operation still fails, the engine + * reports the failure that occurred while performing the + * operation. In the latter case, the client can get a hold + * of the error report document, provided that the used + * protocol supports the feature and that the server included + * the document in the response, by fetching the root node of + * the error document through ErrorRoot() method. + * + * @param CXdmDocumentNode* The element (including its descendants) to insert + * @return void + */ + IMPORT_C void InsertL( CXdmDocumentNode* aDocNode ); + + /** + * Append data to the document this object models beginning from the + * element the parameter points to. If the parameter is not specified, + * the operation applies to the whole of the document. + * + * NOTE: This is a "blind insert"; no guarantees can be given + * as to the success or failure of the operation, since + * it includes no checking for existence of the resource + * that is to be appended/inserted. It is also worth noticing + * that this method may effectively turn into a replace + * operation in case the method is invoked on a document that + * already exists in the storage endpoint. + * + * @param CXdmDocumentNode* The element (including its descendants) to append. + * @return void + */ + IMPORT_C void AppendL( CXdmDocumentNode* aDocNode = NULL ); + + /** + * Delete data from the document this object models beginning from the + * element the parameter points to. If the parameter is not specified, + * the operation applies to the whole of the document. + * + * @param CXdmDocumentNode* The element (including its descendants) to delete. + * @return void + */ + IMPORT_C void DeleteDataL( CXdmDocumentNode* aDocNode = NULL ); + + /** + * Search for nodes which match the specified name & attributes + * + * @param CXdmDocumentNode& The node to search for + * @param RPointerArray& On completion, contains the nodes + * that were found, if any. + * @return TInt KErrNotFound if no matching nodes are found. + * Otherwise indicates the number of nodes found + */ + IMPORT_C TInt Find( const CXdmDocumentNode& aTargetNode, + RPointerArray& aResultArray ) const; + + /** + * Search for nodes which match the specified name & attributes + * + * @param TDesC& The name of the node to search for + * @param RPointerArray& On completion, contains the nodes + * that were found, if any. + * @return TInt KErrNotFound if no matching nodes are found. + * Otherwise indicates the number of nodes found + */ + IMPORT_C TInt Find( const TDesC& aNodeName, + RPointerArray& aResultArray ) const; + + /** + * Search for attributes which match the specified name + * + * @param TDesC& The name of the attribute to search for + * @param RPointerArray& On completion, contains the nodes + * that were found, if any. + * @return TInt KErrNotFound if no matching nodes are found. + * Otherwise indicates the number of nodes found + */ + IMPORT_C TInt Find( const TDesC& aAttributeName, + RPointerArray& aResultArray ) const; + + /** + * Search for nodes which match the specified name & attributes + * + * @param TDesC& The name of the node to search for + * @param RPointerArray& On completion, contains the nodes + * that were found, if any. + * @param RPointerArray& The attribute names & values that a + matching node must have. + * @return TInt KErrNotFound if no matching nodes are found. + * Otherwise indicates the number of nodes found + */ + IMPORT_C TInt Find( const TDesC& aNodeName, + RPointerArray& aResultArray, + const RPointerArray& aAttributeArray ) const; + + /** + * Comparison operator + * + * @param CXdmDocument& The document to compare to + * @return TBool Are the contents of the two identical + */ + IMPORT_C TBool operator==( CXdmDocument& aDocument ) const; + + /** + * Remove an element from the document model + * + * NOTE: This method cannot be used with document models that + * only target a fragment of the document; in practise + * this means that if the client has constructed a node + * using DocumentSubsetL(), this method leaves with KErrGeneral. + * A document subset cannot be treated as an actual document + * since only a fraction of the elements and their dependencies + * in the document is known. The client must have the whole + * document at its disposal in order to be properly able to + * make use of this method. + * + * @param CXdmDocumentNode* The node to be removed + * @return void + */ + IMPORT_C void RemoveFromModelL( CXdmDocumentNode* aChileNode ); + + /** + * Append an element to the document model + * + * NOTE: This method cannot be used with document models that + * only target a fragment of the document; in practise + * this means that if the client has constructed a node + * using DocumentSubsetL(), this method leaves with KErrGeneral. + * A document subset cannot be treated as an actual document + * since only a fraction of the elements and their dependencies + * in the document is known. The client must have the whole + * document at its disposal in order to be properly able to + * make use of this method. + * + * @param The next node in the list + * @return void + */ + IMPORT_C void AppendToModelL( CXdmDocumentNode* aNewNode, + CXdmDocumentNode* aParentNode ); + + /** + * Replace an element in the document model + * + * NOTE: This method cannot be used with document models that + * only target a fragment of the document; in practise + * this means that if the client has constructed a node + * using DocumentSubsetL(), this method leaves with KErrGeneral. + * A document subset cannot be treated as an actual document + * since only a fraction of the elements and their dependencies + * in the document is known. The client must have the whole + * document at its disposal in order to be properly able to + * make use of this method. + * + * @param CXdmDocumentNode The new node + * @param CXdmDocumentNode The old (target) node + * @return void + */ + IMPORT_C void ReplaceInModelL( CXdmDocumentNode* aNewNode, + CXdmDocumentNode* aTargetNode ); + + /** + * Return a subset of the document this object models. + * For instance, if the whole (physical) document is + * the following: + * + * + * + * + * Foo + * + * + * + * + * calling this method with the parameter "root/element1/child1" + * would make this document model model the subset + * + * + * Foo + * + * + * It is important to understand that, after calling this method, + * the document model only models the document starting from the + * node the method returns. The client may traverse the document + * all the way to the root node and back, but the way from the root + * node to the node this method returns should be regarded merely + * as a "path" of elements that has no real content. + * + * A prime use case for this method is one in which the structure + * of the document the client application wants to operate on is + * well-known; a typical example would be an XDM directory document. + * The schema for this application usage is very simple: the root + * element is that has a collection of + * elements as its children. Each element has a mandatory + * "auid" parameter that identifies the type of documents that + * particular folder contains. Therefore, a client application has + * all the necessary information it needs to have in order to be + * able to carry out a fetch for a document subset (one folder): + * + * _LIT( KNodePath, "xcap-directory/folder" ); + * CXdmDocumentNode* node = iDirectoryDoc->DocumentSubsetL( KNodePath ); + * CleanupStack::PushL( node ); + * CXdmNodeAttribute* auid = node->CreateAttributeL( _L( "auid" ) ); + * CleanupStack::PushL( auid ); + * auid->SetAttributeValueL( _L( "My document type" ) ); + * iDirectoryDoc->FetchDataL( node ); + * CleanupStack::Pop( 2 ); //auid, node + * + * In this particular case, even after the fetch operation is + * complete, the element in this document model + * would not be a real element, a genuine part of the document, but, + * rather, a "virtual" node on the way to the element that is of + * real interest to the client application. + * + * Also note that the instance of CXdmDocument on which this subset + * has been created, cannot be used as a container for a whole + * document until ResetSubset() has been called. + * + * The incoming parameter MUST separate each step to the + * target element with a slash character ('/'). + * + * @param TDesC8& The path to the target element + * @return CXdmDocumentNode* + */ + IMPORT_C CXdmDocumentNode* DocumentSubsetL( const TDesC& aNodePath ); + + /* + * Reset the document subset. + * + * See the comments to DocumentSubsetL method for details. + * @return void + */ + IMPORT_C virtual void ResetSubset(); + + /** + * Destructor. + */ + IMPORT_C ~CXdmDocument(); + + public: // New functions + + /** + * Return the type of this document + * + * @return TXdmDocType The type of the document + */ + virtual TXdmDocType DocumentType() const = 0; + + /** + * Construct an "anonymous" entry point for this document. + * This node effectively becomes the root of this document. + * + * @return CXdmDocumentNode* Document root + */ + virtual CXdmDocumentNode* CreateRootL() = 0; + + /** + * Return the root element of this document + * + * NOTE: The returning node may or may not contain any data, + * since, in the case that this document model does not + * have content yet, the element is a simple "entry point" + * to the whole document. Thus, for instance, if the client + * application requests the XDM Engine to fetch a particular + * document, the root element points to nothing until the + * request has been completed. + * + * Also note that in case the client has created a document + * subset using the DocumentSubsetL() method, this method + * will return NULL, since the document is not traversable + * from the root; it, by definition, represents only a subset + * of this document. In case of a document subset, the path from + * the root node to the target node should be considered a simple + * linked list that does not necessarily contain all children + * for any of the nodes in between. + * + * @return CXdmDocumentNode* The root element of the document + */ + virtual CXdmDocumentNode* DocumentRoot() const = 0; + + /* + * Reset the contents of this document model. + * + * This method comes into play when client wants to reuse an instance + * of this class for, for instance, construction of different content. + * Other properties, such as name and the type of the document + * do not change. + * + * @return void + */ + virtual void ResetContents() = 0; + + /** + * Return the currently last node in the path. + * NOTE: Only works with document subsets! + * + * @return CXdmDocumentNode* + */ + virtual CXdmDocumentNode* CurrentExtent() const = 0; + + /** + * Return the time stamp for this document + * + * @return TTime Time stamp + */ + virtual TTime TimeStamp() const = 0; + + /** + * Return an error document for a failed update + * + * NOTE: The returning object will be zero in case + * the used protocol does not support this feature. + * + * @return CXdmDocument* The error document + */ + virtual CXdmDocumentNode* ErrorRoot() = 0; + + protected: + + /** + * Append an element to the path identifying the + * the current document subset + * + * @param TDesC& The path part to append + * @return void + */ + virtual void AppendPathPartL( const TDesC& aString ) = 0; + + private: + + /** + * Empty the operation queue + */ + void EmptyOperationQueue(); + + /** + * Find attributes by name + * + * @param CXdmDocumentNode* The node to search from + * @param TDesC& The name of the attributes to search for + * @param RPointerArray& On completion, contains the results + * @return TInt The number of attributes found + */ + TInt DoFindAttributes( CXdmDocumentNode* aNode, + const TDesC& aAttributeName, + RPointerArray& aResultArray ) const; + + private: //Methods which need to be accessible from the CXdmEngine + //but NOT from the client application => friend class + + /** + * Start updating the document + * @param TRequestStatus& The status of the request + * @return void + */ + virtual void StartUpdateL() = 0; + + /** + * Cancel a document update + * @param TRequestStatus& The status of the request + * @return void + */ + virtual void CancelUpdate() = 0; + + /** + * Save the client's request status + * @param TRequestStatus& The status of the request + * @return void + */ + virtual void SaveClientStatus( TRequestStatus& aClientStatus ) = 0; + + protected: + + /** + * By default Symbian OS constructor is private. + * @return void + */ + IMPORT_C void BaseConstructL( TInt aOperationFactoryUid, + const TDesC& aDocumentName ); + + /** + * By default Symbian OS constructor is private. + * @return void + */ + IMPORT_C void BaseConstructL( TInt aOperationFactoryUid, + const TDesC8& aDocumentName ); + + /** + * C++ constructor is private. + */ + IMPORT_C CXdmDocument( CXdmEngine& aXdmEngine ); + + protected: //Data + + TBool iDocSubset; + HBufC* iDocumentName; + TRequestStatus* iClientStatus; + TTime iTimeStamp; + CXdmEngine& iXdmEngine; + friend class CXdmEngine; + RPointerArray iChangeRequests; + CXdmOperationFactory* iOperationFactory; + + private: // Data + }; + +#endif //__XDMDOCUMENT__ + +// End of File