Managed Object - PropertyCollector

Property of: ServiceContent
See also: ObjectContent, PropertyFilter, PropertyFilterSpec, UpdateSet

Managed Object Description

PropertyCollector is the managed object type that clients use to retrieve a set of properties from one or more managed objects. Clients can also use the PropertyCollector to determine when any of the properties have changed. The change detection mechanism supports both polling and notification to detect property changes.

Polling is supported with the CheckForUpdates method.
Notification is supported with the WaitForUpdates method.

To decrease network traffic when collecting updates, a client creates one or more property collector filters to specify the parts of a managed object in which the client is interested.

All property collector state information is session-specific:

A client cannot share its property collector filters with other clients.
When a session terminates, the associated property collector filters are automatically destroyed.

Properties

Name	Type	Description
filter* P	ManagedObjectReference[] to a PropertyFilter[]	The filters that this property collector uses to determine the list of properties to retrieve and observe for changes.

*May not be presentP Required privilege: System.View

Methods

Methods defined in this Managed Object
CancelWaitForUpdates, CheckForUpdates, CreateFilter, RetrieveProperties, WaitForUpdates

CancelWaitForUpdates

Cancels an outstanding WaitForUpdates, if any. The outstanding waitForUpdates operation completes by throwing the Canceled fault.

Required Privileges: System.View

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the PropertyCollector used to make the method call.

Return Value

Type	Description
None

Faults

Type	Description
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="CancelWaitForUpdates" type="vim25:CancelWaitForUpdatesRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="CancelWaitForUpdatesResponse">
            <complexType/>
         </element>

CheckForUpdates

Checks for updates on properties specified by the union of all current filters. If no updates are pending, this method returns null.

The return value contains the changes between the previous version and the current values of the properties. The result includes a new version string the client passes in order to receive further updates.

Required Privileges: System.View

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the PropertyCollector used to make the method call.
version*	xsd:string	The data version currently known to the client. The value must be either the special initial version (an empty string), or a data version string that was returned from a previous call to CheckForUpdates or WaitForUpdates.

*Need not be set

Return Value

Type	Description
UpdateSet	Changes since the last updated version. If no updates are pending, then this method returns null.

Faults

Type	Description
InvalidCollectorVersion	Thrown if the version string is out-of-date or invalid.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="CheckForUpdates" type="vim25:CheckForUpdatesRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="CheckForUpdatesResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim25:UpdateSet" minOccurs="0"/>
               </sequence>
            </complexType>
         </element>

CreateFilter

Creates a new filter for the given set of managed objects.

Required Privileges: System.View

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the PropertyCollector used to make the method call.
spec	PropertyFilterSpec	The specifications for the filter.
partialUpdates	xsd:boolean	Flag to specify whether a change to a nested property should report only the nested change or the entire specified property value. If the value is true, a change should report only the nested property. If the value is false, a change should report the enclosing property named in the filter.

Return Value

Type	Description
ManagedObjectReference to a PropertyFilter	A reference to the new filter.

Faults

Type	Description
InvalidArgument	Thrown if any of the following is true: "spec" is empty. "spec" contains a selection with properties not defined on its type.
InvalidProperty	Thrown if "spec" has a property that is not defined on one of the objects.
InvalidType	Thrown if "spec" contains, directly or indirectly, a type name that does not refer to a known type.
ManagedObjectNotFound	Thrown if "spec" refers to objects that are not present on the server
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="CreateFilter" type="vim25:CreateFilterRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="CreateFilterResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim25:ManagedObjectReference"/>
               </sequence>
            </complexType>
         </element>

RetrieveProperties

Retrieves the specified properties of the specified managed objects.

This method is equivalent to creating a filter for the given objects and property specification set, then receiving the property values, and finally destroying the filter. If you want to monitor the contents of an object, you should use either CheckForUpdates or WaitForUpdates.

Required Privileges: System.Anonymous

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the PropertyCollector used to make the method call.
specSet	PropertyFilterSpec[]	The specifications for the properties to retrieve.

Return Value

Type	Description
ObjectContent[]	The data contents of the specified objects.

Faults

Type	Description
InvalidArgument	Thrown if any of the following is true: "specSet" is empty. "specSet" contains a selection with properties not defined on its type.
InvalidProperty	Thrown if "specSet" has a property not defined on one of the objects.
InvalidType	Thrown if "specSet" contains, directly or indirectly, a type name that does not refer to a known type.
ManagedObjectNotFound	Thrown if "specSet" refers to objects that are not present on the server
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="RetrieveProperties" type="vim25:RetrievePropertiesRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="RetrievePropertiesResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim25:ObjectContent" minOccurs="0" maxOccurs="unbounded"/>
               </sequence>
            </complexType>
         </element>

WaitForUpdates

Waits for updates on properties specified by the union of all current filters. Unlike checkForUpdates, this method waits until updates are available before it completes.

Required Privileges: System.View

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the PropertyCollector used to make the method call.
version*	xsd:string	The data version currently known to the client. The value must be either the special initial version (an empty string), or a data version string that was returned from a previous call to CheckForUpdates or WaitForUpdates.

*Need not be set

Return Value

Type	Description
UpdateSet	Changes since the last updated version.

Faults

Type	Description
InvalidCollectorVersion	Thrown if the version string is out-of-date or invalid.
RequestCanceled	Thrown if CancelWaitForUpdates has been called or another WaitForUpdates has been issued.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="WaitForUpdates" type="vim25:WaitForUpdatesRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="WaitForUpdatesResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim25:UpdateSet"/>
               </sequence>
            </complexType>
         </element>