| C & C++ Programming | MFC Programming | Download | Site Index |


 

 

Supplementary note for MFC Programming Module 23

 

 

 

What do we have in this Module?

  1. CCmdTarget Class

  2. CCmdTarget Members

    1.     Attributes

    2.     Constructors

    3.     Operations

    4.     Overridables

  3. CoGetClassObject() function

    1.     Parameters

    2.     Return Values

    3.     Remarks

  4. COleObjectFactory Class

  5. COleObjectFactory Members

    1.     Construction

    2.     Operations

    3.     Attributes

    4.     Overridables

 

 

CCmdTarget Class

 

class CCmdTarget : public Cobject

 

CCmdTarget is the base class for the Microsoft Foundation Class Library message-map architecture. A message map routes commands or messages to the member functions you write to handle them. A command is a message from a menu item, command button, or accelerator key. Key framework classes derived from CCmdTarget include CView, CWinApp, CDocument, CWnd, and CFrameWnd. If you intend for a new class to handle messages, derive the class from one of these CCmdTarget-derived classes. You will rarely derive a class from CCmdTarget directly. CCmdTarget includes member functions that handle the display of an hourglass cursor. Display the hourglass cursor when you expect a command to take a noticeable time interval to execute. Dispatch maps, similar to message maps, are used to expose OLE automation IDispatch functionality. By exposing this interface, other applications (such as Visual Basic) can call into your application. The afxwin.h header must be included in order to use this class.

 

CCmdTarget Members

 

Attributes

 

FromIDispatch()

Returns a pointer to the CCmdTarget object associated with the IDispatch pointer.

GetIDispatch()

Returns a pointer to the IDispatch object associated with the CCmdTarget object.

IsResultExpected()

Returns nonzero if an automation function should return a value.

 

Table 1.

 

Constructors

 

CCmdTarget

Constructs a CCmdTarget object.

 

Table 2.

 

Operations

 

BeginWaitCursor()

Displays the cursor as an hourglass cursor.

DoOleVerb()

Causes an action specified by an OLE verb to be performed.

EnableAutomation()

Allows OLE automation for the CCmdTarget object.

EnableConnections()

Enables event firing over connection points.

EndWaitCursor()

Returns to the previous cursor.

EnumOleVerbs()

Enumerates an object's OLE verbs.

RestoreWaitCursor()

Restores the hourglass cursor.

 

Table 3.

 

Overridables

 

EnableTypeLib()

Enables an object's type library.

GetDispatchIID()

Gets the primary dispatch interface ID.

GetTypeInfoCount()

Retrieves the number of type information interfaces that an object provides.

GetTypeInfoOfGuid()

Retrieves the type description that corresponds to the specified GUID.

GetTypeLib()

Gets a pointer to a type library.

GetTypeLibCache()

Gets the type library cache.

IsInvokeAllowed()

Enables automation method invocation.

OnCmdMsg()

Routes and dispatches command messages.

OnFinalRelease()

Cleans up after the last OLE reference is released.

 

Table 4.

 

CoGetClassObject()

 

Provides a pointer to an interface on a class object associated with a specified CLSID. CoGetClassObject() locates, and if necessary, dynamically loads the executable code required to do this.

Call CoGetClassObject() directly when you want to create multiple objects through a class object for which there is a CLSID in the system registry. You can also retrieve a class object from a specific remote machine. Most class objects implement the IClassFactory interface. You would then call IClassFactory::CreateInstance to create an uninitialized object. It is not always necessary to go through this process. To create a single object, call instead the either the CoCreateInstanceEx() function, which allows you to create an instance on a remote machine. This replaces the CoCreateInstance() function, which can still be used to create an instance on a local machine. Both functions encapsulate connecting to the class object, creating the instance, and releasing the class object. Two other functions, CoGetInstanceFromFile() and CoGetInstanceFromIStorage(), provide both instance creation on a remote system, and object activation. OLE also provides many other ways to create an object in the form of numerous helper functions and interface methods whose function is to create objects of a single type and provide a pointer to an interface on that object. Take note that the CoGetClassObject() function does not call CoLoadLibrary(). In order to use this function, objbase.h must be included.

 

STDAPI CoGetClassObject(

  REFCLSID rclsid,

  DWORD dwClsContext,

  COSERVERINFO * pServerInfo,

  REFIID riid,

  LPVOID * ppv

);

 

 

 

 

Parameters

  1. rclsid - [in] CLSID associated with the data and code that you will use to create the objects.

  2. dwClsContext - [in] Context in which the executable code is to be run. To enable a remote activation, CLSCTX_REMOTE_SERVER must be included.

  3. pServerInfo - [in] Pointer to machine on which to instantiate the class object. May be NULL, in which case the class object is instantiated on the current machine or at the machine specified under the class's RemoteServerName key in the registry; according to the interpretation of the dwClsCtx parameter.

  4. riid - [in] Reference to the identifier of the interface, which will be supplied in ppv on successful return. This interface will be used to communicate with the class object. Typically this value is IID_IClassFactory, although other values, such as IID_IClassFactory2 which supports a form of licensing, are allowed. All OLE-defined interface IIDs are defined in the OLE header files as IID_interfacename, where interfacename is the name of the interface.

  5. ppv - [out] Address of pointer variable that receives the interface pointer requested in riid. Upon successful return, *ppv contains the requested interface pointer.

Return Values

  1. S_OK - Location and connection to the specified class object was successful.

  2. REGDB_E_CLASSNOTREG - CLSID is not properly registered. Can also indicate that the value you specified in dwClsContext is not in the registry.

  3. E_NOINTERFACE - Either the object pointed to by ppv does not support the interface identified by riid, or the QueryInterface() operation on the class object returned E_NOINTERFACE.

  4. REGDB_E_READREGDB - Error reading the registration database.

  5. CO_E_DLLNOTFOUND - In-process DLL or handler DLL not found (depends on context).

  6. CO_E_APPNOTFOUND - EXE not found (CLSCTX_LOCAL_SERVER only).

  7. E_ACCESSDENIED - General access failure (returned from LoadLib()/CreateProcess()).

  8. CO_E_ERRORINDLL - EXE has error in image.

  9. CO_E_APPDIDNTREG - EXE was launched, but it didn't register class object (may or may not have shut down).

 

Remarks

 

A class object in OLE is an intermediate object that supports an interface that permits operations common to a group of objects. The objects in this group are instances derived from the same object definition represented by a single CLSID. Usually, the interface implemented on a class object is IClassFactory, through which you can create object instances of a given definition (class). A call to CoGetClassObject() creates, initializes, and gives the caller access (through a pointer to an interface specified with the riid parameter) to the class object. The class object is the one associated with the CLSID that you specify in the rclsid parameter. The details of how the system locates the associated code and data within a given machine are transparent to the caller, as is the dynamic loading of any code that is not already loaded. If the class context is CLSCTX_REMOTE_SERVER, indicating remote activation is required, the COSERVERINFO structure provided in the pServerInfo parameter allows you to specify the machine on which the server is located. For information on the algorithm used to locate a remote server when pServerInfo is NULL, refer to the CLSCTX enumeration. There are two places to find a CLSID for a given class:

  1. The registry holds an association between CLSIDs and file suffixes, and between CLSIDs and file signatures for determining the class of an object.

  2. When an object is saved to persistent storage, its CLSID is stored with its data.

To create and initialize embedded or linked OLE document objects, it is not necessary to call CoGetClassObject() directly. Instead, call one of the OleCreate or OleCreateXxx helper functions. These functions encapsulate the entire object instantiation and initialization process, and call, among other functions, CoGetClassObject(). The riid parameter specifies the interface the client will use to communicate with the class object. In most cases, this interface is IClassFactory. This provides access to the IClassFactory::CreateInstance method, through which the caller can then create an uninitialized object of the kind specified in its implementation. All classes registered in the system with a CLSID must implement IClassFactory. In rare cases, however, you may want to specify some other interface that defines operations common to a set of objects. For example, in the way OLE implements monikers, the interface on the class object is IParseDisplayName, used to transform the display name of an object into a moniker. The dwClsContext parameter specifies the execution context, allowing one CLSID to be associated with different pieces of code in different execution contexts. The CLSCTX enumeration, defined in Compobj.h, specifies the available context flags. CoGetClassObject() consults (as appropriate for the context indicated) both the registry and the class objects that are currently registered by calling the CoRegisterClassObject() function. To release a class object, use the class object's Release() method. The function CoRevokeClassObject() is to be used only to remove a class object's CLSID from the system registry.

 

COleObjectFactory Class

 

class COleObjectFactory : public CCmdTarget

 

The COleObjectFactory class implements the OLE class factory, which creates OLE objects such as servers, automation objects, and documents. The afxdisp.h must be included in order to use this class. The COleObjectFactory class has member functions for performing the following functions:

  1. Managing the registration of objects.

  2. Updating the OLE system register, as well as the run-time registration that informs OLE that objects are running and ready to receive messages.

  3. Enforcing licensing by limiting use of the control to licensed developers at design time and to licensed applications at run time.

  4. Registering control object factories with the OLE system registry.

COleObjectFactory Members

 

Construction

 

COleObjectFactory

Constructs a COleObjectFactory object.

 

Table 5.

 

Operations

 

Register()

Registers this object factory with the OLE system DLLs.

RegisterAll()

Registers all of the application's object factories with OLE system DLLs.

Revoke()

Revokes this object factory's registration with the OLE system DLLs.

RevokeAll()

Revokes an application's object factories' registrations with the OLE system DLLs.

UnregisterAll()

Unregisters all of an application’s object factories.

UpdateRegistryAll()

Registers all of the application's object factories with the OLE system registry.

 

Table 6.

 

Attributes

 

GetClassID()

Returns the OLE class ID of the objects this factory creates.

IsLicenseValid()

Determines if the license of the control is valid.

IsRegistered()

Indicates whether the object factory is registered with the OLE system DLLs.

 

Table 7.

 

Overridables

 

GetLicenseKey()

Requests a unique key from the control's DLL.

OnCreateObject()

Called by the framework to create a new object of this factory's type.

UpdateRegistry()

Registers this object factory with the OLE system registry.

VerifyLicenseKey()

Verifies that the key embedded in the control matches the key embedded in the container.

VerifyUserLicense()

Verifies that the control is licensed for design-time use.

 

Table 8.

 

 


| C & C++ Programming | MFC Programming | Download | Site Index |