Reading the object model diagrams: Interfaces and members [转载]

In this topic

1. Interface inheritance
2. Inbound interfaces
3. Outbound interfaces
4. Interface members

---

Interfaces are the access points for development with COM objects. There are inbound interfaces, which expose the properties and methods of a class, and outbound interfaces, which allow the class to interact with other classes.

A detailed discussion of COM and the IUnknown interface can be found in the topic Introduction to COM.

---

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 IGeometryinterface.

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 GxViewclass, you don't need to implement the IGxViewPrint interface to be a GxView class; however, you do need to implement theIGxView 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".

[Visual Basic 6]

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

[Visual Basic 6]

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.

[Visual Basic 6]

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.

[Visual Basic 6]

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 6, declare the variable as follows:

[Visual Basic 6]

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.

[Visual Basic 6]

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

In the example below, the abstract class Name implements the IName interface; its inheritance relationship to all other name objects indicates that they each implement the IName interface as well. Although neither theFeatureClassName nor WorkspaceName coclass shows the IName interface in the diagrams, you know it is there because of this inheritance. The Open() method on the IName interface is used to instantiate the FeatureClassobject. This usage guarantees that the new FeatureClass object is properly created and includes all necessary information.

The Name abstract class, WorkspaceName and Tablename coclasses, and FeatureClass objects and their relationships

The case below illustrates its importance clearly: opening a shapefile dataset to extract a feature class is not as simple as just reading the database records.

[Visual Basic 6]

Dim pwrkspc As IWorkspaceName
Set pwrkspc = New WorkspaceName
pwrkspc.PathName = "D:\data\canada"
pwrkspc.WorkspaceFactoryProgID = _ "esriDataSourcesFile.shapefileworkspacefactory.1"
'***************************************************
Dim pdatasetname As IDatasetName
Set pdatasetname = New FeatureClassName
pdatasetname.Name = "Canada.dbf"
Set pdatasetname.WorkspaceName = pwrkspc
Dim pname As IName
Set pname = pdatasetname
Dim pfeatclass As IFeatureClass
Set pfeatclass = pname.Open
''Check FeatureType property to ensure you have a featureclass object
MsgBox pfeatclass.FeatureType

An association is shown in the code above where the WorkspaceName object was set to the WorkspaceNameproperty of the FeatureClassName object. As noted earlier, for simplicity's sake, many of the associations in ArcObjects aren't drawn on the diagrams. In fact, this association between the WorkspaceName andFeatureClassName classes isn't shown on the GeoDatabase library object model diagram; however, it can be seen in the IName interface detail for the WorkspaceName property since the symbol used is a Property Put by Reference. Since the WorkspaceName class is being held as a reference and not in a composition relationship, the object's lifespan will not be controlled by the FeatureClassName object. If you were to use the code below to set the FeatureClassName object to nothing, the WorkspaceName class would still exist.

[Visual Basic 6]

Set pfeatclass = Nothing If Not pwrkspc Is Nothing Then
    MsgBox "Object still exists"
End If