Getting a Pointer to an Object

Because COM does not have a strict class model, there are several ways to instantiate or to get a pointer to an interface on an object. There are, in fact, four methods through which a client obtains its first interface pointer to a given object:

• Call a COM Library API function that creates an object of a pre-determined type — that is, the function will only return a pointer to one specific interface for a specific object class.
• Call a COM Library API function that can create an object based on a class identifier (CLSID) and that returns any type of interface pointer requested.
• Call a method of some interface that creates another object (or connects to an existing one) and returns an interface pointer on that separate object.
• Implement an object with an interface through which other objects pass their interface pointer to the client directly.

For information on getting pointers to other interfaces on an object once you have the first one, see QueryInterface: Navigating in an Object.

There are numerous COM functions that return pointers to specific interface implementations, such as CoGetMalloc, which retrieves a pointer to the standard COM memory allocator. Most of these are helper functions, which retrieve a pointer to an COM implementation of an interface on an object, as does CoGetMalloc. Most of these functions are described in the specific area they are related to, such as storage or data transfer.

There are several functions that, given a CLSID, a client can call to create an object instance and get a pointer to it. All of these functions are based on the function CoGetClassObject, which creates a class object and supplies a pointer to an interface that allows you to create instances of that class. While there must be information that says which system the server resides on, there is no need for that information to be contained in the client. The client needs to know only the CLSID, and never the absolute path of the server code. For more information, see Creating an Object through a Class Object.

Among the many interface methods that return a pointer to a separate object are several that create and return a pointer to an enumerator object, which allows you to determine how many items of a given type an object maintains. COM defines interfaces for enumerating a wide variety of items, such as strings, several structures important in various COM technologies, monikers, and IUnknown interface pointers. The typical way to create an enumerator instance and get a pointer to its interface is to call a method from another interface. For example, the IDataObject interface defines two methods, EnumDAdvise and EnumFormatEtc, that return pointers to interfaces on two different enumeration objects. There are many other examples in COM of methods that return pointers to objects, such as the OLE Compound Document interface IOleObject::GetClientSite, which, when called on the embedded or linked object, returns a pointer to the container object's implementation of IOleClientSite.

The fourth way to get a pointer to an object is used when two objects, such as an OLE Compound Document container and server, need bi-directional communication. Each implements an object containing an interface method to which other objects can pass interface pointers. In the case of containers and servers, each object then passes its pointer to the other object. The implementing object, which is also the client of the created object, can then call the method and get the pointer that was passed.