diff -r 000000000000 -r c8caa15ef882 pressrv_plat/presence_list_api/inc/crlsxdm.h --- /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 +#include +#include + +// 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 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 iListPointerPath; + + /** + * Negotiated RLS service URI + * Own + */ + HBufC* iNegotiatedServiceUri; + + + }; + +#endif //__RLSXDM_H__ + +