| 1 |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" |
| 2 |
"http://www.w3.org/TR/REC-html40/loose.dtd"> |
| 3 |
<HTML> |
| 4 |
<HEAD> |
| 5 |
|
| 6 |
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| 7 |
<META name="GENERATOR" content="hevea 1.06-7 of 2001-11-14"> |
| 8 |
<TITLE> |
| 9 |
Hints on writing IDL files |
| 10 |
</TITLE> |
| 11 |
</HEAD> |
| 12 |
<BODY > |
| 13 |
<A HREF="main005.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A> |
| 14 |
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Contents"></A> |
| 15 |
<A HREF="main007.html"><IMG SRC ="next_motif.gif" ALT="Next"></A> |
| 16 |
<HR> |
| 17 |
|
| 18 |
<H2><A NAME="htoc29">6</A> Hints on writing IDL files</H2> |
| 19 |
<A NAME="toc24"></A> |
| 20 |
<H3><A NAME="htoc30">6.1</A> Writing an IDL file for a C library</H3> |
| 21 |
When writing an IDL file for a C library that doesn't have an IDL interface |
| 22 |
already, the include files for that library are a good starting point: |
| 23 |
just copy the relevant type and functin declarations to the IDL file, |
| 24 |
then annotate them with IDL attributes to describe more precisely |
| 25 |
their actual behavior. The documentation of the library must be read |
| 26 |
carefully to determine the mode of function parameters (<TT>in</TT>, <TT>out</TT>, |
| 27 |
<TT>inout</TT>), the actual sizes of arrays, etc.<BR> |
| 28 |
<BR> |
| 29 |
The type definitions in the IDL file need not correspond exactly with |
| 30 |
those in the include files. Often, a cleaner Caml interface can be |
| 31 |
obtained by omitting irrelevant struct fields, or changing their types. |
| 32 |
For instance, the Unix library functions for reading library entries |
| 33 |
may use the following structure: |
| 34 |
<PRE> |
| 35 |
struct dirent { |
| 36 |
long int d_ino; |
| 37 |
__off_t d_off; |
| 38 |
unsigned short int d_reclen; |
| 39 |
unsigned char d_type; |
| 40 |
char d_name[256]; |
| 41 |
}; |
| 42 |
</PRE>Of those fields, only <TT>d_name</TT> and <TT>d_ino</TT> are of interest to the |
| 43 |
user; the other fields are internal information for the library |
| 44 |
functions, are not specified in the POSIX specs, and therefore must |
| 45 |
not be used. Thus, in the IDL file, you should declare: |
| 46 |
<PRE> |
| 47 |
struct dirent { |
| 48 |
long int d_ino; |
| 49 |
char d_name[256]; |
| 50 |
}; |
| 51 |
</PRE>Thus, the Caml code will have |
| 52 |
<TT>type struct_dirent = {d_ino: int; d_name: string}</TT> |
| 53 |
as desired. However, the generated stub code, being |
| 54 |
compiled against the ``true'' definition of <TT>struct dirent</TT>, will find |
| 55 |
those two fields at the correct offsets in the actual struct.<BR> |
| 56 |
<BR> |
| 57 |
Special attention must be paid to integer fields or variables. |
| 58 |
By default, integer IDL types are mapped to the Caml type <TT>int</TT>, |
| 59 |
which is convenient to use in Caml code, but loses one bit |
| 60 |
when converting from a C <TT>long</TT> integer, and may lose one bit (on |
| 61 |
32-bit platforms) when converting from a C <TT>int</TT> integer. When the |
| 62 |
range of values represented by the C integer is small enough, this |
| 63 |
loss is acceptable. Otherwise, you should use the attributes |
| 64 |
<TT>nativeint</TT>, <TT>int32</TT> or <TT>int64</TT> so that integer IDL types are mapped |
| 65 |
to one of the Caml boxed integer types. (We recommend that you use |
| 66 |
<TT>int32</TT> or <TT>int64</TT> for integers that are specified as being exactly 32 |
| 67 |
bit wide or 64 bit wide, and <TT>nativeint</TT> for unspecified <TT>int</TT> or |
| 68 |
<TT>long</TT> integers.)<BR> |
| 69 |
<BR> |
| 70 |
Yet another possibility is to declare certain integer fields or variables |
| 71 |
as <TT>double</TT> in the IDL file, so that they are represented by <TT>float</TT> |
| 72 |
in Caml, and all 32 bits of the integer are preserved in Caml. For |
| 73 |
instance, the Unix function to get the current type is declared as |
| 74 |
<PRE> |
| 75 |
time_t time(time_t * t); |
| 76 |
</PRE>where <TT>time_t</TT> is usually defined as <TT>long</TT>. We can nonetheless |
| 77 |
pretend (in the IDL file) that <TT>time</TT> returns a double: |
| 78 |
<PRE> |
| 79 |
double time() quote(" _res = time(NULL); "); |
| 80 |
</PRE>This way, <TT>time</TT> will have the Caml type <TT>unit -> float</TT>. |
| 81 |
Again, the stub code ``knows'' that <TT>time</TT> actually returns an integer, |
| 82 |
and therefore will insert the right integer-float coercions.<BR> |
| 83 |
<BR> |
| 84 |
<A NAME="toc25"></A> |
| 85 |
<H3><A NAME="htoc31">6.2</A> Sharing IDL files between MIDL and CamlIDL</H3> |
| 86 |
The Microsoft software development kit provides a number of IDL files |
| 87 |
describing various libraries and components. In its current state, |
| 88 |
<TT>camlidl</TT> cannot exploit those files directly: they use many |
| 89 |
(often poorly documented) Microsoft IDL features that are not |
| 90 |
implemented yet in <TT>camlidl</TT>; symmetrically, <TT>camlidl</TT> introduces |
| 91 |
several new annotations that are not recognized by Microsoft's <TT>midl</TT> |
| 92 |
compiler. So, significant editing work on the IDL files is required.<BR> |
| 93 |
<BR> |
| 94 |
The C preprocessor can be used to alleviate the <TT>camlidl</TT>-<TT>midl</TT> |
| 95 |
incompatibilities: <TT>camlidl</TT> defines the preprocessor symbol <TT>CAMLIDL</TT> |
| 96 |
when preprocessing its input files, while <TT>midl</TT> does not. Hence, |
| 97 |
one can bracket incompatible definitions in |
| 98 |
<TT>#ifdef CAMLIDL ... #else ... #endif</TT>. Along these lines, a C |
| 99 |
preprocessor header file, <TT>camlidlcompat.h</TT>, is provided: it uses |
| 100 |
<TT>#define</TT> to remove <TT>camlidl</TT>-specific attributes when compiling with |
| 101 |
<TT>midl</TT>, and to remove <TT>midl</TT>-specific attributes when compiling with |
| 102 |
<TT>camlidl</TT>. Thus, an IDL file compatible with both <TT>midl</TT> and |
| 103 |
<TT>camlidl</TT> would look like this: |
| 104 |
<PRE> |
| 105 |
#include <camlidlcompat.h> |
| 106 |
|
| 107 |
#ifndef CAMLIDL |
| 108 |
import "unknwn.idl"; // imports specific to MIDL |
| 109 |
import "oaidl.idl"; |
| 110 |
#endif |
| 111 |
import "mymodule.idl"; // imports common to MIDL and CamlIDL |
| 112 |
|
| 113 |
typedef [abstract,marshal_as(int)] void * ptr; |
| 114 |
|
| 115 |
... |
| 116 |
|
| 117 |
#ifndef CAMLIDL |
| 118 |
[...] library MyTypeLib { |
| 119 |
importlib("stdole32.tlb"); |
| 120 |
[...] coclass MyComponent { [default] interface IX; } |
| 121 |
} |
| 122 |
#endif |
| 123 |
</PRE>Notice that since <TT>camlidl</TT> doesn't handle type libraries, the type |
| 124 |
library part of an <TT>midl</TT> file must be enclosed in <TT>#ifndef CAMLIDL</TT>.<BR> |
| 125 |
<BR> |
| 126 |
<A NAME="toc26"></A> |
| 127 |
<H3><A NAME="htoc32">6.3</A> Dispatch interfaces and type libraries</H3> <A NAME="s-dispatch"></A> |
| 128 |
A dispatch interface, in COM lingo, is an interface that supports |
| 129 |
dynamic, interpreted dispatch of method interfaces. This form of |
| 130 |
interpreted dispatch is used by Visual Basic and other scripting |
| 131 |
languages to perform calls to methods of COM components.<BR> |
| 132 |
<BR> |
| 133 |
CamlIDL provides minimal support for dispatch interfaces. To equip a |
| 134 |
Caml component with a dispatch interface (thus making it callable from |
| 135 |
Visual Basic), you need to do the following: |
| 136 |
<OL type=1><LI> |
| 137 |
Use <TT>IDispatch</TT> instead of <TT>IUnknown</TT> as the super-interface of |
| 138 |
the component's interfaces. |
| 139 |
<LI>Write a type library for your component and compile it using |
| 140 |
<TT>midl</TT>. A type library is a run-time representation of the interfaces |
| 141 |
supported by an object. The <TT>midl</TT> compiler can generate a type |
| 142 |
library from the IDL description of the component, enriched with some |
| 143 |
special-purpose declarations (the <TT>library</TT> and <TT>coclass</TT> |
| 144 |
statements). Refer to the documentation of <TT>midl</TT> for more |
| 145 |
information. |
| 146 |
<LI>Pass the type library files (<TT>.tlb</TT> files) generated by <TT>midl</TT> |
| 147 |
as extra arguments to <TT>camlidldll</TT> when generating the DLL for your |
| 148 |
Caml component. |
| 149 |
</OL> |
| 150 |
<HR> |
| 151 |
<A HREF="main005.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A> |
| 152 |
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Contents"></A> |
| 153 |
<A HREF="main007.html"><IMG SRC ="next_motif.gif" ALT="Next"></A> |
| 154 |
</BODY> |
| 155 |
</HTML> |