IDSSPropertyGroup Interface Reference

Inherited by IDSSPropertyGroup2.

List of all members.

---

Detailed Description

The COM API has a DSS Property concept.

This concept is used to bind multiple values to objects, where the values have no direct significance to the COM API. These properties are grouped together into property sets. Each property lists a set of 'property groups' to which the property belongs. Each property group represents a type (or several types) of DSS Object. This interface is used to present the collection of all property sets that contain properties that belong to a particular property group.

We have several implementations of the IDSSPropertyGroup interface:

• It is the type specific interface of a first class object DSSPropertyGroup. There are exactly 32 of these objects, one of each property group. They have fixed ObjectIDs. The object server will pre-load these objects as part of the schema. These objects are used to cache the property group to property set relationship. There is no need to store objects in the metadata that correspond to these property groups. The metadata server can fabricate them on demand by doing a specialized search of all the property sets in the metadata. We call this the design time usage of the interface. There is no reason for either a user, or a designer to ever ask to see these objects.
• The IDSSObjectInfo interface exposes an IDSSPropertyGroup interface to present the collection of property sets for each instance of a DSS Object. A user uses these to assign values to the properties in the property sets. We call this the application time usage of the interface.
• The IDSSLink interface exposes the collection to allow a user to specify the property sets in a link object. This is the only situation in which we allow a user to modify the contents of the collection. This is effectively a design time usage.
• The IDSSLinkItem exposes the collection to allow a user to set the property set objects on a link item. A user uses these to assign values to the link items. This is also an application time usage of the interface.

At design time only the MDS needs to put property sets in the property group, and it always does so using all of the relevant property sets in the metadata. At application time a user is only able to assign values to properties; she cannot amend which properties are available.

The interface doesn't even have an Info property. This is by design. As a first class object the DSSPropertyGroup does have an IDSSObjectInfo, since all first class objects must have one. Since it is of no use, accept in serializing the object, we have chosen not to emphasize its existence to the user. This means that we do not provide a property to access the interface.

See the document Usage of Properties for details on how IDSSPropertyGroup interacts with other interfaces.

Public Member Functions
HRESULT	_NewEnum ([out, retval] IUnknown pp_NewEnum)
	Enumerator for this collection.
HRESULT	Add ([in] IDSSPropertySet *pPropertySet)
	Add a single property set to the property group.
HRESULT	Clear ()
	Remove all property sets from the property group.
HRESULT	Count ([out, retval] Int32 *pCount)
	The number of properties in this property group.
HRESULT	Item ([in] VARIANT *pIndex,[out, retval] IDSSPropertySet ppPropertySet)
	Access members of the collection.
HRESULT	Remove ([in] VARIANT *pIndex)
	Remove a specific property set from the property group.

---

Member Function Documentation

HRESULT IDSSPropertyGroup::_NewEnum (  [out, retval] IUnknown   pp_NewEnum  )

Enumerator for this collection. This is the standard property used to return the objects in a collection. It returns an enumerator object. Calling methods on the enumerator object retrieves the contents of the collection. After the enumerator object has been obtained it is possible for both the members of the collection to change. The effect of this change on the members of the collection that are returned by the enumeration object is implementation dependent. Note that the user doesn't retrieve the contents of the collection until he or she calls the Next method on the enumerator object. This property does not presuppose that all of the objects are retrieved simultaneously. Parameters: pp_NewEnum  An IUnknown pointer to the enumerator object. The object is returned using the standard IEnumVARIANT interface. Returns: Usual COM result code: S_OK

HRESULT IDSSPropertyGroup::Add (  [in] IDSSPropertySet *  pPropertySet  )

Add a single property set to the property group. Add a property set to the property group. The only time we permit a user to edit the group is when it is exposed from a link object to show the property sets supported by the link. Even in this case the collection can only be changed if the user has yet to insert any link items into the link object. Returns: Usual COM result code: S_OK DSSCOM_E_READONLY This property group cannot be amended. OBJSVR_E_LINK_NON_EMPTY This property group cannot be changed because the link already contains link items.

HRESULT IDSSPropertyGroup::Clear (   )

Remove all property sets from the property group. Clear is a method. It removes all of the property sets from this property group. The only time we permit a user to edit the group is when it is exposed from a link object to show the property sets supported by the link. Even in this case the collection can only be changed if the user has yet to insert any link items into the link object. Returns: Usual COM result code: S_OK DSSCOM_E_READONLY This property group cannot be amended. OBJSVR_E_LINK_NON_EMPTY This property group cannot be changed because the link already contains link items.

HRESULT IDSSPropertyGroup::Count (  [out, retval] Int32 *  pCount  )

The number of properties in this property group. Returns the number of Property Sets in the collection. Parameters: pCount  The number of properties in the collection. Returns: Usual COM result code: S_OK

HRESULT IDSSPropertyGroup::Item (  [in] VARIANT *  pIndex, [out, retval] IDSSPropertySet   ppPropertySet )

Access members of the collection. This is the default method of the interface. Return a DSSPropertySet from the collection. The property can be identified by Name of the property set, by pointer to the property set, or by index number of the set into the property group. As usual in DSS COM we begin index numbers from 1. We allow a user to look up the property set by name. However since property sets are created independently we do not enforce that the name uniquely identifies a property set, so this call may fail. Parameters: pIndex  Number = Index number of the property set into this group. String = Name of the desired property set. Pointer = Look up the property set by ObjectID of this object. ppPropertySet  The requested member of the collection. NULL if none was found. Returns: Usual COM result code: S_OK E_INVALIDARG pIndex is NULL DSSCOM_E_AMBIGUOUS_NAME Two property sets have the same name DSSCOM_E_INDEX_OUT_OF_RANGE Index number is not in range DSSCOM_E_KEY_NOT_FOUND Name does not describe property DSSCOM_E_BAD_ITEM_SPEC Unexpected Variant type DSSCOM_E_OBJECT_NOT_FOUND Pointer is not an object in this collection

HRESULT IDSSPropertyGroup::Remove (  [in] VARIANT *  pIndex  )

Remove a specific property set from the property group. Remove is a method. It removes a property set from the property group. The property set, like the Item method, can be identified by index number, name or pointer. The only time we permit a user to edit the group is when it is exposed from a link object to show the property sets supported by the link. Even in this case the collection can only be changed if the user has yet to insert any link items into the link object. We allow a user to look up the property set by name. However since property sets are created independently we do not enforce that the name uniquely identifies a property set, so this call may fail. Parameters: pIndex  Number = Index number of the property set into this group. String = Name of the desired property set. Pointer = Look up the property set by ObjectID of this object. Returns: Usual COM result code: S_OK E_INVALIDARG pIndex is NULL. DSSCOM_E_AMBIGUOUS_NAME Two property sets have the same name. DSSCOM_E_INDEX_OUT_OF_RANGE Index number is not in range. DSSCOM_E_KEY_NOT_FOUND Name does not describe property. DSSCOM_E_BAD_ITEM_SPEC Unexpected Variant type. DSSCOM_E_OBJECT_NOT_FOUND Pointer is not an object in this collection. DSSCOM_E_READONLY This property group cannot be amended. OBJSVR_E_LINK_NON_EMPTY This property group cannot be changed because the link already contains link items.

---