Component Categories

5-Jul-02 8:39

Disclaimer: I am not an ATL guru....want to be but that is another disclaimer!

I have not been able to find any samples to follow that use inheritence and virtual functions in com using atl. I guess the first question should be can it be done? Here is what I am trying to accomplish...

I have a parent object (PObject) that has a virtual function (ExecuteService), and several pure virtual functions such as Display(). I want to extend that class with several subclasses that would implement the specific service. (We need an insert diagram here button on this forum!)

I want a factory which takes a string or int which gives me the correct subclass depending upon the parameter value.

This should work:

void RunService(CString name)
{
    IServiceFactoryPtr ptrFact(__uuidof(ServiceFactory));
    IPObjectPtr ptrObj = ptrFact->GetServiceByName(name.AllocSysString());
    ptrObj->ExecuteService();
}

I've been able to get the factory working, I actually end up with the correct object when I make the call to GetServiceByName, however when calling ExecuteService I get an exception.

So, how do I set up the classes using ATL to get this to work??? It's a basic factory pattern. Good basis for an article if someone could get me past this hump!

Thanks,

ed

mhamsa8-Jul-02 6:38

mhamsa

8-Jul-02 6:38

Take a look through the MS documentation (or other sources) for topics pertaining to Aggregation and/or containment. It is possible mimic inheritence in ATL by having one COM component aggregate the implementation of another COM component, expose these interfaces, and extend upon them by exposing additional interfaces. This is how inheritence in practiced in ATL and more specifically COM.

soptest8-Jul-02 7:37

soptest

8-Jul-02 7:37

Component Categories

As this chapter has emphasized, the basic COM activation primitives require the caller to know the precise class name in order to create new instances. However, it is sometimes useful simply to request that any class that adheres to some semantic constraint is suitable. In addition, it could be useful to know what services a class requires from its clients prior to issuing an activation request to avoid creating objects that the client is not prepared to support properly. These problems motivate the concept of component categories.

COM allows implementors to group related COM classes into logical groups or component categories. Often, all classes within a category will implement the same set of interfaces. However, simply partitioning the class space based on which interfaces each class implements does not provide the proper granularity for many applications. Component categories act as metainformation that indicates which classes are compatible with particular semantic constraints.

A component category is a group of logically related COM classes that share a common category ID or CATID. CATIDs are GUIDs that are stored in the Registry as attributes of a class. Each class can have two subkeys: Implemented Categories and Required Categories. Assume that there are two categories of components: Simians and Mammals. These two categories would each have a unique CATID (CATID_Simians and CATID_Mammals, respectively). Assuming that the class Chimp is a member of each of these categories, the Chimp’s Implemented Categories registry key would contain each GUID as an individual subkey:

[HKCR\CLSID\{CLSID_Chimp}\Implemented Categories\{CATID_Mammals}]

[HKCR\CLSID\{CLSID_Chimp}\Implemented Categories\{CATID_Simians}]

These registry entries are typically added at self-registration time. Each known component category on a system has an entry under

HKEY_CLASSES_ROOT\Component Categories

Each category has its own unique subkey named by its CATID. Underneath its subkey, each category has one or more named values that contain the human-readable description of the category. For example, the two categories shown would require the following registry entries:

[HKCR\Component Categories\{CATID_Mammals}]
409="Bears live young"

[HKCR\Component Categories\{CATID_Simians}]
409="Eats Bananas"

Note that this example uses the 409 value, which is the LCID for U.S. English. Other locales can be supported by adding additional named values.

It is also possible for classes to indicate that they require particular types of functionality from the client. This support typically comes in the form of site interfaces that the client will provide to the object once activated. To allow these client-provided services to be categorized independent of any particular interface, COM allows classes to advertise a second type of category ID that can be used by clients to ensure that they do not activate a component that they cannot properly host. Assume the following two categories of client-

provided services: CATID_HasOxygen and CATID_HasWater. Since chimpanzees need oxygen and water to survive, the Chimp implementor might advertise that these two categories of client-provided services are required for activation. This is done by using the Required Categories subkeys:

[HKCR\CLSID\{CLSID_Chimp}\Required Categories\{CATID_HasOxygen}]

[HKCR\CLSID\{CLSID_Chimp}\Required Categories\{CATID_HasWater}]

These two category IDs would need to be registered under

HKEY_CLASSES_ROOT\Component Categories

as well. Given these entries, it is the client’s responsibility to ensure that it meets the required categories prior to activation. COM does not enforce client conformance.

Component category entries can be registered using either explicit registry functions or the COM-supplied component category manager. COM’s component category manager is exposed as an instantiable COM class (CLSID_ StdComponentCategoriesMgr) that implements the ICatRegister interface for registering category information and the ICatInformation interface for querying category information. The ICatRegister interface allows server DLLs easily to add the requisite entries to the Registry:

[ object, uuid(0002E012-0000-0000-C000-000000000046) ]
interface ICatRegister : IUnknown {
// description info for a category
  typedef struct tagCATEGORYINFO {
    CATID      catid;
    LCID       lcid;
    OLECHAR szDescription[128];
  } CATEGORYINFO;
// register cCts category descriptions
  HRESULT RegisterCategories([in] ULONG cCts, 
           [in, size_is(cCts)] CATEGORYINFO rgCatInfo[]);
// unregister cCategories category descriptions
  HRESULT UnRegisterCategories([in] ULONG cCategories, 
           [in, size_is(cCategories)] CATID rgcatid[]);
// indicate a class implements one or more categories
  HRESULT RegisterClassImplCategories([in] REFCLSID rclsid, 
           [in] ULONG cCategories, 
           [in, size_is(cCategories)] CATID rgcatid[]);
// deindicate a class implements with one or more categories
  HRESULT UnRegisterClassImplCategories([in] REFCLSID rclsd,
           [in] ULONG cCategories, 
           [in, size_is(cCategories)] CATID rgcatid[]);
// indicate a class requires one or more categories
  HRESULT RegisterClassReqCategories([in] REFCLSID rclsid, 
           [in] ULONG cCategories, 
           [in, size_is(cCategories)] CATID rgcatid[]);
// deindicate a class requires one or more categories
  HRESULT UnRegisterClassReqCategories([in] REFCLSID rclsid,
           [in] ULONG cCategories, 
           [in, size_is(cCategories)] CATID rgcatid[]);
}

There is no need for user-defined COM classes to implement this interface. It exists solely to allow servers to self-register their component categories using the COM-provided category manager implementation.

In the case of the Chimp example, the following code would register the correct information regarding each category:

// get the standard category manager
ICatRegister *pcr = 0;
HRESULT hr = CoCreateInstance( 
              CLSID_StdComponentCategoriesMgr, 0, 
              CLSCTX_ALL, IID_ICatRegister, (void**)&pcr);
if (SUCCEEDED(hr)) {
// build descriptions of each category
  CATEGORYINFO rgcc[4];
  rgcc[0].catid = CATID_Simian; 
  rgcc[1].catid = CATID_Mammal; 
  rgcc[2].catid = CATID_HasOxygen; 
  rgcc[3].catid = CATID_HasWater; 
  rgcc[0].lcid = rgcc[1].lcid 
    = rgcc[2].lcid = rgcc[3].lcid = 0x409;
  wcscpy(rgcc[0].szDescription, OLESTR("Eats Bananas"));
  wcscpy(rgcc[1].szDescription, OLESTR("Bears live young"));
  wcscpy(rgcc[2].szDescription, OLESTR("Provides Oxygen"));
  wcscpy(rgcc[3].szDescription, OLESTR("Provides Water"));
// register information regarding categories
  pcr->RegisterCategories(4, rgcc);

// note that Chimps are Simians and mammals
  CATID rgcid[2];
  rgcid[0] = CATID_Simian; rgcid[1] = CATID_Mammal;
  pcr->RegisterClassImplCategories(CLSID_Chimp, 2, rgcid);

// note that Chimps require Oxygen and Water
  rgcid[0] = CATID_HasOxygen; rgcid[1] = CATID_HasWater;
  pcr->RegisterClassReqCategories(CLSID_Chimp, 2, rgcid);
  pcr->Release();
}

Note that this code makes no raw registry API calls but instead uses the standard category manager to manipulate the Registry.

The standard category manager also allows applications to query the registry to find information regarding categories. This functionality is exposed via the ICatInformation interface:

[ object, uuid(0002E013-0000-0000-C000-000000000046) ]
interface ICatInformation : IUnknown {
// get list of known categories
  HRESULT EnumCategories([in] LCID lcid, 
       [out] IEnumCATEGORYINFO** ppeci);
// get description of a particular category
  HRESULT GetCategoryDesc([in] REFCATID rcatid, 
       [in] LCID lcid, 
        [out] OLECHAR ** ppszDesc);
// get list of classes compatible with specified categories
  HRESULT EnumClassesOfCategories(
       [in] ULONG cImplemented, (-1 indicates ignore)
       [in,size_is(cImplemented)] CATID rgcatidImpl[],
       [in] ULONG cRequired,    (-1 indicates ignore)
       [in,size_is(cRequired)] CATID rgcatidReq[],
       [out] IEnumCLSID** ppenumClsid);
// verify class is compatible with specified categories
  HRESULT IsClassOfCategories([in] REFCLSID rclsid, 
       [in] ULONG cImplemented,
       [in,size_is(cImplemented)] CATID rgcatidImpl[],
       [in] ULONG cRequired,
       [in,size_is(cRequired)] CATID rgcatidReq[]);
// get list of class's implemented categories
  HRESULT EnumImplCategoriesOfClass([in] REFCLSID rclsid,
       [out] IEnumCATID** ppenumCatid);
// get list of class's required categories
  HRESULT EnumReqCategoriesOfClass([in] REFCLSID rclsid, 
       [out] IEnumCATID** ppenumCatid);
}

Most of these methods return cursors to lists of category or class IDs. These cursors are called enumerators and are described in detail in Chapter 7.

The following code demonstrates how to extract the list of classes that are members of the Mammal category:

// get the standard category manager

ICatInformation *pci = 0;
HRESULT hr = CoCreateInstance( 
          CLSID_StdComponentCategoriesMgr, 0, 
          CLSCTX_ALL, IID_ICatInformation, (void**)&pci);
if (SUCCEEDED(hr)) {
// get the classes that are Simians (ignore required cat.s)
  IEnumCLSID *pec = 0;
  CATID rgcid[1];
  rgcid[0] = CATID_Simian;
  hr = pci->EnumClassesOfCategories(1, rgcid, -1, 0, &pec);
  if (SUCCEEDED(hr)) {
// walk list of CLSIDs 64 at a time
    enum { MAX = 64 };
    CLSID rgclsid[MAX];
    do {
      ULONG cActual = 0;
      hr = pec->Next(MAX, rgclsid, &cActual);
      if (SUCCEEDED(hr)) {
        for (ULONG i = 0; i < cActual; i++)
          DisplayClass(rgclsid[i]);
      }
    } while (hr == S_OK);
    pec->Release();
  }
  pci->Release();
}

This code fragment ignores the fact that the client program may not support the required categories of the resultant list of classes. Had the client been aware of its supported site categories, it could have specified the list of all supported categories.

Consider the following call to EnumClassesOfCategories:

CATID rgimpl[1]; rgimpl[0] = CATID_Simians;
CATID rgreq[3]; rgreq[0] = CATID_HasWater; 
rgreq[1] = CATID_HasOxygen; rgreq[2] = CATID_HasMilk;
hr =pci->EnumClassesOfCategories(1, rgimpl, 3, rgreq, &pec);

The resultant list of classes would contain all Simians that require no more than Oxygen, Water, and Milk from the client’s environment. In the case of the Chimp class registered previously, Chimp would be a compatible class, as it implements the specified category Simian and requires a subset of the specified categories used in the query.

One final aspect of component categories that bears discussion is the notion of a default class for a category. COM allows a CATID to be registered as a CLSID under

HKEY_CLASSES_ROOT\CLSID

To map a CATID to a default CLSID, the TreatAs facility introduced by emulation is used. To indicate that the Gorilla class is the default class of Simian, one would add the following registry key:

[HKCR\CLSID\{CATID_Simian}\TreatAs]
@={CLSID_Gorrila}

This simple convention allows clients simply to use CATIDs where CLSIDs are expected:

// create an instance of the default Simian class
hr = CoCreateInstance(CATID_Simian, 0, CLSCTX_ALL, 
                     IID_IApe, (void**)&pApe);

If no default class is registered for the specified category, the activation call will fail, returning REGDB_E_CLASSNOTREG.

soptest

Vivek Rajan11-Jul-02 11:10

Vivek Rajan

11-Jul-02 11:10

Ed-

Can you post the class signature of the derived class (i.e its inheritance list ) as well as whether or not you have used ATL_NO_VTABLE ?

One place to look at is :

1. Do you have ExecuteService defined as one of the methods in the interface definition for IPObject ?

HTH -
Vivek

Ed K11-Jul-02 15:42

11-Jul-02 15:42

Thanks for offering to take a look at it. Rather than posting all the code here I've put it into a zip on my site to download.

test.zip

The zip contains 2 zip files. One is the test client and the other the servicefactory. I'm using VC6 and WTL7 (I'm in love with CString!).

ServiceFactory has a method GetService(BSTR name, IPObject**ppObj) which will get either the FoodService or the BeverageService depending on the string passed in. PObject has a virtual method ExecuteServie(BSTR param) which calls a virtual method Display. ExecuteService is only implemented in PObject. Display is only implemented in the subclasses.

If you step through the test client you can actually see that the right object is created however when I called ExecuteService it throws an unhandled exception.

Thanks again! Rose | [Rose]

Vivek Rajan12-Jul-02 6:44

Vivek Rajan

12-Jul-02 6:44

Ed -

The problem is you are trying to call a ExecuteService using a IFoodService pointer. This would work if IFoodService were derived from IPObject, but it is not ! This means that the vtable entry for ExecuteService just does not exist for IFoodService. Typecasting it via reinterpret_cast wont fix it either.

I made the following change and it worked for me.

In File factory.cpp
Note that we now QI for IPObject instead of IFoodService

<br />
return	CComCreator< CComObject<CBeverageService> >::CreateInstance(NULL, IID_IPObject, reinterpret_cast<void**>(ppPObj) );<br />

This would ensure that the interface pointer for IPObject is returned instead of IFoodService.
If you really want IFoodService on the client, you can always QI for it from IPObject.

Suggested change
Change the interface map for CFood and CBev

<br />
BEGIN_COM_MAP(CFoodService)<br />
	COM_INTERFACE_ENTRY(IFoodService)<br />
	COM_INTERFACE_ENTRY_CHAIN(CPObject)<br />
END_COM_MAP()<br />

This is because CFoodService does not directly implement IPObject but rather uses the implementation already defined in a base class. The QI then searches for the implementation in the base class.

Hope that helps-
Vivek

Ed K12-Jul-02 8:44

How to use one instance of a COM object in different processes?

12-Jul-02 8:44

What it comes down to is that I have to implement ExecuteService in each of the base classes to handle the initial request (Command Pattern) then let it call a template method in the parent class to get things moving as I want them to. I really don't want the client to have a clue as to what he is calling. That way I can add other base classes without having to recompile the client.

Thanks for checking it out. I really appreciate it!

ed

The nice thing about egotists is that they don't talk about other people.

Lucille Harper

Jawid5-Jul-02 5:37

Jawid

5-Jul-02 5:37

Hi everyone,
I am not able to find a way how to use the only one (common) instance of my COM object from several processes. Here I see the only solution of multiple instances and that way I lose some of the pointers.
Can anybody guide me how to do that?

Thanks,

Jawid

Re: How to use one instance of a COM object in different processes?

Scot T Brennecke6-Jul-02 4:53

Scot T Brennecke

6-Jul-02 4:53

Have you tried using RegisterActiveObject, to put your object in the ROT? Then you can use GetActiveObject.

Scot Brennecke
Software Developer
VC++ MVP

Re: How to use one instance of a COM object in different processes?

8-Jul-02 4:22

I found that macro :

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vclib/html/vcoriATLMacrosAlphabeticalReference.asp

The particular one is :

DECLARE_CLASSFACTORY_SINGLETON

Hope this helps.

Re: How to use one instance of a COM object in different processes?

8-Jul-02 4:17

If you com object was developed using ATL then there is a macro you can use to make it a singleton, meaning only one instance of it will be created and shared between all clients. Im sorry but i can't remeber what the macro is, its something like ATL_DECLARE_SINGLETON. Have a poke around in the MSDN although i found it in one of the wrox atl books.

Re: How to use one instance of a COM object in different processes?

Pedro Miranda8-Jul-02 4:47

Pedro Miranda

8-Jul-02 4:47

Hi,
I’m sorry but I did not fully understand your question? You want to use the some instance of a COM object in different processes or different threads in the same process?
If you want to pass a pointer to a object to another thread in a running process you have to be aware of the COM Threading Model (Apartments) and Marshalling see http://www.codeguru.com/activex/COMApartments1.html and http://www.codeguru.com/activex/COMApartments2.html .
.
If you really want different processes to access the same COM object, then this last has to be implemented in a out-process (.exe) COM server having the class factory returning the same object every time a instance of that class is requested. Remember that using an out-process com server you’ll be linking whit a proxy/stub dll (Marshalling).
http://www.codeguru.com/activex/MiniDcom.html

I recommend you reading Essential COM (Don Box), ATL Internals (Brent Rector) and Learning DCOM (Thuan L. Thai)

Re: How to use one instance of a COM object in different processes?

Jawid9-Jul-02 16:18

Jawid

9-Jul-02 16:18

Hi Guys,
Thanks for great help. All of those advices seem very helpfull. I tried the solution with macro for singleton object and it works nice.

Thanks,

Re: How to use one instance of a COM object in different processes?

Ed K12-Jul-02 8:09

Can somebody please answer this?

12-Jul-02 8:09

Make sure that it is an exe service rather than a dll service. A dll singleton loads a different instance per app. An exe will have only one instance.

ed

The nice thing about egotists is that they don't talk about other people.

Lucille Harper

JohnnyG3-Jul-02 14:26

JohnnyG

3-Jul-02 14:26

Ok. I'm trying to use a COM OCX object in a C program. I've done some research and found out how to call and instantiate a COM object from C. However, I do not know how to generate a header file for object type or interface declarations.

SOPTEST replied with some useful info but all I can find out is info on how to develop a COM object using C and not how to use an existing one that is already in the registry that I didn't develop. I want to use MSCOMM32.OCX in a C program. How do I get the declaration for the IMSComm and other interfaces?

I know how to get the IUknown interface, call QueryInterface, etc. And, I know that getting an interface pointer is really a void** so I could create a void pointer and call it anything I like and use it but that doesn't seem right or is it???? I've learned how to view the typelib, CLASSID, etc. from OLE/COM Object viewer so I don't think I'm an idiot, I just need some help.

Is there someway of interpreting the type library and converting it into a header file that I am not aware of? Anybody??

soptest3-Jul-02 14:39

soptest

3-Jul-02 14:39

Use "oleview" to open type library. From "File" menu you can "Save as" *.IDL, *.H or *.C file. If you save it as *.IDL file then compile it with MIDL compiler to generate proxy/stub files.

soptest

JohnnyG3-Jul-02 14:59

JohnnyG

3-Jul-02 14:59

I used "oleview". I did not know you could save .c or .h files from there but when I tried, it didn't work. Apparently, it uses a console window but the error happens so fast and the console window closes before I can see it. However, I was able to save the .idl file. But, going from using VC++ before with Add To Project | Components and Controls that generates all C++ wrapper classes and as you say proxy/stub files for out of process.

JohnnyG3-Jul-02 15:36

JohnnyG

3-Jul-02 15:36

I think I got it now. I was finally able to save a .c and .h files to the default directory (system32). I still got warnings or errors but I couldn't tell what they were. Looking at the contents it has the proper extern "C" declarations Laugh | :laugh:

Cool!

Thanks again, SOPTEST