In this topic
A detailed discussion of COM and the IUnknown interface can be found in the topic Introduction to COM for ArcObjects developers.
Interface inheritance
Since interfaces in ArcObjects are COM interfaces, they all inherit from IUnknown, the basis for COM itself. Additionally, as illustrated in the diagrams, some interfaces inherit from other ArcObjects interfaces. If one interface is inherited by another interface, then the members of the initial interface are also members of the inheriting interface. For example, since IPoint inherits from IGeometry, the members of the IGeometry interface are also members of the IPoint interface. This inheritance allows you to access the IPoint interface and use the members of IGeometry directly, without needing to query interface to the IGeometry interface.
IGeometry inherits from IUknown and, in turn, IPoint inherits from IGeometry.
Interface inheritance is used extensively to, in effect, add functionality to existing interfaces. Although the rules of COM dictate that an interface signature, once deployed, can't change, a new interface can be created that inherits from the original interface. For example, the IEditor2 interface extends the IEditor interface with additional members.
Inbound interfaces
Some inbound interfaces are shown on the diagrams with special notations that provide information in addition to the usual list of members.
Interfaces defined in other libraries
If the interface name is prefixed with a library name, such as esriSystem.IName, then the interface is inherited from a library other than the one implementing it. The library name reflects the library in which the interface is defined. In the diagram below, the Name abstract class, an object in the GeoDatabase library, is shown. As shown by the library name prefix, the interface implemented by Name is actually defined in the System library.
The Name abstract class and the interface it implements
Optional interfaces
Some interfaces can be inherited optionally by other classes. For example, abstract classes can have optional interfaces that may be included or excluded from its subclasses. These are designated by the prefix (Optional). If you are creating your own GxView class, you don't need to implement the IGxViewPrint interface to be a GxView class; however, you do need to implement the IGxView interface.
The GxView class includes a number of interfaces that implemented optionally.
As a developer, if you intend to utilize an optional interface, you must verify that the interface was implemented by the object with which you are working. Attempts to access an optional interface that is not implemented will produce the error message "Run-time error '13' ; Type mismatch".
[VBA]
Dim pGxApp As IGxApplication
Set pGxApp = Application
Dim pGxV As IGxView
Set pGxV = pGxApp.TreeView
'Optional interface for GxViews
Dim pGxVP As IGxViewPrint
'Attempting to QI to this will result in a runtime error
Set pGxVP = pGxV
Interfaces implemented in select instances
Some classes have been designed to have varying implementations instead of having multiple classes that inherit from a single base or abstract class. In these cases, certain interfaces are implemented in select instances. For example, the RasterDataset class can be instantiated by different Workspace classes depending on the type of data being accessed. When file-based data is used to instantiate a RasterDataset class, the ITemporaryDataset interface is implemented; however, if ArcSDE software-based data is used to instantiate the RasterDataset class, the IRasterPyramid2 interface is implemented.
The RasterDataset class and the interfaces it implements when instantiated by file-based and ArcSDE software-based data
Interfaces that are implemented in select instances are designated with the prefix (Instance). Attempts to access a selected instance interface that hasn't been implemented will produce a "Run-time error '13' ; Type mismatch".
[VBA]
Dim pWsFact As IWorkspaceFactory
Dim pWs As IRasterWorkspace
Dim pRasterDataset As IRasterDataset
'Open the workspace
Set pWsFact = New RasterWorkspaceFactory
Set pWs = pWsFact.OpenFromFile("D:\data\canada", 0)
'Open the raster dataset
Set pRasterDataset = pWs.OpenRasterDataset("Dem")
'Test if interface is implemented before QI
Dim pTempDS As ITemporaryDataset
If TypeOf pRasterDataset Is ITemporaryDataset Then
Set pTempDS = pRasterDataset
End If
Outbound interfaces
Outbound interfaces, also known as event interfaces, provide notification when a certain event occurs. Interaction with the members of an outbound interface requires that another object exists to catch the event occurrences; this is commonly referred to as an event sink. Event sinks have code that responds when certain events occur, an editing operation, for example. In Visual Basic, the creation of classes that will act as sinks to an outbound interface requires that the outbound interface declaration include the name of the class that implements the interface.
[VBA]
Private WithEvents EditEvents As Editor
Although the object variable has been declared with the class that will be raising the events, it points to nothing. The object variable must be initialized using the Set statement linking it to the existing Editor object.
[VBA]
Public Sub SetEvents()
Dim pID As New UID
pID = "esriEditor.Editor"
Set m_pEditor = Application.FindExtensionByCLSID(pID)
Set EditEvents = m_pEditor
Secondary outbound interfaces (nondefault)
When a class implements more than one outbound event, the secondary interface name is preceded by a classname, (EditEvents2)IEditEvents2 for example, where the classname indicates the name of a Helper class. The Helper class is an artificial coclass that solves the Visual Basic problem with multiple outbound interfaces on an object. When working with a nondefault outbound interface for EditEvents2 in Visual Basic, declare the variable as follows:
[VBA]
Private WithEvents pEditEvents2 As EditEvents2
Editor class contains several outbound interfaces
Interface members
The members of an interface include its properties, which specify the state of an object, and its methods, which perform some action.
Properties are designated as read-only (get), write-only (put), or read_write (get/put). Additionally, the value of a property may be a simple data type, a long for the x-value of a point object, or another class, such as a coordinate system class (GeographicCoordinateSystem, for example) for the SpatialReference property.
Properties and their symbols
Each property on the diagram is listed with the data type required or returned. The symbolization and syntax of properties that can be set with an object will vary based on whether the property is put by value (put) or put by reference. If ObjectG is assigned to a property by value on ObjectM, then ObjectG is contained within ObjectM. When an object is passed by reference, an association is formed between the two objects. This is advantageous because an object can be reused in many associations, using less memory space.
[VBA]
Dim psphere As ISphere
Set psphere = New Sphere
Dim ppoint As IPoint
Set ppoint = New point
psphere.Center = ppoint
Dim pspatref As ISpatialReference
Set pspatref = New GeographicCoordinateSystem
'This won't compile
'psphere.SpatialReference = pspatref
Set psphere.SpatialReference = pspatref