/usr/share/doc/camlidl/html/main003.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>

<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.06-7 of 2001-11-14">
<TITLE>
 The Caml-IDL mapping
</TITLE>
</HEAD>
<BODY >
<A HREF="main002.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Contents"></A>
<A HREF="main004.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H2><A NAME="htoc13">3</A>&nbsp;&nbsp;The Caml-IDL mapping</H2>
This section describes how IDL types, function declarations, and
interfaces are mapped to Caml types, functions and classes.<BR>
<BR>
<A NAME="toc11"></A>
<H3><A NAME="htoc14">3.1</A>&nbsp;&nbsp;Base types</H3><BR>
<DIV ALIGN=center><TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1 WIDTH="80%">
<TR><TD ALIGN=center NOWRAP><B>IDL type <I>ty</I></B></TD>
<TD ALIGN=center NOWRAP><B>Caml type [[<I>ty</I></B><B>]]</B></TD>
</TR>
<TR><TD ALIGN=left NOWRAP>
<TT>byte</TT>, <TT>short</TT></TD>
<TD ALIGN=left NOWRAP><TT>int</TT></TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>int</TT>, <TT>long</TT> with <TT>[camlint]</TT> attribute</TD>
<TD ALIGN=left NOWRAP><TT>int</TT></TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>int</TT>, <TT>long</TT> with <TT>[nativeint]</TT> attribute</TD>
<TD ALIGN=left NOWRAP><TT>nativeint</TT></TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>int</TT>, <TT>long</TT> with <TT>[int32]</TT> attribute</TD>
<TD ALIGN=left NOWRAP><TT>int32</TT></TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>int</TT>, <TT>long</TT> with <TT>[int64]</TT> attribute</TD>
<TD ALIGN=left NOWRAP><TT>int64</TT></TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>hyper</TT>, <TT>long long</TT>, <TT>__int64</TT></TD>
<TD ALIGN=left NOWRAP><TT>int64</TT></TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>char</TT></TD>
<TD ALIGN=left NOWRAP><TT>char</TT></TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>float</TT>, <TT>double</TT></TD>
<TD ALIGN=left NOWRAP><TT>float</TT></TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>boolean</TT></TD>
<TD ALIGN=left NOWRAP><TT>bool</TT></TD>
</TR></TABLE></DIV><BR>

(For integer types, <TT>signed</TT> and <TT>unsigned</TT> variants of the same IDL
integer type translate to the same Caml type.)<BR>
<BR>
Depending on the attributes, the <TT>int</TT> and <TT>long</TT> integer types are
converted to one of the Caml integer types <TT>int</TT>, <TT>nativeint</TT>,
<TT>int32</TT>, or <TT>int64</TT>. Values of Caml type <TT>int32</TT> are exactly 32-bit wide
and values of type <TT>int64</TT> are exactly 64-bit wide on all platforms.
Values of type <TT>nativeint</TT> have the natural word size of the platform,
and are large enough to accommodate any C <TT>int</TT> or <TT>long int</TT> without
loss of precision. Values of Caml type <TT>int</TT> have the natural word
size of the platform minus one bit of tag, hence the conversion from IDL
types <TT>int</TT> and <TT>long</TT> loses the most significant bit on 32-bit
platforms. On 64-bit platforms, the conversion from <TT>int</TT> is exact,
but the conversion from <TT>long</TT> loses the most significant bit.<BR>
<BR>
If no explicit integer attribute is given for an <TT>int</TT> or <TT>long</TT> type,
the <TT>int_default</TT> or <TT>long_default</TT> attribute of the enclosing
interface, if any, determines the kind of the integer.
If no <TT>int_default</TT> or <TT>long_default</TT> attribute is in scope, the kind
<TT>camlint</TT> is assumed, which maps IDL <TT>int</TT> and <TT>long</TT> types to the
Caml <TT>int</TT> type.<BR>
<BR>
<A NAME="toc12"></A>
<H3><A NAME="htoc15">3.2</A>&nbsp;&nbsp;Pointers</H3>
The mapping of IDL pointer types depends on their kinds. Writing
[[<I>ty</I>]] for the Caml type corresponding to the IDL type
<I>ty</I>, we have:
<PRE>
       [ref] <I>ty</I> *  <FONT FACE=symbol>Þ</FONT>  [[<I>ty</I>]]
    [unique] <I>ty</I> *  <FONT FACE=symbol>Þ</FONT>  [[<I>ty</I>]] option
       [ptr] <I>ty</I> *  <FONT FACE=symbol>Þ</FONT>  [[<I>ty</I>]] Com.opaque
</PRE>
In other terms, IDL pointers of kind <TT>ref</TT> are ignored during the mapping:
<TT>[ref] </TT><I>ty</I><TT> *</TT> is mapped to the same Caml type as <I>ty</I>.
A pointer <I>p</I> to a C value <I>c</I><TT> = *</TT><I>p</I> is translated to
the Caml value corresponding to <I>c</I>.<BR>
<BR>
IDL pointers of kind <TT>unique</TT> are mapped to an <TT>option</TT> type. The
option value is <TT>None</TT> for a null pointer, and <TT>Some(</TT><I>v</I><TT>)</TT>
for a non-null pointer to a C value <I>c</I> that translates to the ML
value <I>v</I>.<BR>
<BR>
IDL pointers of kind <TT>ptr</TT> are mapped to a <TT>Com.opaque</TT> type.
This is an abstract type that encapsulates the C pointer without
attempting to convert it to an ML data structure.<BR>
<BR>
IDL pointers of kind <TT>ignore</TT> denote struct fields and function
parameters that need not be exposed in the Caml code. Those pointers
are simply set to null when converting from Caml to C, and ignored
when converting from C to Caml. They cannot occur elsewhere.<BR>
<BR>
If no explicit pointer kind is given, the <TT>pointer_default</TT> attribute
of the enclosing interface, if any, determines the kind of the pointer.
If no <TT>pointer_default</TT> attribute is in scope, the kind <TT>unique</TT> is
assumed.<BR>
<BR>
<A NAME="toc13"></A>
<H3><A NAME="htoc16">3.3</A>&nbsp;&nbsp;Arrays</H3>
IDL arrays of characters that carry the <TT>[string]</TT> attribute are mapped
to the Caml <TT>string</TT> type:
<BR>
<DIV ALIGN=center><TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1 WIDTH="80%">
<TR><TD ALIGN=center NOWRAP><B>IDL type <I>ty</I></B></TD>
<TD ALIGN=center NOWRAP><B>Caml type [[<I>ty</I></B><B>]]</B></TD>
</TR>
<TR><TD ALIGN=left NOWRAP>
<TT>[string] char []</TT></TD>
<TD ALIGN=left NOWRAP><TT>string</TT></TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>[string] unsigned char []</TT></TD>
<TD ALIGN=left NOWRAP><TT>string</TT></TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>[string] signed char []</TT></TD>
<TD ALIGN=left NOWRAP><TT>string</TT></TD>
</TR>
<TR><TD ALIGN=left NOWRAP><TT>[string] byte []</TT></TD>
<TD ALIGN=left NOWRAP><TT>string</TT></TD>
</TR></TABLE></DIV><BR>

Caml string values are translated to standard null-terminated C strings.
Be careful about embedded null characters in the Caml string, which
will be recognized as end of string by C functions.<BR>
<BR>
IDL arrays carrying the <TT>[bigarray]</TT> attribute are translated to Caml
``big arrays'', as described in the next section.<BR>
<BR>
All other IDL arrays are translated to ML arrays:
<PRE>
        <I>ty</I> []  <FONT FACE=symbol>Þ</FONT>  [[<I>ty</I>]] array
</PRE>
For instance, <TT>double []</TT> becomes <TT>float array</TT>.
Consequently, multi-dimensional arrays are translated to Caml arrays
of arrays. For instance, <TT>int [][]</TT> becomes <TT>int array array</TT>.<BR>
<BR>
If the <TT>unique</TT> attribute is given, the IDL array is translated to an
ML option type:
<PRE>
        [string,unique] char []  <FONT FACE=symbol>Þ</FONT>  string option
        [unique] <I>ty</I> []     <FONT FACE=symbol>Þ</FONT>  [[<I>ty</I>]] array option
</PRE>
As in the case of pointers of kind <TT>unique</TT>, the option value is
<TT>None</TT> for a null C pointer, and <TT>Some(</TT><I>v</I><TT>)</TT> for a non-null
C pointer to a C array that translates to the ML string or array <I>v</I>.<BR>
<BR>
Conversion between a C array and an ML array proceed element by
element. For the conversion from C to ML, the number of elements of
the ML array is determined as follows (in the order presented):
<UL><LI>
By the <TT>length_is</TT> attribute, if present.
<LI>By the <TT>size_is</TT> attribute, if present.
<LI>By the bound written in the array type, if any.
<LI>By searching the first null element of the C array, if the
<TT>null_terminated</TT> attribute is present.
</UL>
For instance, C values of IDL type <TT>[length_is(n)] double[]</TT> are
mapped to Caml <TT>float array</TT> of <TT>n</TT> elements. C values of IDL type
<TT>double[10]</TT> are mapped to Caml <TT>float array</TT> of 10 elements.<BR>
<BR>
The <TT>length_is</TT> and <TT>size_is</TT> attributes take as argument one or
several limited expressions. Each expression applies to one dimension
of the array. For instance, <TT>[size_is(*dimx, *dimy)] double d[][]</TT>
specifies a matrix of <TT>double</TT> whose first dimension has size
<TT>*dimx</TT> and the second has size <TT>*dimy</TT>.<BR>
<BR>
<A NAME="toc14"></A>
<H3><A NAME="htoc17">3.4</A>&nbsp;&nbsp;Big arrays</H3>
IDL arrays of integers or floats that carry the <TT>[bigarray]</TT> attribute
are mapped to one of the Caml <TT>Bigarray</TT> types: <TT>Array1.t</TT> for
one-dimensional arrays, <TT>Array2.t</TT> for 2-dimensional arrays,
<TT>Array3.t</TT> for 3-dimensional arrays, and <TT>Genarray.t</TT> for arrays of 4
dimensions or more.<BR>
<BR>
If the <TT>[fortran]</TT> attribute is given, the big array is accessed
from Caml using the Fortran conventions (array indices start at 1;
column-major memory layout). By default, the big array is accessed
from Caml using the C conventions (array indices start at 0; row-major
memory layout).<BR>
<BR>
If the <TT>[managed]</TT> attribute is given on a big array type that is
result type or out parameter type of a function, Caml assumes that the
corresponding C array was allocated using <TT>malloc()</TT>, and is not
referenced anywhere else; then, the Caml garbage collector will free
the C array when the corresponding Caml big array becomes unreachable.
By default, Caml assumes that result or out C arrays are statically or
permanently allocated, and keeps a pointer to them during conversion
to Caml big arrays, and does not free them when the Caml bigarrays
become unreachable.<BR>
<BR>
Finally, the <TT>[unique]</TT> attribute applies to bigarrays as to arrays,
that is, it maps a null C pointer to <TT>None</TT>, and a non-null C pointer
<I>p</I> to <TT>Some(</TT><I>v</I><TT>)</TT> where <I>v</I> is the ML bigarray
resulting from the translation of <I>p</I>.<BR>
<BR>
<A NAME="toc15"></A>
<H3><A NAME="htoc18">3.5</A>&nbsp;&nbsp;Structs</H3>
IDL structs are mapped to Caml record types. The names and types of
the IDL struct fields determine the names and types of the Caml record
type:
<PRE>
struct <I>s</I> { ... ; <I>ty</I><SUB><FONT SIZE=2><I>i</I></FONT></SUB> <I>id</I><SUB><FONT SIZE=2><I>i</I></FONT></SUB> ; ... }  becomes  type <I>s</I> = { ... ; <I>id</I><SUB><FONT SIZE=2><I>i</I></FONT></SUB> : [[<I>ty</I><SUB><FONT SIZE=2><I>i</I></FONT></SUB>]] ; ... }
</PRE>
Example: <TT>struct s { int n; double d[4]; }</TT> becomes
<TT>type s = {n: int; d: float array}</TT>.<BR>
<BR>
Exceptions to this rule are as follows:
<UL><LI>
Fields of the IDL struct that are pointers with the <TT>[ignore]</TT>
attribute do not appear in the Caml record type.
Example: <TT>struct s { double x,y; [ignore] void * data; }</TT>
becomes <TT>type struct_s = {x : float; y: float}</TT>.
Those ignored pointer fields are set to <TT>NULL</TT> when converting from a
Caml record to a C struct.<BR>
<BR>
<LI>Integer fields of the IDL struct that appear in a <TT>length_is</TT>,
<TT>size_is</TT> or <TT>switch_is</TT> attribute of another field also do not appear
in the Caml record type. (We call those fields <EM>dependent</EM> fields.)
Example: <TT>struct s { int idx; int len; [size_is(len)] double d[]; }</TT>
is translated to the Caml record type 
<TT>type struct_s = {idx: int; d: float array}</TT>.
The value of <TT>len</TT> is recovered from the size of the Caml array <TT>d</TT>,
and thus doesn't need to be represented explicitly in the Caml record.<BR>
<BR>
<LI>If, after elimination of ignored pointer fields and dependent
fields as described above, the IDL struct has only one field
<I>ty</I>&nbsp;<I>id</I>, we avoid creating a one-field Caml record type
and translate the IDL struct type directly to the Caml type
[[<I>ty</I>]].
Example: <TT>struct s { int len; [size_is(len)] double d[]; }</TT>
is translated to the Caml type abbreviation <TT>type struct_s = double array</TT>.<BR>
<BR>
<LI>The names of labels in the Caml record type can be changed by
using the <TT><FONT COLOR=blue>mlname</FONT></TT> attribute on struct field declarations. For instance,
<PRE>
struct s { int n; [mlname(p)] int q; }
         becomes type s = { n : int; p : int }
</PRE><BR>
<BR>
<LI>The Caml type system makes it difficult to use two record types
defined in the same module and having some label names in common.
Thus, if CamlIDL encounters two or more structs having
identically-named fields, it prefixes the Caml label names by the names
of the structs in order to distinguish them. For instance:
<PRE>
struct s1 { int x; int y; }
struct s2 { double x; double t; }
struct s3 { int z; }
         becomes type s1 = { s1_x: int; s1_y: int }
                 and s2 = { s2_x: float; s2_t: float }
                 and s3 = { z: int }
</PRE>
The labels for <TT>s1</TT> and <TT>s2</TT> have been prefixed by <TT>s1_</TT> and
<TT>s2_</TT> respectively, to avoid ambiguity on the <TT>x</TT> label. However, the
label <TT>z</TT> for <TT>s3</TT> is not prefixed, since it is not used elsewhere.<BR>
<BR>
The prefix added in front of multiply-defined labels is taken from the
struct name, if any, and otherwise from the name of the nearest
enclosing struct, union or typedef. For instance:
<PRE>
typedef struct { int x; } t;
struct s4 { struct { int x; } z; };
         becomes type t = { t_x: int }
                 and s4 = { z: struct_1 }
                 and struct_1 = { s4_x: int }
</PRE>
The ``minimal prefixing'' strategy described above is the default
behavior of <TT>camlidl</TT>. If the <TT>-prefix-all-labels</TT> option is given,
all record labels are prefixed, whether they occur several times or
not. If the <TT>-keep-labels</TT> option is given, no automatic prefixing
takes place; the naming of record labels is left entirely under the
user's control, via <TT><FONT COLOR=blue>mlname</FONT></TT> annotations.</UL>
<A NAME="toc16"></A>
<H3><A NAME="htoc19">3.6</A>&nbsp;&nbsp;Unions</H3>
IDL discriminated unions are translated to Caml sum types. Each case
of the union corresponds to a constructor of the sum type. The
constructor is constant if the union case has no associated field,
otherwise has one argument corresponding to the union case field. If
the union has a <TT>default</TT> case, an extra constructor
<TT>Default_</TT><I>unionname</I> is added to the Caml sum type, carrying an
<TT>int</TT> argument (the value of the discriminating field),
and possibly another argument corresponding to the default field.
Examples:
<PRE>
union u1 { case A: int x; case B: case C: double d; case D: ; }
         becomes type u1 = A of int | B of float | C of float | D
union u2 { case A: int x; case B: double d; default: ; }
         becomes type u2 = A of int | B of float | Default_u of int
union u3 { case A: int x; default: double d; }
         becomes type u3 = A of int | Default_v of int * double
</PRE>
All IDL unions must be discriminated, either via the special syntax
<TT>union </TT><I>name</I><TT> switch(int </TT><I>discr</I><TT>)</TT>..., or via the
attribute <TT>switch_is(</TT><I>discr</I><TT>)</TT>, where <I>discr</I> is a C l-value
built from other parameters of the current function, or other fields
of the current <TT>struct</TT>. Both the discriminant and the
case labels must be of an integer type. Unless a <TT>default</TT> case is
given, the value of the discriminant must be one of the cases of the
union.<BR>
<BR>
<A NAME="toc17"></A>
<H3><A NAME="htoc20">3.7</A>&nbsp;&nbsp;Enums</H3>
IDL enums are translated to Caml enumerated types (sum types with only
constant constructors). The names of the constructors are determined
by the names of the enum labels. The values attached to the enum
labels are ignored.
Example:
<TT>enum e { A, B = 2, C = 4 }</TT> becomes <TT>type enum_e = A | B | C</TT>.<BR>
<BR>
The <TT><FONT COLOR=blue>set</FONT></TT> attribute can be applied to a named enum to denote a
bitfield obtained by logical ``or'' of zero, one or several labels of
the enum. The corresponding ML value is a list of zero, one or
several constructors of the Caml enumerated type. Consider for
instance:
<PRE>
enum e { A = 1, B = 2, C = 4 };
typedef [set] enum e eset;
</PRE>The Caml type <TT>eset</TT> is equal to <TT>enum_e list</TT>.
The C integer 6 (= <TT>B | C</TT>) is translated to the ML list <TT>[B; C]</TT>.
The ML list <TT>[A; C]</TT> is translated to the C integer <TT>A | C</TT>, that is <TT>5</TT>.<BR>
<BR>
<A NAME="toc18"></A>
<H3><A NAME="htoc21">3.8</A>&nbsp;&nbsp;Type definitions</H3>
An IDL <TT>typedef</TT> statement is normally translated
to a Caml type abbreviation. For instance,
<TT>typedef [string] char * str</TT> becomes <TT>type str = string</TT>.<BR>
<BR>
If the <TT><FONT COLOR=blue>abstract</FONT></TT> attribute is given, a Caml abstract type is
generated instead of a type abbreviation, thus hinding from Caml the
representation of the type in question. For instance,
<TT>typedef [abstract] void * handle</TT> becomes <TT>type handle</TT>.
In this case, the IDL type in the <TT>typedef</TT> is ignored.<BR>
<BR>
If the <TT><FONT COLOR=blue>mltype</FONT></TT> <TT><FONT COLOR=blue>(</FONT></TT> <TT><FONT COLOR=blue>"</FONT></TT> <TT><I><FONT COLOR=maroon>caml-type-expr</FONT></I></TT> <TT><FONT COLOR=blue>"</FONT></TT> <TT><FONT COLOR=blue>)</FONT></TT> attribute is given,
the Caml type is made equal to <TT><I><FONT COLOR=maroon>caml-type-expr</FONT></I></TT>. This is often used
in conjunction with the <TT><FONT COLOR=blue>ml2c</FONT></TT> and <TT><FONT COLOR=blue>c2ml</FONT></TT> attributes to implement
custom translation of data structures between C and ML. For instance,
<TT>typedef [mltype("int list")] struct mylist_struct * mylist</TT>
becomes <TT>type mylist = int list</TT>.<BR>
<BR>
If the <TT><FONT COLOR=blue>c2ml(</FONT></TT><TT><I><FONT COLOR=maroon>funct-name</FONT></I></TT><TT><FONT COLOR=blue>)</FONT></TT> &nbsp;<TT><I><FONT COLOR=maroon>and</FONT></I></TT> <TT>ml2c(</TT>funct-name<TT>)</TT> attributes are
given, the user-provided C functions given as attributes will be
called to perform Caml to C and C to Caml conversions for values of
the typedef-ed type, instead of using the <TT>camlidl</TT>-generated
conversion functions. This allows user-controlled translation of data
structures. The prototypes of the conversion functions must be
<PRE>
        value c2ml(<I>ty</I> * input);
        void ml2c(value input, <I>ty</I> * output);
</PRE>
where <I>ty</I> is the name of the type defined by <TT>typedef</TT>. In other
terms, the <TT>c2ml</TT> function is passed a reference to a <I>ty</I> and
returns the corresponding Caml value, while the <TT>ml2c</TT> function is
passed a Caml value as first argument and stores the corresponding C
value in the <I>ty</I> reference passed as second argument.<BR>
<BR>
If the <TT><FONT COLOR=blue>finalize(</FONT></TT><TT><I><FONT COLOR=maroon>final-fn</FONT></I></TT><TT><FONT COLOR=blue>)</FONT></TT> attribute is given in combination with the
<TT><FONT COLOR=blue>abstract</FONT></TT> attribute, the function <TT><I><FONT COLOR=maroon>final-fn</FONT></I></TT> is called when
the Caml block representing a value of this typedef becomes
unreachable from Caml and is reclaimed by the Caml garbage collector. 
Similarly, <TT><FONT COLOR=blue>compare(</FONT></TT><TT><I><FONT COLOR=maroon>compare-fn</FONT></I></TT><TT><FONT COLOR=blue>)</FONT></TT> and <TT><FONT COLOR=blue>hash(</FONT></TT><TT><I><FONT COLOR=maroon>hash-fn</FONT></I></TT><TT><FONT COLOR=blue>)</FONT></TT> attach a
comparison function and a hashing function (respectively) to Caml
values for this typedef. The comparison function is called when two
Caml values of this typedef are compared using the generic comparisons
<TT>compare</TT>, <TT>=</TT>, <TT>&lt;</TT>, etc. The hashing function is called when
<TT>Hashtbl.hash</TT> is applied to a Caml value of this typedef.
The prototype of the finalization, comparison and hashing functions are:
<PRE>
        value <I>final-fn</I>(<I>ty</I> * x);
        int <I>compare-fn</I>(<I>ty</I> * x, <I>ty</I> * y);
        long <I>hash-fn</I>(<I>ty</I> * x);
</PRE>
That is, their arguments are passed by reference. The comparison
function must return an integer that is negative, zero, or positive
depending on whether its first argument is smaller, equal or greater
than its second argument. The hashing function returns a suitable
hash value for its argument.<BR>
<BR>
If the <TT><FONT COLOR=blue>errorcheck(</FONT></TT><TT><I><FONT COLOR=maroon>fn</FONT></I></TT><TT><FONT COLOR=blue>)</FONT></TT> attribute is provided for the <TT>typedef</TT> <I>ty</I>,
the error checking function <TT><I><FONT COLOR=maroon>fn</FONT></I></TT> is called each time a function result
of type <I>ty</I> is converted from C to Caml. The function can then check
the <I>ty</I> value for values indicating an error condition, and raise the
appropriate exception. If in addition the <TT><FONT COLOR=blue>errorcode</FONT></TT> attribute is
provided, the conversion from C to Caml is suppressed: values of type
<I>ty</I> are only passed to <TT><I><FONT COLOR=maroon>fn</FONT></I></TT> for error checking, then discarded.<BR>
<BR>
<A NAME="toc19"></A>
<H3><A NAME="htoc22">3.9</A>&nbsp;&nbsp;Functions</H3>
IDL function declarations are translated to Caml functions.
The parameters and results of the Caml function are determined from
those of the IDL function according to the following rules:
<UL><LI>
First, dependent parameters (parameters that are <TT>size_is</TT>,
<TT>length_is</TT> or <TT>switch_is</TT> of other parameters) as well as parameters
that are ignored pointers are removed.<BR>
<BR>
<LI>The remaining parameters are split into Caml function inputs and
Caml function outputs. Parameters with the <TT>[in]</TT> attribute are added
to the inputs of the function. Parameters with the <TT>[out]</TT>
attribute are added to the outputs of the function. Parameters with
the <TT>[in,out]</TT> attribute are added both to the inputs and to the
outputs of the function, unless they are of type string or big array,
in which case they are added to the inputs of the function only.
(The reason for this exception is that strings and big arrays are
shared between Caml and C, thus allowing true <TT>in,out</TT> behavior on the
Caml function parameter, while other data types are copied during
Caml/C conversion, thus turning a C <TT>in,out</TT> parameter into a Caml
<TT>copy in, copy out</TT> parameter, that is, one parameter and one result.)<BR>
<BR>
<LI>The return value of the IDL function is added to the outputs of
the Caml function (in first position), unless it is of type <TT>void</TT> or
of a type name that carries the <TT>errorcode</TT> attribute. In the latter
two cases, the return value of the IDL function is not transmitted to
Caml.
<LI>The Caml function is then given type
<TT><I><FONT COLOR=maroon>in</FONT></I></TT><SUB><FONT SIZE=2>1</FONT></SUB> <TT><FONT COLOR=blue>-&gt;</FONT></TT> ... <TT><FONT COLOR=blue>-&gt;</FONT></TT> &nbsp;<TT><I><FONT COLOR=maroon>in</FONT></I></TT><SUB><FONT SIZE=2><I>p</I></FONT></SUB> <TT><FONT COLOR=blue>-&gt;</FONT></TT> &nbsp;<TT><I><FONT COLOR=maroon>out</FONT></I></TT><SUB><FONT SIZE=2>1</FONT></SUB> <TT><FONT COLOR=blue>*</FONT></TT> ... <TT><FONT COLOR=blue>*</FONT></TT> &nbsp;<TT><I><FONT COLOR=maroon>out</FONT></I></TT><SUB><FONT SIZE=2><I>q</I></FONT></SUB>
where <TT><I><FONT COLOR=maroon>in</FONT></I></TT><SUB><FONT SIZE=2>1</FONT></SUB> ... &nbsp;<TT><I><FONT COLOR=maroon>in</FONT></I></TT><SUB><FONT SIZE=2><I>p</I></FONT></SUB> are the types of its inputs
and <TT><I><FONT COLOR=maroon>out</FONT></I></TT><SUB><FONT SIZE=2>1</FONT></SUB> ... &nbsp;<TT><I><FONT COLOR=maroon>out</FONT></I></TT><SUB><FONT SIZE=2><I>q</I></FONT></SUB> are the types of its outputs.
If there are no inputs, a <TT>unit</TT> parameter is added.
If there are no outputs, a <TT>unit</TT> result is added.
</UL>
Examples:
<PRE>
int f([in] double x, [in] double y)             f : float -&gt; float -&gt; int
</PRE>
<BLOCKQUOTE> Two <TT>double</TT> input, one <TT>int</TT> output </BLOCKQUOTE>
<PRE>
void g([in] int x)                              g : int -&gt; unit
</PRE>
<BLOCKQUOTE> One <TT>int</TT> input, no output </BLOCKQUOTE>
<PRE>
int h()                                         h : unit -&gt; int
</PRE>
<BLOCKQUOTE> No input, one <TT>int</TT> result </BLOCKQUOTE>
<PRE>
void i([in] int x, [out] double * y)            i : int -&gt; double
</PRE>
<BLOCKQUOTE> One <TT>int</TT> input, one <TT>double</TT> output (as an <TT>out</TT>
parameter) </BLOCKQUOTE>
<PRE>
int j([in] int x, [out] double * y)             j : int -&gt; int * double
</PRE>
<BLOCKQUOTE> One <TT>int</TT> input, one <TT>int</TT> output (in the result), one
<TT>double</TT> output (as an <TT>out</TT> parameter) </BLOCKQUOTE>
<PRE>
void k([in,out,ref] int * x)                    k : int -&gt; int
</PRE>
<BLOCKQUOTE> The <TT>in,out</TT> parameter is both one <TT>int</TT> input and one
<TT>int</TT> output. </BLOCKQUOTE>
<PRE>
HRESULT l([in] int x, [out] int * res1, [out] int * res2)
                                                l : int -&gt; int * int
</PRE>
<BLOCKQUOTE> <TT>HRESULT</TT> is a predefined type with the <TT>errorcode</TT>
attribute, hence it is ignored. It remains one <TT>int</TT> input and
two <TT>int</TT> outputs (<TT>out</TT> parameters) </BLOCKQUOTE>
<PRE>
void m([in] int len, [in,size_is(len)] double d[])
                                                m : float array -&gt; int
</PRE>
<BLOCKQUOTE> <TT>len</TT> is a dependent parameter, hence is ignored. The
only input is the <TT>double</TT> array </BLOCKQUOTE>
<PRE>
void n([in] int inputlen, [out] int * outputlen, 
       [in,out,size_is(inputlen),length_is(*outputlen)] double d[])
                                                n : float array -&gt; float array
</PRE>
<BLOCKQUOTE> The two parameters <TT>inputlen</TT> and <TT>outputlen</TT> are
dependent, hence ignored. The <TT>double</TT> array is both an input
and an output. </BLOCKQUOTE>
<PRE>
void p([in] int dimx, [in] int dimy,
       [in,out,bigarray,size_is(dimx,dimy)] double d[][])
p : (float, Bigarray.float64_elt, Bigarray.c_layout) Bigarray.Array2.t -&gt; unit
</PRE>
<BLOCKQUOTE> The two parameters <TT>dimx</TT> and <TT>dimy</TT> are dependent
(determined from the dimensions of the big array argument),
hence ignored. The two-dimensional array <TT>d</TT>, although marked <TT>[in,out]</TT>,
is a big array, hence passed as an input that will be modified in
place by the C function <TT>p</TT>. The Caml function has no outputs.
</BLOCKQUOTE>

<H5>Error checking:</H5>
For every output that is of a named type with the <TT><FONT COLOR=blue>errorcheck(</FONT></TT><TT><I><FONT COLOR=maroon>fn</FONT></I></TT><TT><FONT COLOR=blue>)</FONT></TT>
attribute, the error checking function <TT><I><FONT COLOR=maroon>fn</FONT></I></TT> is called after the C
function returns. That function is assumed to raise a Caml exception
if it finds an output denoting an error.<BR>
<BR>

<H5>Custom calling and deallocation sequences:</H5>
The IDL declaration for a function can optionally specify a custom
calling sequence and/or a custom deallocation sequence, via <TT><I><FONT COLOR=maroon>quote</FONT></I></TT>
clauses following the function declaration:
<DIV ALIGN=center><TABLE CELLSPACING=2 CELLPADDING=0>
<TR><TD ALIGN=right NOWRAP>
<TT><I><FONT COLOR=maroon>function-decl</FONT></I></TT></TD>
<TD ALIGN=right NOWRAP>::=</TD>
<TD ALIGN=left NOWRAP>
 <TT><I><FONT COLOR=maroon>attributes</FONT></I></TT> &nbsp;<TT><I><FONT COLOR=maroon>type-spec</FONT></I></TT> &nbsp;{<TT><FONT COLOR=blue>*</FONT></TT>} <TT><I><FONT COLOR=maroon>ident</FONT></I></TT> <TT><FONT COLOR=blue>(</FONT></TT> &nbsp;<TT><I><FONT COLOR=maroon>params</FONT></I></TT> <TT><FONT COLOR=blue>)</FONT></TT> 
 &nbsp;{ <TT><FONT COLOR=blue>quote</FONT></TT><TT><FONT COLOR=blue>(</FONT></TT> <TT><I><FONT COLOR=maroon>ident</FONT></I></TT> <TT><FONT COLOR=blue>,</FONT></TT> &nbsp;<TT><I><FONT COLOR=maroon>string</FONT></I></TT> <TT><FONT COLOR=blue>)</FONT></TT> }</TD>
</TR></TABLE></DIV>
The general shape of a <TT>camlidl</TT>-generated stub function is as
follows:
<PRE>
value caml_wrapper(value camlparam1, ..., value camlparamK)

  /* Convert the function parameters from Caml to C */
  param1 = ...;
  ...
  paramN = ...;
  /* Call the C function 'ident' */
  _res = ident(param1, ..., paramN);
  /* Convert the function result and out parameters to Caml values */
  camlres = ...;
  /* Return result to Caml */
  return camlres;

</PRE>
A <TT><FONT COLOR=blue>quote(call,</FONT></TT> <TT><I><FONT COLOR=maroon>string</FONT></I></TT> <TT><FONT COLOR=blue>)</FONT></TT> clause causes the C statements in
<TT><I><FONT COLOR=maroon>string</FONT></I></TT> to be inserted in the generated stub code
instead of the default calling sequence <TT>_res = ident(param1, ..., paramN)</TT>.
Thus, the statements in <TT><I><FONT COLOR=maroon>string</FONT></I></TT> find the converted parameters in
local variables that have the same names as the parameters in the IDL
declaration, and should leave the result of the function, if any, in
the local variable named <TT>_res</TT>.<BR>
<BR>
A <TT><FONT COLOR=blue>quote(dealloc,</FONT></TT> <TT><I><FONT COLOR=maroon>string</FONT></I></TT> <TT><FONT COLOR=blue>)</FONT></TT> clause causes the C statements in
<TT><I><FONT COLOR=maroon>string</FONT></I></TT> to be inserted in the generated stub code just before the
stub function returns, hence after the conversion of the C function
results to Caml values. Again, the statements in <TT><I><FONT COLOR=maroon>string</FONT></I></TT> have access
to the function result in the local variable named <TT>_res</TT>, and to out
parameters in local variables having the same names as the
parameters. Since the function results and out parameters have
already been converted to Caml values, the code in <TT><I><FONT COLOR=maroon>string</FONT></I></TT> can safely
deallocate the data structures they point to.<BR>
<BR>
Custom calling sequences are typically used to rearrange or combine
function parameters, and to perform extra error checks on the
arguments and results. For instance, the Unix <TT>write</TT> system call can
be specified in IDL as follows:
<PRE>
        int write([in] int fd,
                  [in,string,length_is(len)] char * data,
                  [in] int len,
                  [in] int ofs,
                  [in] int towrite)
          quote(call,
            " /* Validate the arguments */
              if (ofs &lt; 0 || ofs + towrite &gt;= len) failwith(\"write\");
              /* Perform the write */
              _res = write(fd, data + ofs, towrite);
              /* Validate the result */
              if (_res == -1) failwith(\"write\"); ");
</PRE>Custom deallocation sequences are useful to free data structures
dynamically allocated and returned by the C function. For instance,
a C function <TT>f</TT> that returns a <TT>malloc</TT>-ed string can be specified in
IDL as follows:
<PRE>
        [string] char * f([in] int x)
          quote(dealloc, "free(_res); ");
</PRE>If the string is returned as an <TT>out</TT> parameter instead, we would write:
<PRE>
        void f ([in] int x, [out, string*] char ** str)
          quote(dealloc, "free(*str); ");
</PRE>
<A NAME="toc20"></A>
<H3><A NAME="htoc23">3.10</A>&nbsp;&nbsp;Interfaces</H3>
IDL interfaces that do not have the <TT><FONT COLOR=blue>object</FONT></TT> attribute are
essentially ignored. That is, the declarations contained in the
interface are processed as if they occurred at the top-level of the
IDL file. The <TT><FONT COLOR=blue>pointer_default</FONT></TT>, <TT><FONT COLOR=blue>int_default</FONT></TT> and
<TT><FONT COLOR=blue>long_default</FONT></TT> attributes to the interface can be
used to specify the default pointer kind and integer mappings
for the declarations contained in the interface. Other attributes, as
well as the name of the super-interface if any, are ignored.<BR>
<BR>
IDL interfaces having the <TT><FONT COLOR=blue>object</FONT></TT> attribute specify COM-style object
interfaces. The function declarations contained in the interface
specify the methods of the COM interface. Other kinds of declarations
(type declarations, <TT><FONT COLOR=blue>import</FONT></TT> statements, etc) are treated as if they
occurred at the top-level of the IDL file. An optional
super-interface can be given, in which case the COM interface
implements the methods of the super-interface in addition to those
specified in the IDL interface.
Example:
<PRE>
[object, uuid(...)] interface IA { typedef int t; int f(int x); }
[object] interface IB : IA { import "foo.idl"; void g([string] char * s); }
</PRE>This defines a type <TT>t</TT> and imports the file <TT>foo.idl</TT> as usual. In
addition, two interfaces are declared: <TT>IA</TT>, containing one
method <TT>f</TT> from <TT>int</TT> to <TT>int</TT>, and <TT>IB</TT>, containing
two methods, <TT>f</TT> from <TT>int</TT> to <TT>int</TT> and <TT>g</TT> from <TT>string</TT> to <TT>unit</TT>.<BR>
<BR>
The definition of an object interface <I>i</I> generates the following
Caml definitions:
<UL><LI>
An abstract type <I>i</I> identifying the interface.
COM interfaces of type <I>i</I> are represented in Caml
with type <I>i</I> <TT> Com.interface</TT>.
<LI>If a super-interface <I>s</I> is given, a conversion function
<I>s</I><TT>_of_</TT><I>i</I> of type
<I>i</I> <TT> Com.interface -&gt; </TT> <I>s</I> <TT> Com.interface</TT>.
<LI>If the <TT>uuid(</TT><I>iid</I><TT>)</TT> attribute is given, a value
<TT>iid_</TT><I>i</I> of type <I>i</I><TT> Com.iid</TT> holding the given interface
identifier.
<LI>A Caml class <I>i</I><TT>_class</TT>, with the same methods as the COM
interface.
<LI>A function <TT>use_</TT><I>i</I> of type <I>i</I> <TT> Com.interface -&gt; </TT><I>i</I><TT>_class</TT>, to transform a COM object into a Caml object. This
allows the methods of the COM object to be invoked from Caml.
<LI>A function <TT>make_</TT><I>i</I> of type <TT>#</TT><I>i</I><TT>_class -&gt; </TT><I>i</I>
<TT> Com.interface</TT>, to transform a Caml object into a COM object with
interface <I>i</I>. This allows the methods of the Caml object to be
invoked from any COM client.
</UL>
Example: in the <TT>IA</TT> and <TT>IB</TT> example above, the following Caml
definitions are generated for <TT>IA</TT>:
<PRE>
type iA
val iid_iA : iA Com.iid
class iA_class : iA Com.interface -&gt; object method f : int -&gt; int end
val use_iA : iA Com.interface -&gt; iA_class
val make_iA : #iA_class -&gt; iA Com.interface
</PRE>For <TT>IB</TT>, we get:
<PRE>
type iB
val iA_of_iB : iB Com.interface -&gt; iA Com.interface
class iB_class :
  iB Com.interface -&gt; object inherit iA_class method g : string -&gt; unit end
val use_iB : iB Com.interface -&gt; iB_class
val make_iB : #iB_class -&gt; iB Com.interface
</PRE>

<H5>Error handling in interfaces:</H5> Conventionally, methods of
COM interfaces always return a result of type <TT>HRESULT</TT> that says
whether the method succeeded or failed, and in the latter case returns
an error code to its caller.<BR>
<BR>
When calling an interface method from Caml, if the method returns an
<TT>HRESULT</TT> denoting failure, the exception <TT>Com.Error</TT> is raised with a
message describing the error. Successful <TT>HRESULT</TT> return values are
ignored. To make them available to Caml, <TT>camlidl</TT> defines the types
<TT>HRESULT_bool</TT> and <TT>HRESULT_int</TT>. If those types are used as return
types instead of <TT>HRESULT</TT>, failure results are mapped to
<TT>Com.Error</TT> exceptions as before, but successful results are mapped to
the Caml types <TT>bool</TT> and <TT>int</TT> respectively. (For <TT>HRESULT_bool</TT>,
the <TT>S_OK</TT> result is mapped to <TT>true</TT> and other successful results are
mapped to <TT>false</TT>. For <TT>HRESULT_int</TT>, the low 16 bits of the result
code are returned as a Caml <TT>int</TT>.)<BR>
<BR>
When calling a Caml method from a COM client, any exception that
escapes the Caml method is mapped back to a failure <TT>HRESULT</TT>. A
textual description of the uncaught exception is saved using
<TT>SetLastError</TT>, and can be consulted by the COM client using
<TT>GetLastError</TT> (this is the standard convention for passing extended
error information in COM).<BR>
<BR>
If the IDL return type of the method is not one of the <TT>HRESULT</TT>
types, any exception escaping the Caml method aborts the whole program
after printing a description of the exception. Hence, programmers of
Caml components should either use <TT>HRESULT</TT> as result type, or make
very sure that all exceptions are properly caught by the method.<BR>
<BR>
<HR>
<A HREF="main002.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Contents"></A>
<A HREF="main004.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
camlidl-doc 1.04-4 / usr / share / doc / camlidl / html / main003.html
