ArcGIS Engine Developer Guide

DEVELOPING WITH A RCOBJECTS
Accessing collection elements
When accessing elements of a collection sequentially, it is best to use an enumerator
interface. This provides the fastest method of walking through the collection.
The reason for this is that each time an element is requested by index, internally
an enumerator is used to locate the element. Hence, if the collection is looped
over getting each element in turn, the time taken increases exponentially (y=cx b ).
Enumerator use
When requesting an enumerator interface from an object, the client has no idea
how the object has implemented this interface. The object may create a new
enumerator, or it may decide for efficiency to return a previously created enumerator.
If a previous enumerator is passed to the client, the position of the
element pointer will be at the last accessed element. To ensure that the enumerator
is at the start of the collection, the client should reset the enumerator before
use.
Exception handling is language specific, and since
COM is language neutral, exceptions are not
supported.
Error handling
All methods of interfaces, in other words, methods callable from other objects,
should handle internal errors and signify success or failure via an appropriate
HRESULT. COM does not support passing exceptions out of interface method
calls. COM supports the notion of a COM exception. A COM exception utilizes
the COM error object by populating it with relevant information and returning an
appropriate HRESULT to signify failure. Clients, on receiving the HRESULT,
can then interrogate the COM Error object for contextual information about the
error. Languages, such as Visual Basic, implement their own form of exception
handling. For more information, see the specific section in this chapter for the
language with which you are developing.
Notification interfaces
There are a number of interfaces in ArcObjects that have no methods. These are
known as notification interfaces. Their purpose is to inform the application
framework that the class that implements them supports a particular set of
functionality. For instance, the application framework uses these interfaces to
determine if a menu object is a root-level menu (IRootLevelMenu) or a context
menu (IShortcutMenu).
Client-side storage
Some ArcObjects methods expect interface pointers to point to valid objects
prior to making the method call. This is known as client storage since the client
allocates the memory needed for the object before the method call. Suppose you
have a polygon, and you want to obtain its bounding box. To do this, use the
QueryEnvelope method on IPolygon. If you write the following code:
Dim pEnv As IEnvelope
pPolygon.QueryEnvelope pEnv
you’ll get an error because the QueryEnvelope method expects you (the client) to
create the Envelope. The method will modify the envelope you pass in and return
the changed one back to you. The correct code follows:
72 • ArcGIS Engine Developer Guide