ReplaceDestCollection
Purpose
The CMetaObject class ReplaceDestCollection function replaces the collection with Ids in the specified list (lDestIDs or destRelList) by adding the IDs in the list not in the collection; removing IDs from the collection that are not in the specified list.
Description
The relationship id is specified by the GUID relationship id or internal relationship id (one of which must be set).
ReplaceDestCollection only modifies the collection of the current version of the CMetaObject, and it only uses the current version of each object in the lDestIDs or destRelList list. If necessary, RemoveFromDestCollection will determine the current version for the CMetaObject and each entry in lDestIDs or destRelList.
When destRelList is specified, only the origin loid and explanation from each entry are used; the other fields are ignored.
If the destination class of the relationship is a superclass, this function will replace only the collections for classes of objects on the replace list. Note the example in Figure 25.
Figure 25: ReplaceDestCollection Function ExampleThe replace list contains object IDs for M2, N1, and N3. The collection of object A1 with ClassM objects is replaced with M2. The collection of object A1 with ClassN objects is replaced with N1 and N3. The collection of object A1 with ClassO objects is not affected as there are no ClassO objects on the replace list. To remove all objects from a collection use the RemoveAllFromDestCollection2 function.
Requirements
The internal object id must be set in the object and it must be for a version of the object. Each object id in lDestIDs must be for a version of an object.
Syntax
HRESULT ReplaceDestCollection(
const LLOBJECTID_t &destIDList,
const GUID &gRelID,
const OBJECTID_t lRelID = NULLLOID);
HRESULT ReplaceDestCollection(
const vector<CMetaRelationship> &destRelList,
const GUID &gRelID,
const OBJECTID_t lRelID = NULLLOID);
Argument |
In/Out |
Description |
IDestIDs |
In |
List of objectIDs to be set in the destination collection; if necessary, they will be adjusted to the current version of each associated object. |
destRelList |
In |
List of destination IDs and explanatory strings to be set in the destination collection; if necessary, they will be adjusted to the current version of each associated object |
gRelID |
In |
Relationship ID |
lRelID |
In |
Internal Relationship ID optional unless gRelID is NULLGUID |