Cross Point


ICollection Interface Reference

List of all members.

Detailed Description

This represents a collection of objects.

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.


Member Function Documentation

ICollection::Add [in] VARIANT  vtItem  ) 
 

Add a new item to the end of this collection.

This method uses an internal number as the new index for new value.

Parameters:
vtItem The item that should be added.
Precondition:
Parameter cannot be NULL

ICollection::Insert [in] VARIANT  vtIndex,
[in] VARIANT  vtItem
 

Insert a new item into this collection.

Parameters:
vtIndex The index (name) of the item to add.
vtItem The item that should be added. This can also be another collection.
Precondition:
Parameter cannot be NULL

ICollection::Remove [in] VARIANT  vtIndex  ) 
 

Remove an item from the collection.

This method removes an item from this collection.

Parameters:
vtIndex The index of the item that should be removed.

ICollection::Count [out, retval] long *  plCount  ) 
 

Returns the number of items in this collection.

Parameters:
plCount Receives the number of items in this collection.
Precondition:
Parameter plCount cannot be NULL.

ICollection::Item [in] VARIANT  vtIndex,
[out, retval] VARIANT *  pvtItem
 

This method retrieves an item from the collection using its index.

Parameters:
vtIndex The index of the item that should be retrieved.
pvtItem Receives the actual item.
Precondition:
Parameter pvtItem cannot be NULL.

ICollection::Clear  ) 
 

This method clears the entire collection.

ICollection::FirstItem [out, retval] VARIANT *  pvtItem  ) 
 

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.

Parameters:
pvtItem Receives the actual item.
Precondition:
Parameter pvtItem cannot be NULL.
See also:
NextItem, CurrentItem, CurrentIndex

ICollection::NextItem [out, retval] VARIANT *  pvtItem  ) 
 

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.

Parameters:
pvtItem Receives the next item in the collection.
Precondition:
Parameter pvtItem cannot be NULL.
See also:
FirstItem, CurrentItem, CurrentIndex

ICollection::CurrentItem [out, retval] VARIANT *  pvtItem  ) 
 

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.

Parameters:
pvtItem Receives the current item.
Precondition:
Parameter pvtItem cannot be NULL
See also:
FirstItem, NextItem, CurrentIndex, LastItem, PreviousItem

ICollection::CurrentIndex [out, retval] VARIANT *  pvtItem  ) 
 

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.

Parameters:
pvtItem Receives the current index.
Precondition:
Parameter pvtItem cannot be NULL.
See also:
FirstItem, NextItem, CurrentItem, LastItem, PreviousItem

ICollection::LastItem [out, retval] VARIANT *  pvtItem  ) 
 

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.

Parameters:
pvtItem Receives the last item in this collection.
Precondition:
Parameter pvtItem cannot be NULL.
See also:
PreviousItem, CurrentItem, CurrentIndex

ICollection::PreviousItem [out, retval] VARIANT *  pvtItem  ) 
 

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.

Parameters:
pvtItem Receives the previous item in the collection.
Precondition:
Parameter pvtItem cannot be NULL.
See also:
FirstItem, CurrentItem

ICollection::Merge [in] ICollection pintfCollection  ) 
 

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.

Parameters:
pintfCollection The collection that should be merged with this collection.
See also:
Add

ICollection::Sort [in] VARIANT_BOOL  fAscending,
[in, defaultvalue(0)] VARIANT  vtDispID,
[out, retval] ICollection **  ppintfSortedCollection
 

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")

Parameters:
fAscending Sort ascending or descending.
vtDispID The property name or DISPID that should be used as sorting index.
ppintfSortedCollection Receives the sorted collection.


© Copyright 2001 - 2006 Cross Point. Generated on Mon Mar 12 16:29:51 2007 Cross Point