Programming Reference: ODObjectIterator

# Programming Reference

## ODObjectIterator

Class Definition File | ObjctItr.idl
Class C++ Binding | ObjctItr.xh

Class Hierarchy

    SOMObject
       ODObject
          ODObjectIterator

Description

An object of the ODObjectIterator class provides access to the entries of an object name space.

You use an object iterator to apply an operation to all entries of an object name space. For example, you might use an object iterator to compile a complete list of all the part editors that support certain part types.

Your part creates an object iterator object by calling the object name space's CreateIterator method, which returns a reference to an object iterator object. The iterator performs an unordered traversal of the name space.

While you are using an object iterator, you should not modify or delete the name space. You must postpone adding entries to or removing entries from the name space until after you have deleted the iterator.

For information related to object name spaces, see the class description for ODObjectNameSpace. For more information on accessing objects through iterators, see the chapter on OpenDoc runtime features in the OpenDoc Programming Guide.

Methods

The methods defined by the ODObjectIterator class include:

- First
- IsNotComplete
- Next

Overridden Methods | There are no methods overridden by the ODObjectIterator class.

### First

This method begins the iteration and returns the first entry in the name space.

Signature

    void First (ODISOStr *key,
                ODObject **object,
                ODULong *objectLength)

Parameters

key (ODISOStr *) - output

  A pointer to an ISO string representing the first key in the first entry in the name space or kODNULL for an empty name space.

object (ODObject **) - output

  A reference to the object in the first entry in the name space.

objectLength (ODULong *) - output

  The actual size, in bytes, of the specified object.

Returns

None.

Remarks

Your part must call this method before calling the object iterator's IsNotComplete method for the first time. This method can be called multiple times. However, each call resets the iteration.

It is the caller' responsibility to deallocate the key ISO string when this string is no longer needed. You do not need to allocate or deallocate any memory for the object object.

Exception Handling

kODErrIteratorOutOfSync | The name space was modified while the iteration was in progress.

### IsNotComplete

This method indicates whether the iteration is incomplete.

Signature

    ODBoolean IsNotComplete ()

Parameters

None.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the iteration is incomplete.

  kODTrue | The iteration is incomplete.
  kODFalse | The iteration is complete.

Remarks

Your part calls this method to test whether more entries remain in the name space. This method returns kODTrue if the preceding call to the First or Next method found an entry. This method returns kODFalse when you have examined all the entries (that is, when the previous call to First or Next returned kODNULL). If the name space is emtpy, this method returns kODFalse.

Exception Handling

kODErrIteratorNotInitialized | This method was called before calling the First or Next method to begin the iteration.
kODErrIteratorOutOfSync | The name space was modified while the iteration was in progress.

### Next

This method returns the next entry in the name space.

Signature

    void Next (ODISOStr *key,
               ODObject **object,
               ODULong *objectLength)

Parameters

key (ODISOStr *) - output

  A pointer to an ISO string representing the key in the next entry in the name space or kODNULL if you have reached the end of the name space.

object (ODObject **) - output

  A reference to the object in the next entry in the name space.

objectLength (ODULong *) - output

  The actual size, in bytes, of the specified object.

Returns

None.

Remarks

If your part calls this method before calling this object iterator's First method to begin the iteration, then this method works the same as calling the First method.

It is caller' responsibility to deallocate the ISO string when it is no longer needed. You do not need to allocate or deallocate any memory for the object parameter.

Exception Handling

kODErrIteratorOutOfSync | The collection was modified while the iteration was in progress.

[ Top | Previous | Next | Contents | Index | Documentation Homepage ]