Debian Codegraph @

htmlman/main006.html

raw
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>&nbsp;&nbsp;Hints on writing IDL files</H2>
19 <A NAME="toc24"></A>
20 <H3><A NAME="htoc30">6.1</A>&nbsp;&nbsp;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 -&gt; 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>&nbsp;&nbsp;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 &lt;camlidlcompat.h&gt;
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>&nbsp;&nbsp;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>