Getting a Pointer to an Object's Interface

Object Identification

Object identification enables the use of COM objects created by disparate groups of developers. To provide a method of uniquely identifying an object class regardless of where it came from, COM uses globally unique identifiers (GUIDs). A GUID is a 16-byte integer value that is guaranteed (for all practical purposes) to be unique across space and time. COM uses GUIDs to identify object classes, interfaces, and other things that require unique identification.

To create an instance of an object, you need to tell COM what the GUID of the object is. While using 16-byte integers for identification is fine for computers, it poses a challenge for the typical developer. So, COM also supports the use of a less precise, textual name called a programmatic identifier (ProgID). A ProgID takes the form:

  application_name.object_name.object_version

Obtaining the Pointer to an Object's Interface

To use the routines generated by the Module Wizard, your application must get a pointer to an object's interface. This pointer is used as the value of the $OBJECT argument, which is the first argument of every interface generated by the Module Wizard.

Typically, your application obtains its first object pointer by calling the COM routine COMCreateObject. COMCreateObject creates a new instance of an object class. COMCreateObject is the generic name of the two subroutines COMCreateObjectByProgID and COMCreateObjectByGUID:

• Use COMCreateObjectByProgID to create Automation objects. It accepts the progID of an object and returns a pointer to the object's IDispatch interface.
• Use COMCreateObjectByGUID to create both COM and Automation objects.

The arguments to COMCreateObjectByGUID are as follows:

• The first argument is a class identifier (CLSID) that uniquely identifies the object's class. The Module Wizard defines a GUID parameter for each class selected from the Type library. These are given the name in the form: CLSID_class-name.
• The second argument allows you to limit the type(s) of server that the call will accept. Most of the time you can use CLSCTX_ALL to accept any type of server.
• The third argument is an interface identifier (IID) that specifies the particular object interface you are requesting:
  
  • To request an Automation interface, use IID_IDispatch.
  • To request a COM interface, the Module Wizard defines a GUID parameter for each interface selected from the type library. These are given a name in the form: IID_interface-name.
• The fourth argument is an output parameter that returns the object's interface pointer.

The COMCreateObjectByProgID and COMCreateObjectByGUID subroutines return an interface pointer of an object that the server has defined as being externally creatable. However, not all objects are externally creatable. Often, a server implements a hierarchy of objects, or object model. COMCreateObject is called to obtain a pointer to an interface of the root object in the hierarchy. Methods and/or properties of the root object are used to obtain pointers to child objects, and so on, down the hierarchy. You can see examples of this in the Autodice, Dlines, and DSbuild Visual Fortran samples.

All objects must implement the IUnknown interface. Every object also implements one or more additional interfaces. You can always get a pointer to any of the object's interfaces from any of the object's interface pointers by using the COMQueryInterface subroutine. It is important that you have a pointer to the correct object interface when calling a routine generated by the Module Wizard. If not, your application will likely crash.

Releasing the Pointer to an Object's Interface

When you have finished using an object's interface pointer, you must call COMReleaseObject with the pointer. This includes object pointers that you have received using any method, including COMCreateObject, COMQueryInterface, or by calling an object's method.