Programming Reference: ODValueIterator

# Programming Reference

## ODValueIterator

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

Class Hierarchy

    SOMObject
       ODObject
          ODValueIterator

Description

An object of the ODValueIterator class provides access to the entries of a value name space.

You use a value iterator to apply an operation to all entries of a value name space. For example, you might use a value iterator to iterate over a list of part editors to obtain information about each part editor, such as the part's supported part kinds.

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

While you are using a value 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 more information related to value name spaces, see the class description for ODValueNameSpace. 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 ODValueIterator class include:

- First
- IsNotComplete
- Next

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

### First

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

Signature

    void First (ODISOStr *key,
                ODByteArray *value)

Parameters

key (ODISOStr *) - in/out

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

value (ODByteArray *) - in/out

  A byte array whose buffer contains the value for the first entry in the name space.

Returns

None.

Remarks

Your part must call this method before calling this value iterator's IsNotComplete method for the first time. This method may be called multiple times. Each call resets the iteration.

The caller must deallocate the ISO string and byte array structure (and its buffer) when they are no longer needed.

Exception Handling

kODErrIteratorOutOfSync | The name space was modified during the iteration.

### 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 empty, this method always 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 during the iteration.

### Next

This method returns the next entry in the name space.

Signature

    void Next (ODISOStr *key,
               ODByteArray *value)

Parameters

key (ODISOStr *) - in/out

  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.

value (ODByteArray *) - in/out

  A byte array whose buffer contains the value for the next entry in the name space.

Returns

None.

Remarks

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

The caller must deallocate the ISO string and byte array structure (and its buffer) when they are no longer needed.

Exception Handling

kODErrIteratorOutOfSync | The name space was modified during the iteration.

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