ComBroker has been developed to maximize two things: ease of use and unlimited application. Using ComBroker is not hard, but there are a few basic steps that need to be followed.

1 - You need to Register an Interface for Brokering
2 - You need to Initialize your Handler (and know how to call the original interface), and
3 - After you've finished, you need to de-registering your Handler.

The sections below provide a basic overview for registering, using and de-registering an interface handler.

Registering an Interface and Interface Handler

The ComBroker library consists of 3 methods, one for registering an interface and two for releasing that same interface. Registering an interface with ComBroker initiates the associated negotiation framework against that interface, and releasing an interface causes ComBroker to restore that interface back to its original working condition.

When an interface is registered, you must also specify an associated handler for "handling" that interface. A handler serves a single purpose: to associated the interface being subclassed with your version of that same interface. It is therefore a requirement that your handler support the same interface identifier (GUID) as the interface being subclassed.

For example: If you wanted to subclass an IOleClientSite interface, then your associated handler would have to support both IInterfaceHandler and IOleClientSite. The IInterfaceHandler implementation of your handler would receive the IOleClientSite IUnknown method calls, and all of the other method calls of IOleClientSite would be forwarded to your handlers implementation of IOleClientSite.

Once An Interface Handler Has Been Registered

Once your handler has been registered, its "InitializeHandler" method is called. InitializeHandler receives 2 parameters, "lpBroker" and "lpBrokeredInterface".

lpBrokeredInterface:
It is important to point out that the purpose of lpBrokeredInterface is to provide the default interface for communicating with the original interface! If you are going to call any of the methods from the original interface you must use lpBrokeredInterface to do so, as calling the original interface pointer will cause your code to be called recursively.

The lpBroker parameter of "InitializeHandler" identifies the core IInterfaceBroker instance controlling the flow of execution to your interface handler.

All handlers, once registered, are inactive (or paused). The original interface will continue to operate normally until you call the resume method of IInterfaceBroker. Calling lpBroker.Resume(...) from within InitializeHandler is perfectly legitimate and provides the ideal opportunity to do so.

De-registering an Interface or Interface Handler!

After your handler has finished performing its duties, you are required to call one of the two ComBroker deregistration routines to release the associated interface negotiation framework from both your handler and the brokered interface.

There are 2 deregistration procedures that differ only in their parameters. One identifies which handler to release via the interface it brokered, and the other accepts the handler itself as identification.