ESRI XML PropertySet object.
Product Availability
Supported Platforms
Extended Error Information
Use the ISupportErrorInfo method InterfaceSupportsErrorInfo to determine if the object supports extended error information. If the object supports extended error info, VC++ developers should use the OLE/COM IErrorInfo interface to access the ErrorInfo object. Visual Basic developers should use the global error object Err to retrieve this extended error information.
Interfaces
| Interfaces | Description |
|---|---|
| IClone (esriSystem) | Provides access to members that control cloning of objects. |
| IPersistStreamInit (esriGeoDatabase) | Supports initialized stream-based persistence, regardless of whatever else the object does. |
| IPropertySet (esriSystem) | Provides access to members for managing a PropertySet. |
| ISupportErrorInfo | Indicates whether a specific interface can return Automation error objects. |
| IXmlPropertySet | Provides access to members that manage metadata. |
| IXmlPropertySet2 | Provides access to members that manage metadata. |
| IXMLSerialize (esriSystem) | Provides access to members that XML serialize and deserialize an object to/from XML. |
Remarks
Creating a
new XmlPropertySet
When a
new XmlPropertySet is created, it contains no XML header or
document elements (the exception to this is in VB6 and VBA,
see below). Attempting to use a newly-created XmlPropertySet in
almost any way will raise an error until the header and root
element are added. There are three ways to do
this:
Call the IXmlPropertySet2.InitGeneric method, with the rootName parameter as "metadata".Call the IXmlPropertySet2.SetXml method, with the xml parameter as a string containing a header and a root node.Use the IXMLSerialize or IPersistStreamInit interfaces to pull data into the property set.
Using the
IPropertySet interface on an
XmlPropertySet
Accessing an instance
of the XmlPropertySet class through the IPropertySet interface
varies slightly from the interface's typical use. In a typical
property set, there is a 1:1 relationship between properties and
values, but because metadata can contain multiple occurrences of a
property, the relationship between properties and values in an
XmlPropertySet is 1:N. This has an effect on the types of objects
returned through the outbound parameters of methods such as
GetProperty and GetProperties. The following paragraphs describe
the differences in the behavior of each member between a typical
property set and an XmlPropertySet containing
metadata.
One note
that applies to all "getter" methods on this interface is that
binary enclosures of type Picture will not be returned as text
values, but as IPicture references. Binary enclosures of type Image
or Base64 will be extracted to the current user's temporary
directory, and a path to the temporary file will be the property's
value.
Count:
In a typical property set, this returns the total number of
properties. When called on an XmlPropertySet, it returns the number
of top-level elements. In a metadata document, this will always be
one, the Metadata element.
GetAllProperties:
An XmlPropertySet's implementation of this method behaves similar
to that of a regular property set. Each leaf node is returned as an
element in the returned arrays, with the array of names containing
the semi-qualified name of each property ("/Metadata" is
omitted).
GetProperties:
In a typical property set, an array containing strings is provided
to this method, and the variant passed to the values parameter is
populated with the corresponding values, as strings. Due to the 1:N
relationship between properties and values in an XmlPropertySet,
however, the values variant does not return an array of strings,
but rather a jagged two-dimensional array (an array of arrays) that
contain strings. For example, if an array containing a single
string, "idinfo/keywords/theme/themekey", was passed to this
method, the outbound values parameter would contain an array with a
single element, an array of strings. That array would (for many
datasets) contain several strings. See this coclass' associated
code for a concrete example of this.
Although
the names parameter of this method accepts a variant, it must
actually be an array of strings (not a variant containing strings),
or an error will occur.
This
method accepts XSL patterns as valid input strings. If a provided
XSL pattern matches multiple properties, the values of these
properties will all be returned within a single array in the
outbound values parameter. For example, passing an array with the
string "*" into the names parameter would return an array with a
single "inner" array, with the inner array would contain all
top-level elements. See this coclass' associated code for a
concrete example of this.
GetProperty:
As with GetProperties, the 1:N relationship between properties and
values has an effect on the outbound variant parameter of this
method. Rather than returning a string, as is the case with typical
property sets, an array of strings is returned (one string for each
matching property). Also similar to GetProperties, an XSL pattern
can be provided as name parameter, with all of the matching
properties' values being returned in the values
array.
IsEqual:
Normally used to compare property sets, this method will always
return false when called on an XmlPropertySet, regardless of
whether or not the property sets being compared are
equal.
RemoveProperty:
This method accepts XSL patterns as valid input, meaning that
multiple properties can be deleted with a single call. If deleting
a single instance of a property (where there are multiple
occurrences) is intended, a value or attribute filter can be
applied to the property's name, or an indexer may be used. If the
specified property is a node containing other properties, all of
the sub-nodes will also be removed.
SetProperties:
This method accepts a string array (containing property names or
XSL patterns) and a variant containing strings, which are the
values the properties (or all properties matching the provided
pattern) should be set to. Unlike GetProperties, which retrieves a
jagged two-dimensional array of strings as its values parameter,
this method must be given a simple array of strings, and any
specified properties or patterns with multiple occurrences are
assigned the same value.
SetProperty:
Calling this method on an XmlPropertySet is equivalent to calling
IXmlPropertySet.SetPropertyX, with the propType parameter set to
esriXPTText, the action parameter set to esriXSPAAddOrReplace, and
the syncing parameter set to False. For more information, see the
IXmlPropertySet.SetPropertyX documentation.