IMcObjectRemoveFromCollection Method

Return Value

Type: Int32
The remaining reference count on the object. This should never be zero, since one reference should be necessary to call this method. If it is 1, then any subsequent single Release will delete the object.

This McObject and any descendent McObject's are removed from the McObjects collection but any data held by these objects is not freed. The McObject instance is Released, but the object and its data are only actually deleted when the object's reference count reaches zero. You would typically use this method to convert an McObject that was part of the collection into a "temporary" McObject instance, so that it could be passed off to some other code for final disposition when it was last released (e.g., it might be used as a retval from some method). A call to this method will not delete the refered to object immediately, since the calling application will have bumped the reference count. The object will be deleted only when the last reference to the object is released. After this call, the object will no longer appear in any McObjects enumeration (e.g., a "for each" statement). However, the object is still functional and all of its methods and properties may be accessed. Furthermore, it may still be looked up by name via an McObjects.Item or McObjects.GetCategoryItem, and any attempt to Add a new object with the same name and parent will fail due to the name conflict. Use KillObjectAndChildren if you want to remove an object completely, and free its name and data. Once an object has been removed from the collection, there is no mechanism for putting it back in.