Skip Headers

Oracle® XML API Reference
10g Release 1 (10.1)
Part No. B10789-01
  Go To Table Of Contents
Contents

Previous Next  

Attr Interface

Table 4-1 summarizes the methods of available through the Attr interface.

Table 4-1 Summary of Attr Methods; DOM Package

Function Summary
XmlDomGetAttrLocal
Returns an attribute's namespace local name as NULL-terminated string.
XmlDomGetAttrLocalLen
Returns an attribute's namespace local name as length-encoded string.
XmlDomGetAttrName
Return attribute's name as NULL-terminated string.
XmlDomGetAttrNameLen
Return attribute's name as length-encoded string.
XmlDomGetAttrPrefix
Returns an attribute's namespace prefix.
XmlDomGetAttrSpecified
Return flag that indicates whether an attribute was explicitly created.
XmlDomGetAttrURI
Returns an attribute's namespace URI as NULL-terminated string.
XmlDomGetAttrURILen
Returns an attribute's namespace URI as length-encoded string.
XmlDomGetAttrValue
Return attribute's value as NULL-terminated string.
XmlDomGetAttrValueLen
Return attribute's value as length-encoded string.
XmlDomGetAttrValueStream
Get attribute value stream-style,i.e.chunked.
XmlDomGetOwnerElem
Return an attribute's "owning" element.
XmlDomSetAttrValue
Set an attribute's value.
XmlDomSetAttrValueStream
Sets an attribute value stream style (chunked).


XmlDomGetAttrLocal

Returns an attribute's namespace local name (in the data encoding). If the attribute's name is not fully qualified (has no prefix), then the local name is the same as the name.

A length-encoded version is available as XmlDomGetAttrURILen which returns the local name as a pointer and length, for use if the data is known to use XMLType backing store.


Syntax
oratext* XmlDomGetAttrLocal(
   xmlctx *xctx, 
   xmlattrnode *attr)

Parameter In/Out Description
xctx
IN
XML context
attr
IN
attribute node


Returns

(oratext *) attribute's local name [data encoding]


XmlDomGetAttrLocalLen

Returns an attribute's namespace local name (in the data encoding). If the attribute's name is not fully qualified (has no prefix), then the local name is the same as the name.

A NULL-terminated version is available as XmlDomGetAttrLocal which returns the local name as NULL-terminated string. If the backing store is known to be XMLType, then the attribute's data will be stored internally as length-encoded. Using the length-based GetXXX functions will avoid having to copy and NULL-terminate the data.

If both the input buffer is non-NULL and the input buffer length is nonzero, then the value will be stored in the input buffer. Else, the implementation will return its own buffer.

If the actual length is greater than buflen, then a truncated value will be copied into the buffer and len will return the actual length.


Syntax
oratext* XmlDomGetAttrLocalLen(
   xmlctx *xctx, 
   xmlattrnode *attr, 
   oratext *buf, 
   ub4 buflen, 
   ub4 *len)

Parameter In/Out Description
xctx
IN
XML context
attr
IN
attribute node
buf
IN
input buffer; optional
buflen
IN
input buffer length; optional
len
OUT
length of local name, in characters


Returns

(oratext *) Attr's local name [data encoding]


XmlDomGetAttrName

Returns the fully-qualified name of an attribute (in the data encoding) as a NULL-terminated string, for example bar\0 or foo:bar\0.

A length-encoded version is available as XmlDomGetAttrNameLen which returns the attribute name as a pointer and length, for use if the data is known to use XMLType backing store.


Syntax
oratext* XmlDomGetAttrName(
   xmlctx *xctx, 
   xmlattrnode *attr)

Parameter In/Out Description
xctx
IN
XML context
attr
IN
attribute node


Returns

(oratext *) name of attribute [data encoding]


XmlDomGetAttrNameLen

Returns the fully-qualified name of an attribute (in the data encoding) as a length-encoded string, for example ("bar", 3) or ("foo:bar", 7).

A NULL-terminated version is available as XmlDomGetAttrName which returns the attribute name as NULL-terminated string. If the backing store is known to be XMLType, then the attribute's data will be stored internally as length-encoded. Using the length-based GetXXX functions will avoid having to copy and NULL-terminate the data.

If both the input buffer is non-NULL and the input buffer length is nonzero, then the value will be stored in the input buffer. Else, the implementation will return its own buffer.

If the actual length is greater than buflen, then a truncated value will be copied into the buffer and len will return the actual length.


Syntax
oratext* XmlDomGetAttrNameLen(
   xmlctx *xctx, 
   xmlattrnode *attr, 
   oratext *buf, 
   ub4 buflen, 
   ub4 *len)

Parameter In/Out Description
xctx
IN
XML context
attr
IN
attribute node
buf
IN
input buffer; optional
buflen
IN
input buffer length; optional
len
OUT
length of local name, in characters


Returns

(oratext *) name of attribute [data encoding]


XmlDomGetAttrPrefix

Returns an attribute's namespace prefix (in the data encoding). If the attribute's name is not fully qualified (has no prefix), NULL is returned.


Syntax
oratext* XmlDomGetAttrPrefix(
   xmlctx *xctx, 
   xmlattrnode *attr)

Parameter In/Out Description
xctx
IN
XML context
attr
IN
attribute node


Returns

(oratext *) attribute's namespace prefix [data encoding] or NULL


XmlDomGetAttrSpecified

Return the 'specified' flag for an attribute. If the attribute was explicitly given a value in the original document, this is TRUE; otherwise, it is FALSE. If the node is not an attribute, returns FALSE. If the user sets an attribute's value through DOM, its specified flag will be TRUE. To return an attribute to its default value (if it has one), the attribute should be deleted; it will then be re-created automatically with the default value (and specified will be FALSE).


Syntax
boolean XmlDomGetAttrSpecified(
   xmlctx *xctx,
   xmlattrnode *attr)

Parameter In/Out Description
xctx
IN
XML context
attr
IN
attribute node


Returns

(boolean) attribute's "specified" flag


See Also:

XmlDomSetAttrValue


XmlDomGetAttrURI

Returns an attribute's namespace URI (in the data encoding). If the attribute's name is not qualified (does not contain a namespace prefix), it will have the default namespace in effect when the node was created (which may be NULL).

A length-encoded version is available as XmlDomGetAttrURILen which returns the URI as a pointer and length, for use if the data is known to use XMLType backing store.


Syntax
oratext* XmlDomGetAttrURI(
   xmlctx *xctx, 
   xmlattrnode *attr)

Parameter In/Out Description
xctx
IN
XML context
attr
IN
attribute node


Returns

(oratext *) attribute's namespace URI [data encoding] or NULL


XmlDomGetAttrURILen

Returns an attribute's namespace URI (in the data encoding) as length-encoded string. If the attribute's name is not qualified (does not contain a namespace prefix), it will have the default namespace in effect when the node was created (which may be NULL).

A NULL-terminated version is available as XmlDomGetAttrURI which returns the URI as NULL-terminated string. If the backing store is known to be XMLType, then the attribute's data will be stored internally as length-encoded. Using the length-based Get functions will avoid having to copy and NULL-terminate the data.

If both the input buffer is non-NULL and the input buffer length is nonzero, then the value will be stored in the input buffer. Else, the implementation will return its own buffer.

If the actual length is greater than buflen, then a truncated value will be copied into the buffer and len will return the actual length.


Syntax
oratext* XmlDomGetAttrURILen(
   xmlctx *xctx, 
   xmlattrnode *attr, 
   oratext *buf, 
   ub4 buflen, 
   ub4 *len)

Parameter In/Out Description
xctx
IN
XML context
attr
IN
attribute node
buf
IN
input buffer; optional
buflen
IN
input buffer length; optional
len
OUT
length of URI, in characters


Returns

(oratext *) attribute's namespace URI [data encoding] or NULL


XmlDomGetAttrValue

Returns the "value" (character data) of an attribute (in the data encoding) as NULL-terminated string. Character and general entities will have been replaced.

A length-encoded version is available as XmlDomGetAttrValueLen which returns the attribute value as a pointer and length, for use if the data is known to use XMLType backing store.


Syntax
oratext* XmlDomGetAttrValue(
   xmlctx *xctx, 
   xmlattrnode *attr)

Parameter In/Out Description
xctx
IN
XML context
attr
IN
attribute node


Returns

(oratext *) attribute's value


XmlDomGetAttrValueLen

Returns the "value" (character data) of an attribute (in the data encoding) as length-encoded string. Character and general entities will have been replaced.

A NULL-terminated version is available as XmlDomGetAttrValue which returns the attribute value as NULL-terminated string. If the backing store is known to be XMLType, then the attribute's data will be stored internally as length-encoded. Using the length-based GetXXX functions will avoid having to copy and NULL-terminate the data.

If both the input buffer is non-NULL and the input buffer length is nonzero, then the value will be stored in the input buffer. Else, the implementation will return its own buffer.

If the actual length is greater than buflen, then a truncated value will be copied into the buffer and len will return the actual length.


Syntax
oratext* XmlDomGetAttrValueLen(
   xmlctx *xctx,
   xmlattrnode *attr,
   oratext *buf,
   ub4 buflen, 
   ub4 *len)

Parameter In/Out Description
xctx
IN
XML context
attr
IN
attribute node
buf
IN
input buffer; optional
buflen
IN
input buffer length; optional
len
OUT
length of attribute's value, in characters


Returns

(oratext *) attribute's value


XmlDomGetAttrValueStream

Returns the large "value" (associated character data) for an attribute and sends it in pieces to the user's output stream. For very large values, it is not always possible to store them [efficiently] as a single contiguous chunk. This function is used to access chunked data of that type.


Syntax
xmlerr XmlDomGetAttrValueStream(
   xmlctx *xctx,
   xmlnode *attr,
   xmlostream *ostream)

Parameter In/Out Description
xctx
IN
XML context
attr
IN
attribute node
ostream
IN
output stream object


Returns

(xmlerr) numeric error code, 0 on success


XmlDomGetOwnerElem

Returns the Element node associated with an attribute. Each attr either belongs to an element (one and only one), or is detached and not yet part of the DOM tree. In the former case, the element node is returned; if the attr is unassigned, NULL is returned.


Syntax
xmlelemnode* XmlDomGetOwnerElem(
   xmlctx *xctx,
   xmlattrnode *attr)

Parameter In/Out Description
xctx
IN
XML context
attr
IN
attribute node


Returns

(xmlelemnode *) attribute's element node [or NULL]


XmlDomSetAttrValue

Sets the given attribute's value to data. If the node is not an attribute, does nothing. Note that the new value must be in the data encoding! It is not verified, converted, or checked. The attribute's specified flag will be TRUE after setting a new value.


Syntax
void XmlDomSetAttrValue(
   xmlctx *xctx,
   xmlattrnode *attr,
   oratext *value)

Parameter In/Out Description
xctx
IN
XML context
attr
IN
attribute node
value
IN
new value of attribute; data encoding


See Also:

XmlDomGetAttrValue


XmlDomSetAttrValueStream

Sets the large "value" (associated character data) for an attribute piecemeal from an input stream. For very large values, it is not always possible to store them efficiently as a single contiguous chunk. This function is used to access chunked data of that type.


Syntax
xmlerr XmlDomSetAttrValueStream(
   xmlctx *xctx,
   xmlnode *attr,
   xmlistream *istream)

Parameter In/Out Description
xctx
IN
XML context
attr
IN
attribute node
isream
IN
input stream


Returns

(xmlerr) numeric error code, 0 on success