A collection can contain any number of objects. It can even contain objects of different types. This object is used by this API to return collections of data to the user (or to set a number of objects at once).
This object contains an enumerator. Using this enumerator you can easily walk through the collection, for instance in VBScript:
' We presume objUsers contains a collection of users Dim objUser For Each objUser in objUsers MsgBox objUser Next
It is also possible to return a certain element from a collection using the Item method. Note that the index that should be passed to the item method may not hold a continous rang, it depends on what items are stored in the collection. For instance the collection of IProximityReader objects returned by the IReaderNetwork::Readers property, should be indexed using the address of the reader, in VBScript, to return the reader at address 7:
' We presume objNetwork contains a valid network object Dim objReader Set objReader = objNetwork.Readers(7) If IsObject(objReader) Then MsgBox "Found reader at address 7, reader name: " & objReader Else MsgBox "No reader found at address 7" End If
There are a number of properties in this object that can be used to enumerate through collection. Use the FirstItem, NextItem to enumerate forwards. To enumerate backwards, use the LastItem and PreviousItem. Use the CurrentItem and CurrentIndex to return the current position when enumerating through the collection.
Using the Merge method it is possible to merge all items from another ICollection object into this collection.
Items can be added using the Add method or the Insert method, and can be removed using the Remove method.
Use the Count property to determine the current number of items in this collection.
This interface also contains a useful Sort method that can be used to sort an entire collection at once, any property of the contained objects can be used as sort index.
Public Member Functions | |
HRESULT | Add ([in] VARIANT Item) |
Add a new item to the end of this collection. | |
HRESULT | Insert ([in] VARIANT Index,[in] VARIANT Item) |
Insert a new item into this collection. | |
HRESULT | Remove ([in] VARIANT Index) |
Remove an item from the collection. | |
HRESULT | Count ([out, retval] long *plCount) |
Returns the number of items in this collection. | |
HRESULT | Item ([in] VARIANT Index,[out, retval] VARIANT *pvtItem) |
This method retrieves an item from the collection using its index. | |
HRESULT | Clear () |
This method clears the entire collection. | |
HRESULT | FirstItem ([out, retval] VARIANT *pvtItem) |
This method returns the first item from this collection. | |
HRESULT | NextItem ([out, retval] VARIANT *pvtItem) |
This method returns the next item from this collection. | |
HRESULT | CurrentItem ([out, retval] VARIANT *pvtItem) |
This method returns the current item from this collection. | |
HRESULT | CurrentIndex ([out, retval] VARIANT *pvtItem) |
This method returns the index of the current item of this collection. | |
HRESULT | LastItem ([out, retval] VARIANT *pvtItem) |
This method returns the last item in this collection. | |
HRESULT | PreviousItem ([out, retval] VARIANT *pvtItem) |
This method returns the previous item in this collection. | |
HRESULT | Merge ([in] ICollection *pintfCollection) |
Merge another collection into this collection. | |
HRESULT | Sort ([in] VARIANT_BOOL fAscending,[in, defaultvalue(0)] VARIANT vtDispID,[out, retval] ICollection **ppintfSortedCollection) |
Sort this collection. |
|
Add a new item to the end of this collection. This method uses an internal number as the new index for new value.
|
|
Insert a new item into this collection.
|
|
Remove an item from the collection. This method removes an item from this collection.
|
|
Returns the number of items in this collection.
|
|
This method retrieves an item from the collection using its index.
|
|
This method clears the entire collection.
|
|
This method returns the first item from this collection. Use in combination with NextItem. When there are no items in the collection, this method will return S_FALSE and return an empty pvtItem parameter.
|
|
This method returns the next item from this collection. Use in combination with FirstItem. When the end of the collection is reached, this method will return S_FALSE and return an empty pvtItem parameter.
|
|
This method returns the current item from this collection. When looping through the collection using FirstItem and NextItem, this property can be use to retrieve the current item. Use in combination with FirstItem, NextItem, LastItem, PreviousItem.
|
|
This method returns the index of the current item of this collection. When looping through the collection using FirstItem and NextItem, this property can be use to retreive the index of the current item. Use in combination with FirstItem, NextItem, LastItem, PreviousItem.
|
|
This method returns the last item in this collection. Use in combination with PreviousItem to walk backwards through the collection. When the collection is empty, this method will return S_FALSE and return an empty pvtItem parameter.
|
|
This method returns the previous item in this collection. Use in combination with LastItem to walk backwards through the collection. When the current item in the collection is the first item and this method is called, this method will return S_FALSE and return an empty pvtItem parameter.
|
|
Merge another collection into this collection. All items of the new collection will be added to the collection using the Add method, see the documentation of the Add method for more information.
|
|
Sort this collection. This method can sort an entire collection either ascending or descending. It returns the sorted collection. Since the collection can contain objects (of different types), a property of the object(s) can be used as sort index. When sorting for instance a collection of users by name, use the following syntax (VB): ' We presume objUsers contains a collection of users Dim objSortedUsers objSortedUsers = objUsers.Sort(true, "Name") Sorting readers by network address descending (VB): ' We presume objReaders contains a collection of readers Dim objSortedReaders objSortedReaders = objReaders.Sort(false, "NetworkAddress")
|