Esri XML PropertySet object.
Supported Platforms
Windows, Solaris, Linux
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 | |
| IPropertySet (esriSystem) | Provides access to members for managing a PropertySet. |
| ISupportErrorInfo (esriSystem) | |
| 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. 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.