COM & AssemblyA. PurposeSome of the basic technics used in the COM samples for assembly (Masm syntax) are described here. It is not a must to understand these things to use COM with Masm or JWasm, but it might help. Please note that no introduction to COM is given here. There exist other places on the net for that purpose. The source samples which will demonstrate the things described here are:
Some more sophisticated examples, all written in assembly (Masm style):
The include files which are refered to below are
B. Basic Macros in OBJBASE.INC1. Macro BEGIN_INTERFACEMacro BEGIN_INTERFACE starts definition of an interface. It has 2 parameters. The first is required and is the name of the interface, the second is optional and is the name of an interface to be inherited. An example is:
This line will start declaration of interface IShellFolder, inheriting from IUnknown. The code generated by this macro will look like:
2. Macro STDMETHODMacro STDMETHOD defines a method inside current interface definition. It has at least 1 parameter, which is the name of the method. Other parameters may follow, but do NOT declare THIS pointer as a parameter. It is automatically included.Each STDMETHOD macro will result in two typedefs and one variable being included. First is a function prototype type definition, second is a pointer to this function type definition. The structure variable, which is defined at last, will get the type of the second type definition. So Masm/JWasm will be able to check number and type of parameters for each call of this method. Example (from Interface IOleCommandTarget):
will be translated to the following 3 lines:
3. Macro END_INTERFACEMacro END_INTERFACE has no parameters and finishes current interface definition. In fact, the vtable definition is terminated and the interface itself - which consists of a pointer to this vtable only - is defined. Example:
will be translated to the following lines (the bold ones come from END_INTERFACE):
4. Macro vf()Macro vf() is used to call a method of an interface. It requires 3 parameters, which are:
The above line will in a first step be evaluated into:
After invoke itself is evaluated, the code will look like:
where only the bold text comes from macro vf()! This implicates that register edx MUST NOT be used in any form as a parameter. Macro vf() is unable to detect usage of edx for any parameter behind the closing bracket, so no error message is displayed in this case. C. IDispatch Support Macros in DISPHLP.INC1. IDispatch InterfaceIf an interface is derived from IDispatch then there exists another possible way to call methods of this interface. That's by using method IDispatch::Invoke. Include File DISPHLP.INC - supplied with COMView - offers some support macros for calling methods this way. With these calling a method by IDispatch::Invoke is as simple as calling it by vtable with macro vf().2. Macro DEFINE_DISPMETHODThis macro describes a method being called with IDispatch::Invoke. In fact some text equates and a dummy procedure are defined.Example (method "Close", interface "Window" with 3 variants as parameters and returning a BOOL):
will finally result in following equates being defined
and a dummy procedure
will be generated. The dummy procedure is necessary to make Masm/JWasm check parameters when calling this method. No code is generated, though, and "segment" _TEXT$02 MUST remain empty. This will result in proc InvokeHelper - located immediately "behind" in "segment" _TEXT$02$1 - being entered if proc Window_Close is being called. 3. Macro dm()Macro dm() is used to call a method thru IDispatch::Invoke. It works only in conjunction with macro DEFINE_INVOKEHELPER (see below). So if you use dm() and haven't coded DEFINE_INVOKEHELPER, you will most likely get a linker error. Besides that macro dm() is used similar to macro vf(), with exactly the same parameters.If using the example above dm() would look like:
which is evaluated into (bold text from macro dm())
As you may notice, there is - besides "this" pointer pWindow - another hidden parameter, the "metadata" pointer addr Window_CloseMDData. This "metadata" is defined for each method being used in code in section _TEXT$03, its value comes from equates defined by macro DEFINE_DISPMETHOD and will be used by proc InvokeHelper. External DEFINE_INVOKEHELPER_is_missing ensures that macro DEFINE_INVOKEHELPER will exist in source code 4. Macro DEFINE_INVOKEHELPERMacro DEFINE_INVOKEHELPER defines proc InvokeHelper and public DEFINE_INVOKEHELPER_is_missing. This proc is not called directly. But in fact every call generated with macro dm() will hopefully result in a call of this procedure. That's because InvokeHelper will be located in section _TEXT$02$1, which the linker should place immediately behind section _TEXT$02, where dummy procs generated by macro DEFINE_DISPMETHOD are locatedWhat will proc InvokeHelper do? Depending on first parameter, the "metadata" pointer, it will get the other parameters from stack, convert it to variants and put them in a dynamically build array of variants. After that it will call IDispatch::Invoke and, if a return parameter is expected, convert returned variant into appropriate return type and store it. Finally InvokeHelper clears the stack and returns to caller. For more details please take a look in include file DISPHLP.INC. D. Client Event Support macros in DISPHLP.INC1. Macro BEGIN_EVENTSThis macro will define an event table. It requires one parameter, which should be the name of the event interface. A label xxx_EventTab will be defined, where xxx stands for the interface name.2. Macro DEFINE_DISPEVENTThis macro defines an entry in the current event table. One or two parameters are expected. First will be the name of a method for which event notifications should be received. Second - optional - parameter is local name of the event procedure. The macro can only occure between macros BEGIN_EVENTS and END_EVENTS.3. Macro END_EVENTSThis macro will finish definition of an event table. It defines a DWORD with value -1 to indicate the end of the table.Finally a sample for an event table:
will create the following code:
4. Macro DEFINE_EVENTHELPERMacro DEFINE_EVENTHELPER defines an IDispatch interface which will act as event sink object. As well the following procedures are defined:
E. Server Event Support macros in DISPHLP.INC1. Macro FIREEVENT()Macro FIREEVENT() requires 3 parameters and is used only in conjunction with macro invoke, so its syntax is similiar to macros vf() or dm(). As well, it requires macro DEFINE_FIREEVENTHELPER to be inserted somewhere in the code, since it calls procedure FireEvent.Example: Let's assume an event dispinterface is defined as:
To fire event OnClick one have to code:
which will result in code:
2. Macro DEFINE_FIREEVENTHELPERMacro DEFINE_FIREEVENTHELPER defines public proc FireEvent, which will be called from inside macro FIREEVENT(). It moves all parameters to an array of variants, prepares a DISPPARAMS structure and will notify all connected sinks of the event. For this to work the server must support interface IEnumConnections.F. Screen ShotsThe following screenshots are done inside COMView, which is a powerful tool to view and handle COM objects.
|
