--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/upnp/upnpstack_plat/upnp_utils_api/inc/upnpdominterface.h Tue Feb 02 01:12:20 2010 +0200
@@ -0,0 +1,413 @@
+/** @file
+* Copyright (c) 2005-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: Declares UpnpDomInterface functions
+*
+*/
+
+
+#ifndef C_UPNPDOMINTERFACE_H
+#define C_UPNPDOMINTERFACE_H
+
+// INCLUDES
+
+#include <e32def.h>
+#include <e32math.h>
+#include <f32file.h>
+#include <s32file.h>
+#include <utf.h>
+#include <xmlengdom.h>
+
+namespace UpnpDomInterface
+ {
+
+ //CONSTANTS
+ _LIT8(KContainer, "container");
+ _LIT8(KSearchable, "searchable");
+ _LIT8(KTrueVal, "1");
+
+ /*
+ * GetAttrValueL
+ * Gets value of the indicated attribut for the given tag.
+ * @Param aElement reference to the Element which attribute's value
+ * should be returned.
+ * @Param aAttribute name of the attribute which value should be returned.
+ * @Return attribute's value or empty descriptor if Element has no such attribute.
+ */
+ IMPORT_C TPtrC8 GetAttrValueL( const TXmlEngElement& aElement,
+ const TDesC8& aAttribute );
+
+ /*
+ * GetElementValueL
+ * Gets value of the indicated element.
+ * @Param aElement reference to the Element which value should be returned.
+ * @Return value or empty descriptor if Element has no content.
+ */
+ IMPORT_C TPtrC8 GetElementValueL( const TXmlEngElement& aElement );
+
+ /*
+ * AllocElementValueL
+ * Gets value of the indicated element and allocs it on heap.
+ * @Param aElement reference to the Element which value should be returned.
+ * @Return pointer to allocated descriptor eith content or NULL if Element has no content.
+ */
+ IMPORT_C HBufC* AllocElementValueL( const TXmlEngElement& aElement );
+
+
+ /*
+ * CheckTagL
+ * Checks if given XML element has given tag.
+ * @Param aElement reference to the Element that is being checked
+ * @Param aTag LocalName of the Element which is being checked
+ * @Return ETrue if element's name is equal to the passed one
+ */
+ IMPORT_C TBool CheckTagL( const TXmlEngElement& aElement,
+ const TDesC8& aTag );
+
+ /*
+ * CheckTagL
+ * Checks if given XML element has given tag and contains given value.
+ * @Param aElement reference to the Element that is being checked
+ * @Param aTag LocalName of the Element which is being checked
+ * @Param aTagValue The value that is checked againts
+ * the contents of the aTag element
+ * @Return ETrue if element meets searching criteria
+ */
+ IMPORT_C TBool CheckTagL( const TXmlEngElement& aElement,
+ const TDesC8& aTag,
+ const TDesC8& aTagValue );
+
+ /*
+ * CheckSubTagL
+ * Checks if the given elements has an element whose
+ * local name is specified by the Tag
+ * @Param aElement reference to the Element that is being checked
+ * @Param aTag LocalName that is being searched for
+ * @Return ETrue if subtag meets search criteria
+ */
+ IMPORT_C TBool CheckSubTagL( const TXmlEngElement& aElement,
+ const TDesC8& aTag );
+
+ /*
+ * CheckSubTagL
+ * Checks the value of the specified SubTag (Element) against
+ * the given value returns ETrue if match found else EFalse
+ * @Param aElement reference to the Element that is being checked
+ * @Param aTag LocalName of the Element which is being checked
+ * @Param aTagValue The value that is checked againts
+ * the contents of the Tag element
+ * @Return ETrue if subtag meets search criteria
+ */
+ IMPORT_C TBool CheckSubTagL( const TXmlEngElement& aElement,
+ const TDesC8& aTag,
+ const TDesC8& aTagValue );
+
+ /*
+ * CheckSubTagPrefixL
+ * Checks the value of the specified SubTag (Element) against
+ * the given value returns ETrue if match found else EFalse
+ * @Param aElement reference to the Element that is being checked
+ * @Param aNameSpacePrefix Specifies the wanted prefix
+ * @Param aTag LocalName of the Element which is being checked
+ * @Param aTagValue The value that is checked againts
+ * the contents of the Tag element
+ * @Return ETrue if subtag meets search criteria
+ */
+ IMPORT_C TBool CheckSubTagPrefixL( const TXmlEngElement& aElement,
+ const TDesC8& aNameSpacePrefix,
+ const TDesC8& aTag,
+ const TDesC8& aTagValue );
+
+ /*
+ * CheckAttributeValueL
+ * Checks the attribute value of the given element against the given value.
+ * @Param aElement reference to the Element being checked
+ * @Param aAttribute The Name of the attribute which is being checked
+ * @Param aValue The value that is checked against the value of the aAttribute
+ * @Return ETrue if attribute meets given criteria
+ */
+ IMPORT_C TBool CheckAttributeValueL( const TXmlEngElement& aElement,
+ const TDesC8& aAttribute,
+ const TDesC8& aValue);
+
+ /*
+ * DeleteElement
+ * Deletes the specified element from the DomTree
+ * @param aElement reference to the Element to be deleted
+ * @return the parent element
+ */
+ IMPORT_C TXmlEngElement DeleteElement(TXmlEngElement& aElement);
+
+ /*
+ * GetElementL
+ * Searches the DomTree for the element specified by the given specifiers.
+ * @param aElement reference to a "Root" element from which the search will start
+ * @param aWanted Specifies the location of the reference
+ * which will be set to point to the wanted Element
+ * @param aMainTag LocalName of the Element that is being searched for
+ * @param aDepth specifies how deep into the tree the search will proceed
+ * (if set to -1 the whole tree will be searched)
+ * @param aCurrentDepth How deep into the tree the search has proceeded
+ * (should be set to 0 when the search is started)
+ * @Return ETrue if element is found
+ */
+ IMPORT_C TBool GetElementL( const TXmlEngElement& aElement,
+ TXmlEngElement& aWanted,
+ const TDesC8& aMainTag,
+ TInt aDepth=-1,
+ TInt aCurrentDepth=0);
+
+ /*
+ * GetElementL
+ * Searches the DomTree for the element specified by the given specifiers.
+ * @param aElement reference to a "Root" element from which the search will start
+ * @param aWanted Specifies the location of the reference
+ * which will be set to point to the wanted Element
+ * @param aMainTag LocalName of the Element that is being searched for
+ * @param aSubTag LocalName of an Element within
+ * the MainElement that is being searched for
+ * @param aDepth specifies how deep into the tree the search will proceed
+ * (if set to -1 the whole tree will be searched)
+ * @param aCurrentDepth How deep into the tree the search has proceeded
+ * (should be set to 0 when the search is started)
+ * @Return ETrue if element is found
+ */
+ IMPORT_C TBool GetElementL( const TXmlEngElement& aElement,
+ TXmlEngElement& aWanted,
+ const TDesC8& aMainTag,
+ const TDesC8& aSubTag,
+ TInt aDepth=-1,
+ TInt aCurrentDepth=0);
+
+ /**
+ * GetElementL
+ * Searches the DomTree for the element specified by the given specifiers.
+ * @param aElement reference to a "Root" element from which the search will start
+ * @param aWanted Specifies the location of the reference
+ * which will be set to point to the wanted Element
+ * @param aMainTag LocalName of the Element that is being searched for
+ * @param aSubTag LocalName of an Element within
+ * the MainElement that is being searched for
+ * @param aSubTagValue Contents of the Element specified by the aSubTag
+ * @param aDepth specifies how deep into the tree the search will proceed
+ * (if set to -1 the whole tree will be searched)
+ * @param aCurrentDepth How deep into the tree the search has proceeded
+ * (should be set to 0 when the search is started)
+ * @Return ETrue if element is found
+ */
+ IMPORT_C TBool GetElementL( const TXmlEngElement& aElement,
+ TXmlEngElement& aWanted,
+ const TDesC8& aMainTag,
+ const TDesC8& aSubTag,
+ const TDesC8& aSubTagValue,
+ TInt aDepth=-1,
+ TInt aCurrentDepth=0);
+
+ /*
+ * GetContentElementL
+ * Searches the DomTree for the element specified by the given specifiers.
+ * @param aElement reference to a "Root" element from which the search will start
+ * @param aWanted Specifies the location of the reference
+ * which will be set to point to the wanted Element
+ * @param aSubTag LocalName of an Element within
+ * the MainElement that is being searched for
+ * @param aSubTagValue Contents of the Element specified by the aSubTag
+ * @param aDepth specifies how deep into the tree the search will proceed
+ * (if set to -1 the whole tree will be searched)
+ * @param aCurrentDepth How deep into the tree the search has proceeded
+ * (should be set to 0 when the search is started)
+ * @Return ETrue if element is found
+ */
+ IMPORT_C TBool GetContentElementL( const TXmlEngElement& aElement,
+ TXmlEngElement& aWanted,
+ const TDesC8& aSubTag,
+ const TDesC8& aSubTagValue,
+ TInt aDepth=-1,
+ TInt aCurrentDepth=0);
+
+ /*
+ * GetDirectoryElementL
+ * Searches the DomTree for the element specified by the given parameters
+ * @param aElement reference to a "Root" element from which the search will start
+ * @param aWanted Specifies the location of the reference
+ * which will be set to point to the wanted Element
+ * @param aMainTag LocalName of the Element that is being searched for
+ * @param aAttribute The name of the Attribute of the MainElement
+ * that is searched for
+ * @param aAttributeValue The wanted value of the Attribute
+ * that is searched for
+ * @param aDepth specifies how deep into the tree the search will proceed
+ * (if set to -1 the whole tree will be searched)
+ * @param aCurrentDepth How deep into the tree the search has proceeded
+ * (should be set to 0 when the search is started)
+ * @Return ETrue if element is found
+ */
+ IMPORT_C TBool GetDirectoryElementL( const TXmlEngElement& aElement,
+ TXmlEngElement& aWanted,
+ const TDesC8& aMainTag,
+ const TDesC8& aAttribute,
+ const TDesC8& aAttributeValue,
+ TInt aDepth=-1,
+ TInt aCurrentDepth=0);
+
+ /*
+ * GetDirectoryElementL
+ * Searches the DomTree for the element specified by the given parameters
+ * @param aElement reference to a "Root" element from which the search will start
+ * @param aWanted Specifies the location of the reference
+ * which will be set to point to the wanted Element
+ * @param aAttribute The name of the Attribute of the MainElement
+ * that is searched for
+ * @param aAttributeValue The wanted value of the Attribute
+ * that is searched for
+ * @param aDepth specifies how deep into the tree the search will proceed
+ * (if set to -1 the whole tree will be searched)
+ * @param aCurrentDepth How deep into the tree the search has proceeded
+ * (should be set to 0 when the search is started)
+ * @Return ETrue if element is found
+ */
+ IMPORT_C TBool GetDirectoryElementL( const TXmlEngElement& aElement,
+ TXmlEngElement& aWanted,
+ const TDesC8& aAttribute,
+ const TDesC8& aAttributeValue,
+ TInt aDepth=-1,
+ TInt aCurrentDepth=0);
+
+ /*
+ * GetElementListL
+ * Creates a RArray of Elements that fit the given specifiers
+ * @param aElement reference to a "Root" element from which the search will start
+ * @param aElementList list of elements matching searching criteria
+ * @param aMainTag LocalName of the Element that is being searched for
+ * @param aSearchable Specifies whether or not
+ * the searchability of container-elements is checked
+ * @Return ETrue if any element has been found.
+ */
+ IMPORT_C TBool GetElementListL( const TXmlEngElement& aElement,
+ RArray<TXmlEngElement>& aElementList,
+ const TDesC8& aMainTag,
+ TBool aSearchable=EFalse );
+
+
+
+ /*
+ * GetElementList
+ * Creates a RArray of Elements that fit the given specifiers
+ * @param aElement reference to a "Root" element from which the search will start
+ * @param aElementList list of elements matching searching criteria
+ * @param aMainTag LocalName of the Element that is being searched for
+ * @param aSubTag LocalName of an Element within
+ * the MainElement that is being searched for
+ * @param aSubTagValue Contents of the Element specified by the aSubTag
+ * @param aSearchable Specifies whether or not
+ * the searchability of container-elements is checked
+ * @Return ETrue if any element has been found.
+ */
+ IMPORT_C TBool GetElementListL( const TXmlEngElement& aElement,
+ RArray<TXmlEngElement>& aElementList,
+ const TDesC8& aMainTag,
+ const TDesC8& aSubTag,
+ const TDesC8& aSubValue,
+ TBool aSearchable=EFalse);
+
+
+
+ /*
+ * GetElementList
+ * Creates a RArray of Elements that fit the given specifiers
+ * @param aElement reference to a "Root" element from which the search will start
+ * @param aElementList list of elements matching searching criteria
+ * @param aMainTag LocalName of the Element that is being searched for
+ * @param aSubTag LocalName of an Element within
+ * the MainElement that is being searched for
+ * @param aSubTagValue Contents of the Element specified by the aSubTag
+ * @Param aSearchable Specifies whether or not
+ * the searchability of container-elements is checked
+ * @Param aNSPrefix the Prefix of the wanted element
+ * @Return ETrue if any element has been found.
+ */
+ IMPORT_C TBool GetElementListL( const TXmlEngElement& aElement,
+ RArray<TXmlEngElement>& aElementList,
+ const TDesC8& aMainTag,
+ const TDesC8& aSubTag,
+ const TDesC8& aSubValue,
+ const TDesC8& aNSPrefix,
+ TBool aSearchable=EFalse );
+
+ /*
+ * GetDirectoryElementList
+ * Creates a RArray of Elements that fit the given specifiers
+ * @param aElement reference to a "Root" element from which the search will start
+ * @param aElementList list of elements matching searching criteria
+ * @param aAttrName The name of the Attribute of the Element
+ * that is searched for
+ * @param aAttributeValue The wanted value of the Attribute
+ * that is searched for
+ * @param aSearchable Specifies whether or not the searchability
+ * of container-elements is checked
+ * @Return ETrue if any element has been found.
+ */
+ IMPORT_C TBool GetDirectoryElementListL( const TXmlEngElement& aElement,
+ RArray<TXmlEngElement>& aElementList,
+ const TDesC8& aAttrName,
+ const TDesC8& aAttrValue,
+ TBool aSearchable=EFalse);
+
+ /*
+ * GetContentElementList
+ * Creates a RArray of Elements that fit the given specifiers
+ * @Param aElement reference to a "Root" element from which the search will start
+ * @param aElementList list of elements matching searching criteria
+ * @Param aMainTag LocalName of the Element that is being searched for
+ * @Param aSubTag LocalName of an Element within the MainElement
+ * that is being searched for
+ * @Param aSubTagValue Contents of the Element specified by the aSubTag
+ * @Param aSearchable Specifies whether or not
+ * the searchability of container-elements is checked
+ * @Return ETrue if any element has been found.
+ */
+ IMPORT_C TBool GetContentElementListL( const TXmlEngElement& aElement,
+ RArray<TXmlEngElement>& aElementList,
+ const TDesC8& aSubTag,
+ const TDesC8& aSubValue,
+ TBool aSearchable=EFalse );
+
+ /*
+ * SaveToFile
+ * Saves the contents of the aRoot element into the given file.
+ * All saving should be done with ROOT element.
+ * @param aFileName name of the file
+ * @param aRoot reference to the first element of the DomTree
+ * @return ETrue if writing succeeded
+ */
+ IMPORT_C TBool SaveToFileL(const TDesC16& aFileName, const TXmlEngElement& aRoot);
+
+ /*
+ * SaveToFile
+ * Saves the contents of the aRoot element into the given file.
+ * Writes given TDesC8 string to file
+ * @param aFileName name of the file
+ * @param aData string that is saved to the file
+ * @return ETrue if writing succeeded
+ */
+ IMPORT_C TBool SaveToFileL(const TDesC16& aFileName, const TDesC8& aData);
+
+
+
+}
+
+#endif // C_UPNPDOMINTERFACE_H
+
+// End of File
+
+