| class TXmlEngElement : public TXmlEngNode |
This class represents an XML element in the DOM tree.
Namespace handling:
The namespace of a XML element is an URI that in pair with the local part of the element's name consistute the expanded-name of the element. It is said that "the element is of NNN namespace".
XML elements are shown as belonging to a specific namespace by using prefixes that previously were bound to some namespace URIs. The scope of a prefix is the element, where it was declared and all its child (sub-)elements.
<a xmlns:pr="http://some.uri.com/"> ... </a> OR <pr:a xmlns:pr="http://some.uri.com/"> ... </a> <a xmlns="http://some.uri.com/"> ... </a>
The latter two examples are equivalent and show the use of default namespace.
<a xmlns=""> .. </a>
<a xmlns:="http://some.uri.com/"> ... </a>(it does not contradict XML spec, but you are strongly advised against using this)
Prefix "xml" is reserved by XML Namespace spec for special purposes; it is implicitly bound to XML's namespace "http://www.w3.org/XML/1998/namespace" and no one is allowed to use this prefix except as with spec-defined elements and attributes or to rebind this prefix to other namespaces
Namespace URI may be "" (an empty descriptor) only for default namespace. In other words, "" namespace URI may not be bound to non-NULL prefix.
<a xmlns=""> ... </a>which undeclares any existing (in some parent element) default namespace for the scope of element 'a': element, its attributes and all child nodes of DOM tree. Note, that such "undeclaration" will be added only if neccessary.
Unneccessary namespace declaration are ignored. Attemps to add namespace binding using same namespace URI and prefix if such binding already exists in the scope will have no effect.
IMPORTANT! Attributes DO NOT HAVE default namespaces. If an attribute has no prefix, its namespace is undeclared even if there is some default namespaces for the scope of the element, which contains the attribute.
<a xmlns="ns_uri" attr="value"> ... </a>and assume that the attr belongs to namespace pointed to with ns_uri.
Use namespace declaration nodes as much as possible (but watch out for prefix collisions).
Add most referred to namespace declarations (AddNamespaceDeclarationL(uri,pref)) after any other namespace declarations in a element -- they will be found faster in namespace lookups.
For more informarion on NULL and NULL nodes: TXmlEngNode
| Inherited Enumerations | |
|---|---|
| TXmlEngNode:TXmlEngDOMNodeType | |
| Inherited Attributes | |
|---|---|
| TXmlEngNode::iInternal | |
| TXmlEngElement | ( | void * | aInternal | ) | [inline] |
Constructor
| void * aInternal | element pointer |
| IMPORT_C TXmlEngNamespace | AddNamespaceDeclarationL | ( | const TDesC8 & | aNsUri, |
| const TDesC8 & | aPrefix | |||
| ) | ||||
Adds a namespace declaration to the current element: a binding of prefix to namespace URI.
If the same namespace declaration exists (same prefix and URI), a redundant namespace declaration will not be created.
Both KNullDesC8 or an empty descriptor may be used for "UNDEFINED URI" and "NO PREFIX" values of arguments. Please refer to the class documentation for more specific information. TXmlEngElement
Note: Undeclaring of default namespace (xmlns="") is supported by the SetNoDefaultNamespace() method. SetNoDefaulNamespace()
Note: Adding a namespace declaration that rebinds the prefix mapping (or default namespace) used by nodes lower in the tree may damage the document tree because references to namespace declarations are not updated. However, after serialization, the document will have the desired structure. Use this method with care!
Copies are taken of descripters passed in.
The namespace that was created or found or a NULL namespace if the namespace is being undeclared.
leave
KXmlEngErrNullNode Element is NULL
leave
KXmlEngErrWrongUseOfAPI URI or prefix is not specified
leave
One of the system-wide error codes
| IMPORT_C TXmlEngAttr | AddNewAttributeL | ( | const TDesC8 & | aName, |
| const TDesC8 & | aValue | |||
| ) | ||||
Creates a new attribute node outside of any namespace (i.e. it has no prefix), sets the attribute's value and links it as the last attribute of the current element.
No checks are made that an attribute with the same name exists. Use this method only on newly created elements! Otherwise, use TXmlEngElement::SetAttributeL()
The attribute's value is the second argument in all AddNewAttributeL() methods
TXmlEngElement el = ... ; // get some element
el.AddNewAttributeL("version","0.1").SetAsFirstSibling();
Copies are taken of descripters passed in.
MoveBeforeSibling(TXmlEngNode)
The created attribute
leave
KXmlEngErrNullNode The node is NULL
leave
KXmlEngErrWrongUseOfAPI aName is empty
leave
One of the system-wide error codes
| IMPORT_C TXmlEngAttr | AddNewAttributeL | ( | const TDesC8 & | aName, |
| const TDesC8 & | aValue, | |||
| const TXmlEngNamespace | aNsDef | |||
| ) | ||||
Creates a new attribute node and adds it to the element.
The provided namespace declaration is used to set the attribute's namespace.
Note: If aNsDef is not defined in some of the attribute's ascendants (including this element), then the ReconcileNamespacesL() method must be called on this element later.
Copies are taken of descripters passed in.
The created attribute
leave
KXmlEngErrNullNode The node is NULL
leave
KXmlEngErrWrongUseOfAPI aName is empty
leave
One of the system-wide error codes
| const TDesC8 & aName | The local name of attribute |
| const TDesC8 & aValue | Value to set for new attribute or KNullDesC8 |
| const TXmlEngNamespace aNsDef | Namespace to add to the attribute |
| IMPORT_C TXmlEngAttr | AddNewAttributeL | ( | const TDesC8 & | aName, |
| const TDesC8 & | aValue, | |||
| const TDesC8 & | aNsUri, | |||
| const TDesC8 & | aPrefix | |||
| ) | ||||
Creates a new attribute for the element. A namespace declaration for the attribute namespace is also created.
Note: Namespace declarations are reused if possible (no redundant ones are created)
Copies are taken of descripters passed in.
The created attribute
leave
KXmlEngErrNullNode The node is NULL
leave
KXmlEngErrWrongUseOfAPI aName is empty
leave
One of the system-wide error codes
| TXmlEngAttr | AddNewAttributeSameNsL | ( | const TDesC8 & | aName, |
| const TDesC8 & | aValue | |||
| ) | [inline] | |||
Creates a new attribute node using the namespace of its parent element (this element), sets the attribute's value and links it as the last attribute of the element
For more hints how to use it AddNewAttributeL(const TDesC8&,const TDesC8&)
No checks are made that an attribute with the same name exists
if the namespace of the parent element is default (i.e. bound prefix is KNullDesC8), then a temporary prefix will be used and bound to the same namespace URI as the element (It is due to the fact that default namespaces do not spread on unprefixed attributes, see http://w3.org/TR/REC-xml-names/#defaulting)
Copies are taken of descripters passed in. KNullDesC8
The created attribute
leave
KXmlEngErrNullNode The node is NULL
leave
KXmlEngErrWrongUseOfAPI aName is empty
leave
One of the system-wide error codes
| IMPORT_C TXmlEngAttr | AddNewAttributeUsePrefixL | ( | const TDesC8 & | aLocalName, |
| const TDesC8 & | aValue, | |||
| const TDesC8 & | aPrefix | |||
| ) | ||||
Creates a new attribute using the namespace which is bound to the specified prefix
TXmlEngElement el = parent.AddNewAttributeUsePrefixL("property","ObjName","rdf");
el.AddNewAttributeUsePrefixL("type", "xs:integer", "rdf");
TXmlEngNamespace boundNS = TXmlEngNamespace::LookupByPrefix(thisElement, prefix);
if (boundNS.NotNull()){
thisElement.AddNewAttributeUsePrefixL("name", value, prefix);
}
Note: Use AddNewAttributeNsL(name,value,nsDefNode) as much as you can, because it is the most efficient way to create namespaced DOM elements (no additional lookups for namespace declarations are required).
// If namespace with given URI is not in the scope, then it will be declared
// and bound to "data" prefix.
TXmlEngNamespace nsDef = elem.FindOrCreateNsDefL("http://../Data", "data");
elem.AddNewAttributeL("location", "...", nsDef);
elem.AddNewElementL("child", nsDef).AddNewAttributeL("attr","...value...");
// the result is
...
<elem xmlns:data="http://../Data" data:location="...">
<data:child attr="...value..."/>
</elem>
...
//
Copies are taken of descripters passed in.
The created attribute
leave
KXmlEngErrNullNode The node is NULL
leave
KXmlEngErrWrongUseOfAPI aLocalName is empty
leave
KErrNoMemory The namespace is not found and the URI is not http://www.w3.org/XML/1998/namespace; or there is a memory allocation error
leave
One of the system-wide error codes
| IMPORT_C TXmlEngAttr | AddNewAttributeWithNsL | ( | const TDesC8 & | aLocalName, |
| const TDesC8 & | aValue, | |||
| const TDesC8 & | aNsUri | |||
| ) | ||||
Creates new attributes using the namespace in scope, which has the specified URI
Almost the same as AddNewAttributeUsePrefixL() but does lookup by namespace URI
AddNewAttributeUsePrefixL(const TDesC8&,const TDesC8&,const TDesC8&)
Copies are taken of descripters passed in. KNullDesC8
NULL attribute if namespace declaration is not found OR newly added to the end of attribute list attribute of this element.
leave
KXmlEngErrNullNode The node is NULL
leave
KXmlEngErrWrongUseOfAPI aLocalName is empty
leave
One of the system-wide error codes
| IMPORT_C TXmlEngElement | AddNewElementAutoPrefixL | ( | const TDesC8 & | aLocalName, |
| const TDesC8 & | aNsUri, | |||
| TXmlEngElement | aNsDeclTarget | |||
| ) | ||||
Creates a new child element. If there is no a prefix binding for the new element's namespace, a namespace decaration is created with a generated prefix at the specified element.
The location of the namespace declaration may be controlled with aNsDeclTarget:
el.AddNewElementAutoPrefixL(tagName,uri,KNullDesC8); // declare on the new element
el.AddNewElementAutoPrefixL(tagName,uri,el); // declare on the parent element
el.AddNewElementAutoPrefixL(tagName,uri,doc.DocumentElement()); // declare on the root element
...
Note: The farther namespace declaration up in the document tree, the longer the namespace declaration lookups take.
Copies are taken of descripters passed in.
The created element
leave
KXmlEngErrNullNode Element is NULL
leave
KXmlEngErrWrongUseOfAPI Name or URI is not specified
leave
One of the system-wide error codes
| const TDesC8 & aLocalName | Name of the element to create |
| const TDesC8 & aNsUri | Namespace URI of the new element |
| TXmlEngElement aNsDeclTarget | The element where the namespace declaraton should be placed. |
| IMPORT_C TXmlEngElement | AddNewElementL | ( | const TDesC8 & | aName | ) |
Adds a child element with no namespace. This results in adding an element with aName and no prefix.
This method is the best for creation of non-namespace based documents or document fragments, where no default namespace declared.
It may be used also as a method for adding elements from the default namespace, BUT namespace will be assigned ONLY after serialization of the current document and parsing it back into a DOM tree!! If you need the new element to inherit the default namespace use:
...
TXmlEngNamespace defns = element.DefaultNamespace();
TXmlEngElement newEl = element.AddNewElementL("Name",defns);
...
It is not recommended that you use an undefined namespace with libxml. If an undefined namespace for the element is truly required, then DO NOT USE this method if there is a default namespace in the scope! AddNamespaceDeclarationL
Copies are taken of descripters passed in.
The created element
leave
KXmlEngErrNullNode Element is NULL
leave
KXmlEngErrWrongUseOfAPI Name is not specified
leave
One of the system-wide error codes
| const TDesC8 & aName | The name of the element |
| IMPORT_C TXmlEngElement | AddNewElementL | ( | const TDesC8 & | aLocalName, |
| TXmlEngNamespace | aNsDecl | |||
| ) | ||||
Creates a new child element with the provided name and namespace declaration and adds it as the last child of its parent.
Copies are taken of descripters passed in.
Created element node
leave
KXmlEngErrNullNode Element is NULL
leave
KXmlEngErrWrongUseOfAPI Name is not specified
leave
One of the system-wide error codes
| const TDesC8 & aLocalName | The name of the element |
| TXmlEngNamespace aNsDecl | The namespace declaration that must be retrieved from one of the ascendant nodes of the new elements (and its prefix should not be remapped to another namespace URI for the scope of the new element) |
| IMPORT_C TXmlEngElement | AddNewElementL | ( | const TDesC8 & | aLocalName, |
| const TDesC8 & | aNsUri, | |||
| const TDesC8 & | aPrefix | |||
| ) | ||||
Creates a new child element with provided the name, prefix and namespace URI and adds it as the last child of its parent.
The new namespace declaration will be attached to the parent (this) element and used as the namespace for newly created child element. If such a binding already exists (same prefix is bound to same URI), it will be reused. If the prefix is already bound to some other namespace URI, it will be rebound by the new namespace declaration node.
Copies are taken of descripters passed in.
The created element node
leave
KXmlEngErrNullNode Element is NULL
leave
KXmlEngErrWrongUseOfAPI Name or URI or prefix is not specified
leave
One of the system-wide error codes
| IMPORT_C TXmlEngElement | AddNewElementSameNsL | ( | const TDesC8 & | aLocalName | ) |
Creates a child element with the same namespace (and prefix if present) as the parent element and adds it as the last child of its parent.
Copies are taken of descripters passed in.
The created element
leave
KXmlEngErrNullNode Element is NULL
leave
KXmlEngErrWrongUseOfAPI Name is not specified
leave
One of the system-wide error codes
| const TDesC8 & aLocalName | The element's name |
| IMPORT_C TXmlEngElement | AddNewElementUsePrefixL | ( | const TDesC8 & | aLocalName, |
| const TDesC8 & | aPrefix | |||
| ) | ||||
Performs a lookup for the namespace declaration for the specified prefix and adds a new child element with the found namespace as the last child of its parent.
The prefix is bound
Copies are taken of descripters passed in.
The created element
leave
KXmlEngErrNullNode Element is NULL
leave
KXmlEngErrWrongUseOfAPI Name is not specified
leave
KErrNoMemory The namespace is not found and the prefix is not "xml" (i.e http://www.w3.org/XML/1998/namespace); or there is a memory allocation error.
leave
One of the system-wide error codes
| IMPORT_C TXmlEngElement | AddNewElementWithNsL | ( | const TDesC8 & | aLocalName, |
| const TDesC8 & | aNsUri | |||
| ) | ||||
Performs a lookup for the namespace declaration for the specified namespace URI and adds a new child element with the found namespace. The new element is added as the last child of this element.
Copies are taken of descripters passed in.
A namespace with the given URI has been declared
The created element
leave
KXmlEngErrNullNode Element is NULL
leave
KXmlEngErrWrongUseOfAPI Name is not specified
leave
KErrNoMemory The namespace is not found and the URI is not http://www.w3.org/XML/1998/namespace or there is a memory allocation error
leave
One of the system-wide error codes
| IMPORT_C void | AddTextL | ( | const TDesC8 & | aString | ) |
Adds text as a child of the element to the end of the list of children.
Note: There may be several TXmlEngTextNode and TXmlEngEntityReference nodes added, depending on the aString value. For example, if the curernt node has text and attributes, a text node and attribute nodes will be added.
Copies are taken of descripters passed in.
leave
KXmlEngErrNullNode Element is NULL
leave
One of the system-wide error codes
| const TDesC8 & aString | Text to be added as the element's content. |
| IMPORT_C TXmlEngAttr | AddXmlIdL | ( | const TDesC8 & | aLocalName, |
| const TDesC8 & | aValue, | |||
| TXmlEngNamespace | aNs = TXmlEngNamespace() | |||
| ) | ||||
Adds attribute to element that will be used as Xml:Id. Does not check if an attribute with the same name exists.
Note: Call RXmlEngDocument.RegisterXmlIdL(aName,aNsUri) first to register existed id's in the document. If the ids are not registered the ID will not be added to the element.
Copies are taken of descripters passed in.
Attribute if created. Null attribute if Xml:Id exists
leave
KXmlEngErrWrongUseOfAPI Element is NULL or attribute doesn't exist
leave
One of the system-wide error codes
| const TDesC8 & aLocalName | Name of the attribute |
| const TDesC8 & aValue | Value of the attribute |
| TXmlEngNamespace aNs = TXmlEngNamespace() | Namespace of the attribute |
| IMPORT_C void | AppendTextNoEncL | ( | const TDesC8 & | aNotEncString | ) |
Appends a new text node with the value exactly as presented in the string. Predefined entities are not converted into the characters they represent. Existing child nodes are not removed.
TXmlEngAttr::SetValueNoEncL(const TDesC8& aNewValue);
Copies are taken of descripters passed in.
leave
KXmlEngErrNullNode Element is NULL
leave
One of the system-wide error codes
| const TDesC8 & aNotEncString | Appended string value |
| IMPORT_C TXmlEngAttr | AttributeNodeL | ( | const TDesC8 & | aLocalName, |
| const TDesC8 & | aNamespaceUri = KNullDesC8 | |||
| ) | const | |||
Retrieves an attribute node with a specific namespace by its name.
Attribute node with matching namespace URI and name, NULL if not found.
leave
One of the system-wide error codes
| const TDesC8 & aLocalName | Name of the attribute |
| const TDesC8 & aNamespaceUri = KNullDesC8 | Attribute namespace URI, default is KNullDesC8 |
| IMPORT_C TPtrC8 | AttributeValueL | ( | const TDesC8 & | aLocalName, |
| const TDesC8 & | aNamespaceUri = KNullDesC8 | |||
| ) | const | |||
Returns the value of the attribute with the given name and namespace URI.
The attribute value (for as long as the attribute exists) or NULL if not found.
leave
One of the system-wide error codes
| const TDesC8 & aLocalName | Local name of the attribute |
| const TDesC8 & aNamespaceUri = KNullDesC8 | Namespace URI of the attribute, or the default namespace if not specified. |
| void | ClearElement | ( | ) | [inline] |
Removes all element contents: child nodes, attributes and namespace declarations
| IMPORT_C void | CopyAttributesL | ( | TXmlEngElement | aSrc | ) |
Copies attributes from another element. It may be a very convenient method for initializing element with a set of predefined attributes.
Note: Namespaces of the this element may need to be reconciled if the copied attributes belong to any namespace that is not declared on some ascendant of this node. ReconcileNamespacesL()
leave
KXmlEngErrNullNode The element is NULL
leave
One of the system-wide error codes
| TXmlEngElement aSrc | Source element |
| IMPORT_C void | CopyChildrenL | ( | TXmlEngElement | aSrc | ) |
Recursively copies the children (and all of it's associated information) from another element. Elements are appended to the current element's children list.
Note: Namespaces of this element may need to be reconciled after copy operation ReconcileNamespacesL()
leave
KXmlEngErrNullNode The element is NULL
leave
KXmlEngWrongUseOfAPI The source element is NULL
leave
One of the system-wide error codes
| TXmlEngElement aSrc | Source element |
| TXmlEngElement | CopyL | ( | ) | const [inline] |
Specialized version of TXmlEngNode::CopyL() Deep copy of the element.
leave
KXmlEngErrNullNode The element is NULL
leave
One of the system-wide error codes
| TXmlEngNamespace | DefaultNamespaceL | ( | ) | const [inline] |
Get the default namespace for the element.
A NULL TXmlEngNamespace means that an element with no prefix has no namespace associated with it because no default namespace was declared or the default namespace was undeclared with xmlns=""
This function is equivalent to LookupNamespaceByPrefixL(KNullDesC8). KNullDesC8
The default namespace in the scope of the element
leave
One of the system-wide error codes
| IMPORT_C TXmlEngElement | ElementCopyNoChildrenL | ( | TBool | preserveNsContext | ) | const |
Copies the element with its attributes, but not child nodes
If the context is preserved (preserveNsContent), then all namespace declarations that are in the element are writen to the <element ...> tag.
The copied element
leave
KXmlEngErrNullNode The element is NULL
leave
One of the system-wide error codes
| TBool preserveNsContext | Whether the namespace context should be preserved |
| IMPORT_C TXmlEngNamespace | FindOrCreateNsDeclL | ( | const TDesC8 & | aNsUri, |
| const TDesC8 & | aPrefix | |||
| ) | ||||
Performs a search for the namespace in the scope of the element. This method will create new namespace declaration on the element if such namespace is not found.
Note: Be sure not to use the result of this method for non-descendants of the element or in situations when prefix overlapping might occur. TXmlEngAttr
TXmlEngNamespace Please read the documentation for this class:
Copies are taken of descripters passed in.
The namespace found or created
leave
KXmlEngErrNullNode Element is NULL
leave
KXmlEngErrWrongUseOfAPI URI is not specified
leave
One of the system-wide error codes
LookupNamespacebyUriL
| IMPORT_C TXmlEngNamespace | FindOrCreateNsDeclL | ( | const TDesC8 & | aNsUri | ) |
Performs a search on the element and its ascendants for any namespace declaration with a given URI. Creates a new namespace declaration with a (unique) prefix if the search was not successful. AddNamespaceDeclarationL
Copies are taken of descripters passed in.
The namespace found or created
leave
KXmlEngErrNullNode Element is NULL
leave
KXmlEngErrWrongUseOfAPI URI is not specified
leave
One of the system-wide error codes
| const TDesC8 & aNsUri | Namespace to search for |
| IMPORT_C void | GetAttributes | ( | RXmlEngNodeList< TXmlEngAttr > & | aList | ) | const |
Retrieves a list of the attribute nodes of an element
Upon return, aList is initialized and is ready for use with HasNext() and Next() methods:
...
TXmlEngElement root = doc.DocumentElement();
RXmlEngNodeList<TXmlEngAttr> attlist;
root.GetAttributes(attlist);
while (attlist.HasNext())
processAttribute(attlist.Next());
...
attlist.Close();
If there are no attributes the list will be empty.
| RXmlEngNodeList< TXmlEngAttr > & aList | An attribute list to initialize |
| IMPORT_C void | GetChildElements | ( | RXmlEngNodeList< TXmlEngElement > & | aList | ) | const |
Retrieves a list of child elements of an element.
Upon return, aList is initialized and is ready for use with HasNext() and Next() methods.
Note: This returns a list of the child element nodes only.
There is no affect if the element attributes are empty.
| RXmlEngNodeList< TXmlEngElement > & aList | A child list to initialize |
| IMPORT_C void | GetElementsByTagNameL | ( | RXmlEngNodeList< TXmlEngElement > & | aList, |
| const TDesC8 & | aLocalName, | |||
| const TDesC8 & | aNamespaceUri = KNullDesC8 | |||
| ) | const | |||
Initializes list of child elements with matching names and namespace URIs.
Note: This method does not list all descendants of the element, only child elements KNullDesC8
leave
One of the system-wide error codes
| RXmlEngNodeList< TXmlEngElement > & aList | Node list to be created |
| const TDesC8 & aLocalName | Element name |
| const TDesC8 & aNamespaceUri = KNullDesC8 | if specified it sets the Namespace URI, default is KNullDesC8 (no namespace set). |
| TBool | HasAttributeL | ( | const TDesC8 & | aLocalName, |
| const TDesC8 & | aNamespaceUri = KNullDesC8 | |||
| ) | const [inline] | |||
Check if the element has an attribute with given parameters.
This function is the same as AttributeNodeL(uri,name).NotNull().
ETrue if the element holds an attribute with such namespace URI and name.
leave
One of the system-wide error codes
| const TDesC8 & aLocalName | Name of attribute |
| const TDesC8 & aNamespaceUri = KNullDesC8 | Namespace uri, default is KNullDesC8. |
| IMPORT_C TBool | HasNsDeclarationForPrefixL | ( | const TDesC8 & | aPrefix | ) | const |
Checks whether a prefix has been bound in this element (not in one of its ascendants)
Use this method for preventing prefix-name collision in a element node
Copies are taken of descripters passed in.
ETrue if there is already a namespace declaration that uses aPrefix on this element
leave
One of the system-wide error codes
| const TDesC8 & aPrefix | Namespace prefix |
| IMPORT_C TXmlEngNamespace | LookupNamespaceByPrefixL | ( | const TDesC8 & | aPrefix | ) | const |
Finds the namespace declaration that has a specific prefix in the list of parents for this element.
If no prefix is specified (an empty descriptor or KNullDesC8) then it is considered to be a "NO PREFIX" search. Therefore, if the namespace declaration for "no prefix" is searched, then the default namespace is returned.
Copies are taken of descripters passed in. KNullDesC8
The namespace, which may be NULL if prefix is not found; NULL result for "no prefix" means that default namespace is undefined.
leave
One of the system-wide error codes
| const TDesC8 & aPrefix | Namespace prefix. |
| IMPORT_C TXmlEngNamespace | LookupNamespaceByUriL | ( | const TDesC8 & | aUri | ) | const |
Finds a namespace declaration that has a specific namespace URI in the scope for the given node.
KNullDesC8 value of aUri is equivalent to an empty descriptor and means "UNDEFINED NAMESPACE". For such URI's a NULL namespace handle is always returned even if there is a namespace undeclaration, which has an empty descriptor URI (and KNullDesC8 prefix).
Hint: Use the returned instance of TXmlEngNamespace as the aNsDef argument to an element's methods that create new child elements and attributes. The same TXmlEngNamespace may be used on deeper descentants of the reference element (and doing this way will generally increase performance of DOM tree construction). However, if namespace bindings are not controlled for the element's children and the prefix (which is bound to the search namespace) is rebound to some other namespace URI, then reusing the namespace may lead to unwanted result.
Note: At the moment it is possible to retrieve namespace declaration nodes whose prefixes were rebound. Be careful when using returned TXmlEngNamespace objects for creation of new elements.
Copies are taken of descripters passed in.
The namespace declaration that binds the given namespace URI to a prefix or sets it as a default namespace
leave
One of the system-wide error codes
| const TDesC8 & aUri | Namespace URI, for which the namespace declaration is searched |
| IMPORT_C void | RemoveAttributeL | ( | const TDesC8 & | aLocalName, |
| const TDesC8 & | aNamespaceUri = KNullDesC8 | |||
| ) | ||||
Removes the attribute with the given name and namespace URI (if it exists). Memory allocated for the attribute is freed.
leave
One of the system-wide error codes
| const TDesC8 & aLocalName | Name of the attribute |
| const TDesC8 & aNamespaceUri = KNullDesC8 | Attribute namespace URI, default is KNullDesC8 |
| IMPORT_C void | RemoveChildElementsL | ( | const TDesC8 & | aLocalName, |
| const TDesC8 & | aNamespaceUri | |||
| ) | ||||
Removes the child element with the given name and namespace URI (if it exists). Memory allocated for the element is freed.
leave
KXmlEngErrNullNode The element is NULL
leave
One of the system-wide error codes
| IMPORT_C void | RemoveChildren | ( | ) |
Resets element's content: all child nodes are removed
| IMPORT_C void | RemoveNamespaceDeclarations | ( | ) |
Resets all namespace declarations made in the element
Note: There can be references to these namespace declarations elsewhere! Use ReconcileNamespacesL() to fix that.
| IMPORT_C void | RenameElementL | ( | const TDesC8 & | aLocalName, |
| const TDesC8 & | aNamespaceUri, | |||
| const TDesC8 & | aPrefix | |||
| ) | ||||
Renames the element with the given name, namespace URI, and namespace prefix.
leave
One of the system-wide error codes
| IMPORT_C void | SetAttributeL | ( | const TDesC8 & | aLocalName, |
| const TDesC8 & | aValue, | |||
| const TDesC8 & | aNamespaceUri = KNullDesC8 , | |||
| const TDesC8 & | aPrefix = KNullDesC8 | |||
| ) | ||||
Sets the value of the given attribute. The attribute is created if there is no such attribute yet.
Note: If prefix is not KNullDesC8 (or an empty descriptor), then the namespace URI may not be empty see http://www.w3.org/TR/REC-xml-names/#ns-decl (Definition #3)
Copies are taken of descripters passed in. KNullDesC8
leave
KXmlEngErrNullNode The element is NULL
leave
KXmlEngErrWrongUseOfAPI Attribute name not specified
leave
One of the system-wide error codes
| const TDesC8 & aLocalName | Attribute name |
| const TDesC8 & aValue | Attribute value |
| const TDesC8 & aNamespaceUri = KNullDesC8 | Namespace URI - default is KNullDesC8 |
| const TDesC8 & aPrefix = KNullDesC8 | Namespace prefix - default is KNullDesC8 |
| IMPORT_C void | SetAttributeNodeL | ( | TXmlEngAttr | aNewAttr | ) |
Adds an attribute to this element. If an attribute of the same name exists, it will be destroyed.
leave
KXmlEngErrNullNode The element or attribute is NULL
leave
One of the system-wide error codes
| TXmlEngAttr aNewAttr | The new attribute |
| IMPORT_C TXmlEngNamespace | SetDefaultNamespaceL | ( | const TDesC8 & | aNsUri | ) |
Adds a default namespace declaration.
1 This achieves the same result as with AddNamespaceDeclarationL(aNsUri, KNullDesC8), but additionally the element's namespace is modified (if it has no prefix and there were no default namespace declaration in the scope) to the new default one.
Copies are taken of descripters passed in. KNullDesC8
The created namespace declaration (NULL for UNDEFINED NAMESPACE)
leave
KXmlEngErrNullNode Element is NULL
leave
KXmlEngErrWrongUseOfAPI URI is not specified
leave
One of the system-wide error codes
| const TDesC8 & aNsUri | Namespace URI; KNullDesC8 and empty descriptor are allowed to represent UNDEFINED NAMSPACE |
| IMPORT_C void | SetEscapedTextL | ( | const TDesC8 & | aEscapedString | ) |
Sets the text content of the element from an escaped string. TXmlEngAttr::SetEscapedValueL(TDesC8&)
leave
KXmlEngErrNullNode Element is NULL
leave
One of the system-wide error codes
| const TDesC8 & aEscapedString | New value |
| IMPORT_C void | SetNoDefaultNamespaceL | ( | ) |
Undeclares any default namespace for this element and its descendants.
If there is already a default namespace, a xmlns="" namespace declaration is added. Otherwise, nothing happens, since elements with no prefix in such scope are automaticaly considered outside of any namespace.
The side effect of this method is that the namespace of the current element may change from the previous default namespace to a NULL TXmlEngNamespace, which is considered an absence of namespace.
If the element has a prefix (i.e. not having default namespace), then the only effect for the element is undeclaration of existing default namespace.
If the element is in the scope of another xmlns="" undeclaration, no action is taken.
Note: Use AddNamespaceDeclarationL(KNullDesC8,KNullDesC8) to force the creation of a xmlns="" declaration within the scope of another such declaration (otherwise unneccessary/duplicate declarations are not created).
Note: This method should be called on elements before adding children, because default namespace undeclaration is not spread into its subtree and descendants' default namespaces are not reset to NULL. This should be taken into account if later some processing on the subtree occurs. However, after serialization and deserialization, undeclared default namespace will affect whole element's subtree correctly.
leave
KXmlEngErrNullNode Element is NULL
leave
One of the system-wide error codes
| IMPORT_C void | SetTextL | ( | const TDesC8 & | aString | ) |
Sets text contents for the element. Any child nodes are removed. This function is the same as TXmlEngNode::SetValueL(TDesC8&)
TXmlEngNode::SetValueL(TDesC8&)
leave
KXmlEngErrNullNode Element is NULL
leave
One of the system-wide error codes
| const TDesC8 & aString | Text to be set as element's content. |
| IMPORT_C void | SetTextNoEncL | ( | const TDesC8 & | aNotEncString | ) |
Sets the new element value exactly as presented in the string. Predefined entities are not converted into the characters they represent. Any child nodes are removed.
TXmlEngAttr::SetValueNoEncL(const TDesC8& aNewValue);
leave
KXmlEngErrNullNode Element is NULL
leave
One of the system-wide error codes
| const TDesC8 & aNotEncString | New string value |
| IMPORT_C TPtrC8 | Text | ( | ) | const |
Gets element content. This method may be used in most cases when the element has only simple text content (without entity references embedded). If the element's contents is mixed (other types of nodes present), only the contents of the first child node is returned (if it is a TXmlEngTextNode node).
For getting the contents of an element that has contents containing entity references, WholeTextValueCopyL() should be used.
TXmlEngNode::WholeTextContentsCopyL()
The simple text contents of the element or NULL if there is no text.
| IMPORT_C TXmlEngNamespace | TheXMLNamespaceL | ( | ) | const |
Retrieves the implicitly declared XML infoset binding of the 'xml' prefix to XML's namespace URI: "http://www.w3.org/XML/1998/namespace"
The result should be used for creating attributes beloging to the XML namespace (xml:lang, xml:space, xml:id , etc.)
DO NOT USE the methods LookupNamespaceByUriL(const TDesC8&) and LookupNamespaceByPrefixL(const TDesC8&) (with the arguments "http://www.w3.org/XML/1998/namespace" and "xml" respectively) for retrieving the namespace node, since in the case of a memory allocation fault, a NULL result is returned (and breaks your program silently)
Note: Normally the 'xml' prefix is bound to the XML namespace URI in the document node, BUT if this element is not a part of the document tree yet, the requested namespace declaration WILL BE ADDED to the current node. This is the reason why the method may fail in OOM conditions.
The namespace matching the prefix binding {xml,"http://www.w3.org/XML/1998/namespace"} in the current document
leave
KErrNoMemory The element is NULL or there was a memory allocation error
leave
One of the system-wide error codes