--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/pressrv_plat/presence_list_api/inc/crlsxdm.h Tue Feb 02 01:05:17 2010 +0200
@@ -0,0 +1,559 @@
+/*
+* 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: RLS and Presence XDM, This is class for RLS XDM
+*
+*/
+
+
+
+#ifndef __RLSXDM_H__
+#define __RLSXDM_H__
+
+// INCLUDE FILES
+#include <e32base.h>
+#include <badesca.h>
+#include <rlspresxdmconsts.h>
+
+// Forward declarations
+class CXdmProtocolInfo;
+class CXdmEngine;
+class CXdmDocument;
+class MRLSPresXDMAsyncHandler;
+class CXdmDocumentNode;
+
+
+// Class declaration
+/**
+* This class is used for RLS XDM. Refer to OMA 'Resource List Server (RLS) XDM
+* Specification'. The class maintains a so called current path information,
+* which can be manipulated using specific functions. The elements adding,
+* removing, getting etc are performed on current path. However, 'service'
+* uri nodes related functions are always treated on document root. The class
+* also applies restrictions on adding elements on certain paths, to comply with
+* OMA specifications. Some servers does not allow empty 'list' or 'service' uri
+* nodes, the class provides functions to delete those from the whole document.
+*
+* @lib rlspresxdm.lib
+* @since S60 3.2
+*/
+class CRLSXDM : public CActive
+ {
+ public:
+
+ /**
+ * Creates CRLSXDM
+ *
+ * @param TInt XDMSettingsList ID
+ * @return Pointer to created CRLSXDM
+ */
+ IMPORT_C static CRLSXDM* NewL( const TInt aSettingId );
+
+ /**
+ * Create CRLSXDM, leaves pointer to stack
+ *
+ * @param TInt XDMSettingsList ID
+ * @return Pointer to created CRLSXDM
+ */
+ IMPORT_C static CRLSXDM* NewLC( const TInt aSettingId );
+
+
+ /**
+ * Updates information (document) to server. This results in
+ * HandleRLSUpdateToServerL on completion.
+ *
+ * @param aHandler, pointer to MRLSPresXDMAsyncHandler callback handler
+ * @return Error code, KErrAlreadyExist if some async already going on
+ */
+ IMPORT_C TInt UpdateToServerL(MRLSPresXDMAsyncHandler* const aHandler);
+
+ /**
+ * Updates all information (document) from server. This results in
+ * HandleRLSUpdateFromServerL on completion.
+ *
+ * @param aHandler, pointer to MRLSPresXDMAsyncHandler callback handler
+ * @return Error code, KErrAlreadyExist if some async already going on
+ */
+ IMPORT_C TInt UpdateAllFromServerL(MRLSPresXDMAsyncHandler* const aHandler);
+
+
+ /**
+ * Cancels document update to/from server if going on. This results in
+ * HandleRLSUpdateCancelL on completion.
+ */
+ IMPORT_C void CancelUpdateL();
+
+ // Service URIs, will always be treated at the root level
+
+ /**
+ * Delete all data by deleting all service uris. It also resets the path.
+ */
+ IMPORT_C void DeleteAll();
+
+ /**
+ * Add a new service URI
+ *
+ * @param TDesC& aServiceURI
+ * @return Error code, KErrNone, KErrAlreadyExist
+ */
+ IMPORT_C TInt AddServiceURIL(const TDesC& aServiceURI);
+
+ /**
+ * Removes a service URI (and all lists/Entries it holds). Current path
+ * will be reset if this service exists in current path
+ *
+ * @param TDesC& aServiceURI to be removed
+ * @return Error code, KErrNone or KErrNotFound
+ */
+ IMPORT_C TInt RemoveServiceURIL(const TDesC& aServiceURI);
+
+ /**
+ * Return ETrue if service URI is exist with given name
+ *
+ * @param TDesC& aServiceURI to be searched
+ * @return ETrue if found
+ */
+ IMPORT_C TBool IsExistServiceURI(const TDesC& aServiceURI);
+
+ /**
+ * Get all Service Uri(s) in current document
+ *
+ * @param CDesCArray& array of Service Uri in current document
+ */
+ IMPORT_C void GetServiceUrisL(CDesCArray& aServiceUris);
+
+ /**
+ * Deletes all service-uris in the document which doesnt have any lists.
+ * This function is very useful with the servers which doesnt accept
+ * empty service uris. Note that as a side effect of this call, the path
+ * information is deleted. If emtpy lists also needed to be deleted,
+ * DeleteAllEmptyListsL must be called before calling this function.
+ */
+ IMPORT_C void DeleteAllEmptyServiceUrisL();
+
+
+ // Methods that apply to current path
+
+ /**
+ * Renames a 'list' element
+ *
+ * @param TDesC& aListName list's current name
+ * @param TDesC& aListNewName list's new name
+ * @return Error code, KErrNone or KErrNotFound
+ */
+ IMPORT_C TInt RenameListL(const TDesC& aListName, const TDesC& aListNewName);
+
+ /**
+ * Async. function. Deletes all lists in the document which doesnt have
+ * any lists or entries.
+ * This function is very useful with the servers which doesnt accept
+ * empty lists. Note that as a side effect of this call, the path
+ * information is deleted. Results in HandleRLSDeleteAllEmptyListsL upon
+ * completion. If empty service-uris also needed to be deleted,
+ * DeleteAllEmptyServiceUrisL must be called after calling this function.
+ *
+ * @param TInt KErrAlreadyExist if some async call already exist
+ */
+ IMPORT_C TInt DeleteAllEmptyLists(MRLSPresXDMAsyncHandler* const aHandler);
+
+ /**
+ * Adds an element to current path, only 'list' and 'resource-list'
+ * elements can be added to the root of ServiceURI, to add any of other
+ * elements current path should be inside an existing list. aDisplayName
+ * is optional and KNullDesC can be provided if display name is not desired.
+ * Note that leaf element type can not have display-name so in that case
+ * display-name is always discarded.
+ *
+ * @param aElementType, an element type to be added, this can be list,
+ * resource-list, entry, external, entry ref. Use constants from
+ * RLSPresXDMConsts.h.
+ * @param aData name in case of list, value of element's attribute for
+ * other elements. In case of resource-list this is the link.
+ * @param aDisplayName display name of the element, use KNullDesC if
+ * display-name is not required.
+ * @return Error code, KErrNone, KErrAlreadyExist or KErrPermissionDenied
+ */
+ IMPORT_C TInt AddElementL(const TDesC& aElementType,
+ const TDesC& aData, const TDesC& aDisplayName);
+
+ /**
+ * Gets display name of an element. Only applicable to those elements
+ * which can have a display name.
+ *
+ * @param aElementType, this can be list, entry, external and entry ref.
+ * Use constants from RLSPresXDMConsts.h.
+ * @param aData name in case of list, value of element's attribute for
+ * other elements.
+ * @param aDisplayName display name of the element
+ * @return Error code. KErrArgument, KErrNone, KErrNotFound
+ * or KErrPermissionDenied
+ */
+ IMPORT_C TInt GetDisplayName(const TDesC& aElementType,
+ const TDesC& aData, TPtrC8& aDisplayName);
+
+ /**
+ * Updates display name of an element.
+ *
+ * @param aElementType, an element type, this can be list,
+ * entry, external, entry ref. Use constants from RLSPresXDMConsts.h.
+ * @param aData name in case of list, value of element's attribute for
+ * other elements.
+ * @param aDisplayName display name of the element
+ * @return Error code. KErrArgument, KErrNone, KErrNotFound
+ * or KErrPermissionDenied
+ */
+ IMPORT_C TInt UpdateDisplayNameL(const TDesC& aElementType,
+ const TDesC& aData, const TDesC& aDisplayName);
+
+ /**
+ * Get all elements of same type at given node path
+ *
+ * @param aElementType, an element type, this can be list, resource-list
+ * entry, external, or entry ref. Use constants from RLSPresXDMConsts.h.
+ * @param aValues array of data values. 'name' in case of list or value of
+ * element's attribute for other element types.
+ */
+ IMPORT_C void GetElementsL(const TDesC& aElementType, CDesCArray& aValues);
+
+ /**
+ * Removes the given element from the current path
+ *
+ * @param aElementType, an element type, this can be list, resource-list
+ * entry, external, or entry ref. Use constants from RLSPresXDMConsts.h.
+ * @param aData name in case of list, value of element's attribute for
+ * other elements.
+ * @return Error code. KErrArgument, KErrNone, KErrNotFound
+ * or KErrPermissionDenied
+ */
+ IMPORT_C TInt RemoveElementL(const TDesC& aElementType, const TDesC& aData);
+
+ /**
+ * Is element exist on the current path
+ *
+ * @param aElementType, an element type, this can be list, resource-list
+ * entry, external, or entry ref. Use constants from RLSPresXDMConsts.h.
+ * @param aData name in case of list, value of element's attribute for
+ * other elements.
+ * @return ETrue if element exist.
+ */
+ IMPORT_C TBool IsElementExist(const TDesC& aElementType, const TDesC& aData);
+
+
+ // Methods related to changing the current path
+
+ /**
+ * Switch into given service URI. After this the given ServiceURI
+ * will become currently pointed URI, and all operations will be
+ * performed on this URI. This corresponds to entering into a disk
+ * in DOS
+ *
+ * @param TDesC& name of the ServiceURI
+ * @return Error code, KErrNone or KErrNotFound
+ */
+ IMPORT_C TInt SwitchToServiceURIL(const TDesC& aServiceURI);
+
+ /**
+ * Switch into given list. After this the given list will become
+ * currently pointed list (path), and all operations will be performed
+ * in this path. This corresponds to entering into a directory in DOS
+ *
+ * @param TDesC& name of the list
+ * @return Error code, KErrNone or KErrNotFound
+ */
+ IMPORT_C TInt SwitchToListL(const TDesC& aListName);
+
+ /**
+ * Switch out from current list, if path is already service-uri level
+ * nothing will happed. This corresponds to gettting out from a directory.
+ * The Current path changes if successful
+ */
+ IMPORT_C void SwitchOutFromList();
+
+ /**
+ * This gives complete hierarchy of the current path. The first element
+ * of the array will be ServiceURI, and after that will be child lists,
+ * The current list name is the last element of the array.
+ *
+ * @param CDesC16Array& array of service-uri and list names ordered from
+ * root to the list's own name.
+ */
+ IMPORT_C void GetCurrentPathL(CDesCArray& aPath);
+
+ /**
+ * Set the current path according to given hierarchy. The first element
+ * of the array must be the ServiceURI, with child lists to follow.
+ * The target list name is the last element of the array.
+ * If the list is not found according to the given heirarchy, the current
+ * path will not be changed and KErrNotFound will be returned. An empty
+ * array will cause the path to be completely empty.
+ *
+ * @param MDesCArray& array of service-uri and list names ordered from
+ * root to the list's own name.
+ * @return Error code, KErrNone or KErrNotFound
+ */
+ IMPORT_C TInt SetCurrentpathL(const MDesCArray& aListsNames);
+
+ /**
+ * Accessor for the last negotiated RLS service URI.
+ * URI is Zero length if the last HTTP PUT did not
+ * receive HTTP 409 error or if there was no <alt-value> value
+ * in the response body.
+ *
+ * @return last negotiated RLS service URI.
+ *
+ */
+ IMPORT_C TPtrC NegotiatedServiceUri();
+
+ /**
+ * Destructor
+ *
+ */
+ ~CRLSXDM();
+
+ private:
+
+ /**
+ * Second phase constructor
+ *
+ * @param TInt XDMSettingsList ID
+ * @return none
+ */
+ void ConstructL(const TInt aSettingId );
+
+ /**
+ * C++ constructor
+ *
+ * @param none
+ * @return none
+ */
+ CRLSXDM();
+
+
+ /**
+ * Return pointer to serviceUri and its attribute value
+ *
+ * @param CXdmNodeAttribute attribute value of serviceUri
+ * @param CXdmDocumentNode pointer to root node
+ * @return CXdmDocumentNode* if found, otherwise NULL
+ */
+ CXdmDocumentNode* IsServiceUriExist(const TDesC& aUriAttr,
+ CXdmDocumentNode* aRootNode);
+
+ /**
+ * Get list's non-leaf child. These includes getting of list, entry
+ * external and entry ref.
+ *
+ * @param aChildName, name of non-leaf child
+ * @param aAttrValue value of attribute to match with
+ * @param aTargetNode pointer to target node
+ * @return CXdmDocumentNode* if found, otherwise NULL
+ */
+ CXdmDocumentNode* GetNonLeafChild(const TDesC& aChildName,
+ const TDesC& aAttrValue,
+ CXdmDocumentNode* const aTargetNode);
+
+ /**
+ * Get list's leaf child. These includes getting of resource-list and
+ * packages
+ *
+ * @param aChildName, name of non-leaf child
+ * @param aValue value to match with
+ * @param aTargetNode pointer to target node
+ * @return CXdmDocumentNode* if found, otherwise NULL
+ */
+ CXdmDocumentNode* GetLeafChild(const TDesC& aChildName,
+ const TDesC& aValue, CXdmDocumentNode* const aTargetNode);
+
+ /**
+ * Return the attribute name used for the element.
+ * Only valid for non-leaf elements.
+ *
+ * @param aElementName, name of non-leaf element
+ * @param aAttrName name of the attribute returns here
+ */
+ void GetNonLeafElementAttrName(const TDesC& aElementName,
+ TDes& aAttrName);
+
+ /**
+ * Validates the given non-leaf element.
+ *
+ * @param aElementName, name of non-leaf element
+ * @return ETrue if valid non-leaf element
+ */
+ TBool IsNonLeafElementValid(const TDesC& aElementName);
+
+
+ /**
+ * Adds a non leaf element to current path, only 'list' element can be
+ * added to the root of ServiceURI, to add any of other possible elements
+ * current path should be inside an existing list. This functions doesnt
+ * care whether element already exist or not.
+ *
+ * @param aElementType, an element type to be added, this can be list,
+ * entry, external, entry ref. Use constants from RLSPresXDMConsts.h.
+ * @param aData name in case of list, value of element's attribute for
+ * other elements.
+ * @param aDisplayName display name of the element
+ * @param aTargetNode pointer to target node
+ */
+ void AddNonLeafElementL(const TDesC& aElementType,
+ const TDesC& aData, const TDesC& aDisplayName,
+ CXdmDocumentNode* const aTargetNode);
+
+ /**
+ * Adds a leaf element to current path, only 'resource-list' element can be
+ * added to the root of ServiceURI. This functions doesnt care whether
+ * element already exist or not.
+ *
+ * @param aElementType, an element type to be added, currently this can be
+ * only resource-list. Use constants from RLSPresXDMConsts.h.
+ * @param aData value of the element
+ * @param aTargetNode pointer to target node
+ */
+ void AddLeafElementL(const TDesC& aElementType, const TDesC& aData,
+ CXdmDocumentNode* const aTargetNode);
+
+ /**
+ * Gets display name of a non leaf element.
+ *
+ * @param aElementType, an element type, this can be list,
+ * entry, external, entry ref. Use constants from RLSPresXDMConsts.h.
+ * @param aData name in case of list, value of element's attribute for
+ * other elements.
+ * @param aDisplayName display name of the element
+ * @param aTargetNode pointer to target node
+ * @return Error code. KErrArgument, KErrNone, KErrAlreadyExist
+ * or KErrPermissionDenied
+ */
+ TInt GetDisplayNameInt(const TDesC& aElementType,
+ const TDesC& aData, TPtrC8& aDisplayName,
+ CXdmDocumentNode* const aTargetNode);
+
+ /**
+ * Updates display name of an element.
+ *
+ * @param aElementType, an element type, this can be list,
+ * entry, external, entry ref. Use constants from RLSPresXDMConsts.h.
+ * @param aData name in case of list, value of element's attribute for
+ * other elements.
+ * @param aDisplayName display name of the element
+ * @param aTargetNode pointer to target node
+ * @return Error code. KErrArgument, KErrNone, KErrAlreadyExist
+ * or KErrPermissionDenied
+ */
+ TInt UpdateDisplayNameIntL(const TDesC& aElementType,
+ const TDesC& aData, const TDesC& aDisplayName,
+ CXdmDocumentNode* const aTargetNode);
+
+ /**
+ * Get all elements of same type at given node path
+ *
+ * @param aElementType, an element type, this can be list,
+ * entry, external, or entry ref. Use constants from
+ * RLSPresXDMConsts.h.
+ * @param aValues array of data values. 'name' in case of list or value of
+ * element's attribute for other element types.
+ * @param aTargetNode pointer to target node
+ */
+ void GetNonLeafElementsL(const TDesC& aElementType,
+ CDesCArray& aValues, CXdmDocumentNode* const aTargetNode);
+
+ /**
+ * Get all elements of same type at given node path
+ *
+ * @param aElementType, this can be resource-list
+ * @param aValues array of data values. 'name' in case of list or value of
+ * element's attribute for other element types.
+ * @param aTargetNode pointer to target node
+ * @return none
+ */
+ void GetLeafElementsL(const TDesC& aElementType, CDesCArray& aValues,
+ CXdmDocumentNode* const aTargetNode);
+
+ /**
+ * Internal function for deleting empty lists, keep called by RunL
+ * until all lists are deleted.
+ */
+ void DeleteEmptyListsL();
+
+ /**
+ * Adds the compulsory package node to current service uri
+ * in case no current uri found, does nothing. This function needed
+ * because some servers wants package as the last child node of
+ * service uri node.
+ */
+ void AddPackageL();
+
+ /**
+ * Removes the compulsory package node to current service uri
+ * in case no current uri found, does nothing. This function needed
+ * because some servers wants package as the last child node of
+ * service uri node.
+ */
+ void RemovePackageL();
+
+ /**
+ * Creates the document root if needed
+ */
+ void CreateRootIfNeededL();
+
+ /**
+ * Parse Serice URI negotiation response body and save it into
+ * iNegotiatedServiceUri.
+ * @param aErrorBody HTTP 409 error body
+ */
+ void DoParseNegotiatedServiceUriL( CXdmDocumentNode* aErrorBody );
+
+
+ /**
+ * From CActive
+ *
+ */
+ void DoCancel();
+
+ /**
+ * From CActive
+ *
+ */
+ void RunL();
+
+ /**
+ * From CActive
+ *
+ */
+ TInt RunError(TInt aError);
+
+ private: // Data
+
+ CXdmProtocolInfo* iXDMProtocolInfo;
+ CXdmEngine* iXDMEngine;
+ CXdmDocument* iRLSDocument;
+
+ TInt iAsyncReq;
+ MRLSPresXDMAsyncHandler* iAsyncHandler;
+
+ CDesCArray* iListPath;
+ RPointerArray<CXdmDocumentNode> iListPointerPath;
+
+ /**
+ * Negotiated RLS service URI
+ * Own
+ */
+ HBufC* iNegotiatedServiceUri;
+
+
+ };
+
+#endif //__RLSXDM_H__
+
+