[Caml-list] CamlIDL documentation and COM issues

[Caml-list] CamlIDL documentation and COM issues

[Florian Hars]

I am trying to write an interface to an existing C library and I intend 
to use CamlIDL for this task, but I am missing some more HOWTO-like 
documentation.

The library uses a pattern that should be common enough to supported in 
CamlIDL (and explained in the hints on writing IDL files): there is a 
struct that is only of internal relavance, and there is an open and a 
close function that returns or frees a pointer to such a struct, and 
several functions that operate on such a handle:

typedef struct { /* things */ } Foo;
typedef Foo * FooHandle;
FooHandle FooOpen(args...);
int FooOperate(FooHandle fhdl, args...);
void FooClose(FooHandle fhdl);

Now all I need is a way to put this handle into a Caml variable (and, 
optionally, to call FooClose automatically whenever the handle runs out 
of scope). It looks like the [abstract] and [ptr] attributes, either 
alone or in combination, might be relevant for this task. But [ptr] 
requires the Com module, which I do not want to use. (OK, it is tiny 
under unix, but still... what happens if I ever recompile the program 
under windoze? Shouldn't the generally useful features for interfacing 
to C/C++ and the COM-specific stuff be somehow separated, like in a 
module Idl and another module Com? This would certainly help to reduce 
the prevailing confusion over the possible uses of CamlIDL. Or is it 
irrelevant for my problem?)

An example for the use of errorcheck(fn) and a remark on the type of fn 
in errorcheck might be helpful, too.

Oh, and shouldn't the example on page 24 of the Manual (1.0.4) read

  double time() quote(call, "_res=....; ");
                      ^^^^^^
Or is "call" implicit if no ident is given in a quote in a function 
definition?

Yours, Florian Hars.

-------------------
To unsubscribe, mail caml-list-request@inria.fr Archives: http://caml.inria.fr
Bug reports: http://caml.inria.fr/bin/caml-bugs FAQ: http://caml.inria.fr/FAQ/
Beginner's list: http://groups.yahoo.com/group/ocaml_beginners

Re: [Caml-list] CamlIDL documentation and COM issues

[Dmitry Bely]

Florian Hars <florian@hars.de> writes:

> I am trying to write an interface to an existing C library and I
> intend to use CamlIDL for this task, but I am missing some more
> HOWTO-like documentation.
>
> The library uses a pattern that should be common enough to supported
> in CamlIDL (and explained in the hints on writing IDL files): there is
> a struct that is only of internal relavance, and there is an open and
> a close function that returns or frees a pointer to such a struct, and
> several functions that operate on such a handle:
>
> typedef struct { /* things */ } Foo;
> typedef Foo * FooHandle;
> FooHandle FooOpen(args...);
> int FooOperate(FooHandle fhdl, args...);
> void FooClose(FooHandle fhdl);
>
> Now all I need is a way to put this handle into a Caml variable (and,
> optionally, to call FooClose automatically whenever the handle runs
> out of scope). It looks like the [abstract] and [ptr] attributes,
> either alone or in combination, might be relevant for this task. But
> [ptr] requires the Com module, which I do not want to use. (OK, it is
> tiny under unix, but still...

It's easy:

[interface.idl]
quote(c,"#include <foo-native-definition.h>");
typedef [abstract,finalize(FooClose)] void* FooHandle;
FooHandle FooOpen(args...);
int FooOperate(FooHandle fhdl, args...);
void FooClose(FooHandle fhdl);

$camlidl -no-include interface.idl

FooClose() will be called automatically when Foo instance is
garbage-collected.

> what happens if I ever recompile the
> program under windoze? Shouldn't the generally useful features for
> interfacing to C/C++ and the COM-specific stuff be somehow separated,
> like in a module Idl and another module Com? This would certainly help
> to reduce the prevailing confusion over the possible uses of
> CamlIDL. Or is it irrelevant for my problem?)

Com module works under unix and windows (under Unix some COM stuff is
emulated), so there is no such problem.

> An example for the use of errorcheck(fn) and a remark on the type of
> fn in errorcheck might be helpful, too.

If you write IDL definition

typedef [errorcheck(checkFoo)] something Foo;

then checkFoo() should have C prototype

void check(Foo);

> Oh, and shouldn't the example on page 24 of the Manual (1.0.4) read
>
>   double time() quote(call, "_res=....; ");
>                       ^^^^^^
> Or is "call" implicit if no ident is given in a quote in a function
> definition?

Yes, "call" can be ommited:

[camlidl/compiler/parser_midl.mly]
...
opt_quotes:
    opt_quotes QUOTE LPAREN STRING RPAREN
        { ("call", $4) :: $1 }
  | opt_quotes QUOTE LPAREN ident COMMA STRING RPAREN
        { ($4, $6) :: $1 }
  | /* empty */
        { [] }
;

But you are right, this doesn't seem to be documented in the manual. Ask
Xavier Leroy for the correction.

Hope to hear from you soon,
Dmitry


-------------------
To unsubscribe, mail caml-list-request@inria.fr Archives: http://caml.inria.fr
Bug reports: http://caml.inria.fr/bin/caml-bugs FAQ: http://caml.inria.fr/FAQ/
Beginner's list: http://groups.yahoo.com/group/ocaml_beginners

Re: [Caml-list] CamlIDL documentation and COM issues

[Florian Hars]

Dmitry Bely wrote:
> It's easy:
> typedef [abstract,finalize(FooClose)] void* FooHandle;

Nice, now all I need is a debian package for camlidl 1.04 to get this 
working :-).
But there are more things I cannot figure out reading the manual:

The library I want to use contains constructs like

typedef struct {
   int numThings;
   int *the1stThings;
   int *the2ndThings;
    /* more stuff */
} FOOThing;

Can I translate this to

struct FOOThing {
    [length_is(numThings)] int (*the1stThings) [];
    [length_is(numThings)] int (*the2ndThings) [];
     /* more stuff */
};

Will this work as expected? From a quick look at the machine generated C 
code, the answer seems to be yes, but the manual doesn't say much about 
how camlidl deals with the array/pointer ambiguity in C, except that it 
mentions (*x)[] as an example for the syntax of type declarations.
And what is the difference between length_is() and size_is(), except 
that the latter is checked after the former?

And who has to do the name mangling? FOOThing is no valid type or 
variable name in ocaml. It looks like camlidl just converts the first 
character to lowercase, but can I control this better? I can use 
[mlname="thing"] on struct fields, something like
int [quote("_ret=FOOOperate(args...)")] operate(args...);
for functions, but what about structs and typedefs? Wouldn't it be 
usefull to generalize the mlname attribute to all cases where names on 
both sides of the translation might be different?

Yours, Florian.
-------------------
To unsubscribe, mail caml-list-request@inria.fr Archives: http://caml.inria.fr
Bug reports: http://caml.inria.fr/bin/caml-bugs FAQ: http://caml.inria.fr/FAQ/
Beginner's list: http://groups.yahoo.com/group/ocaml_beginners

Re: [Caml-list] CamlIDL documentation and COM issues

[Dmitry Bely]

Florian Hars <hars@bik-gmbh.de> writes:

>> It's easy:
>> typedef [abstract,finalize(FooClose)] void* FooHandle;
>
> Nice, now all I need is a debian package for camlidl 1.04 to get this
> working :-).
> But there are more things I cannot figure out reading the manual:
>
> The library I want to use contains constructs like
>
> typedef struct {
>    int numThings;
>    int *the1stThings;
>    int *the2ndThings;
>     /* more stuff */
> } FOOThing;
>
> Can I translate this to
>
> struct FOOThing {
>     [length_is(numThings)] int (*the1stThings) [];
>     [length_is(numThings)] int (*the2ndThings) [];
>      /* more stuff */
> };
>
> Will this work as expected? From a quick look at the machine generated
> C code, the answer seems to be yes, but the manual doesn't say much
> about how camlidl deals with the array/pointer ambiguity in C, except
> that it mentions (*x)[] as an example for the syntax of type
> declarations.

Your declaration is wrong, just look into generated C header
(camlidl -header). Why simply not to use

typedef struct {
   int numThings;
   [size_is(numThings)] int *the1stThings;
   [size_is(numThings)] int *the2ndThings;
    /* more stuff */
} FOOThing;

?

> And what is the difference between length_is() and size_is(), except
> that the latter is checked after the former?

See

http://msdn.microsoft.com/library/en-us/midl/mi-laref_1r1h.asp

:-)

> And who has to do the name mangling? FOOThing is no valid type or
> variable name in ocaml. It looks like camlidl just converts the first
> character to lowercase, but can I control this better? I can use
> [mlname="thing"] on struct fields, something like
> int [quote("_ret=FOOOperate(args...)")] operate(args...);
> for functions, but what about structs and typedefs? Wouldn't it be
> usefull to generalize the mlname attribute to all cases where names on
> both sides of the translation might be different?

Maybe. Ask Xavier Leroy if he's like this idea.

Hope to hear from you soon,
Dmitry


-------------------
To unsubscribe, mail caml-list-request@inria.fr Archives: http://caml.inria.fr
Bug reports: http://caml.inria.fr/bin/caml-bugs FAQ: http://caml.inria.fr/FAQ/
Beginner's list: http://groups.yahoo.com/group/ocaml_beginners