com_gen

MODULE

com_gen

MODULE SUMMARY

Comet code generator from COM type libraries.

DESCRIPTION

The com_gen module generates stub code from COM type libraries. This makes it as easy to use COM objects in erlang as in other languages with COM capabilies (such as Visual Basic or Microsoft Java). OK, not quite as easy, but not really difficult anyway.

It also makes it possible to use the early-binding virtual interfaces available for most COM classes. This is often way faster than going through the Dispatch/Invoke-interface.

The com_gen module takes a COM interface and generates erlang source code files in the current directory. It can generate just one type, or a whole typelib with several types. There are options controlling the output.

These options are available, a (D) indicates a default option:

Option           Explanation
=================================================================
fix_names (D)    Fix names to reasonable Erlang names

keep_names       Keeps the names as is, requiring '

prefix           A prefix added before each name

prefix_these     A list of names to prefix (empty means all)
      
also_prefix_these
                 Include the given names to be prefixed

dont_prefix_these
                 Remove the given names from the list of
                 names being prefixed

suffix           A suffix added after each name

class_suffix     A suffix added after class names

{verbose, Lvl}   The amount of feedback while generating
      1 (D)      Only write type library name
      2          Write each type in a library
      3          Write each member in a type (e.g. each function)

no_optional      Prevents generation of multiple functions with
                 optional arguments

virtual          Generate virtual interfaces (dispatch interfaces are
                 generated with the suffix _disp)

no_base_virtual  Generate virtual interfaces without including
                 functions in the interhited interface in each
                 interface module

    

The name fixing is made to make it easier to use COM object in erlang. It removes any initial _ (underscores), and changes the first letter to lower case. Thus _Connection -> connection and EOF -> eOF. Without the name fixing (option keep_names), each COM name has to be surrounded with ' (ticks).

Sometimes names are unappropriate or clashes with other names, e.g. _Application -> application. In those cases a prefix can be given.

By default, the following names will be prefixed with c_: end, fun, when. Names that might be added are application, receive, throw, etc.

Each interface generates a file with stubs that calls the appropriate erl_com function. If the function has optional in arguments, several version with different cardinality is generated.

Virtual interfaces that inherits from other interfaces, are normally recursively generated to include there base interface functions. This makes comet behave more like C++ or Visual Basic when using interfaces with inheritance. (This can be turned off with the no_base_virtual option.)

When generating from a library, lot's of files will be created. All types in the library that comet recognizes will be generated as files.

Note that the options for virtual or dispatch does not prevent dispatch-interfaces to be generated, however they will have another name.

Often in COM, the same name is used for different members. To avoid name clashes, com_gen has a simple rule: properties are prefixed with put_, get_ or put_ref_, and methods are suffixed with _ (underscore). Name changes will be reported with warnings from com_gen.

The current default options for com_gen are: use name fixing, prefix c_, no suffix, class suffix _class, verbose level 1 (print type names, but not mebmers), generate multiple functions for optional in parameters and prefer dispatch-interfaces.

EXPORTS

gen_enum(ComInterface, EnumName) -> {Erlfilename, Hrlfilename, ok}
gen_enum(ComInterface, EnumName, Options) -> {Erlfilename, Hrlfilename, ok}

Types:
EnumName = string()

The gen_enum function is used to generate a COM enum from a type library. The enum yields both a header file and a module with the same contents.

The header file contains the enum values as defines, for inclusion in an erlang module.

The module file contains the values as functions, and is useful when experimenting in an erlang shell.

gen_coclass(ClassName, ClsID) -> {ok, Filename}
gen_coclass(ClassName, ClsID, Options) -> {ok, Filename}

Types:
ClassName = ClsID = Filename = string()

This functions generates a stub for a COM class. Both the name and the GUID has to be specified.

The erlang module only contatins create-functions for instance creation, and iid and name.

Note that no checking is performed on the ClsID parameter. This function is rarely used, instead generation is done from the type library with gen_typelib.

gen_interface(ComInterface, VirtualOrDispatch) -> {ok, Filename}
gen_interface(ComInterface, VirtualOrDispatch, Options) -> {ok, Filename}
gen_interface(ComInterface, IntfName, VirtualOrDispatch) -> {ok, Filename}
gen_interface(ComInterface, IntfName, VirtualOrDispatch, Options) -> {ok, Filename}

Types:
VirtualOrDispatch = virtual | dispatch
IntfName, Filename = string()

This function generates stub files for an interface. For each of the methods (and property functions) in the interface, a function is generated.

The VirtualOrDispatch flag is used to specify if virtual interfaces are to be generated. If it virtual is given, virtual and dispatch versions are generated, the dispatch interfaces have the suffix _disp. If dispatch is given, only dispatch interfaces are generated, without suffix.

The options can specify whether several versions for optional parameters is generated, and if inherited functions should be included in virtual interfaces.

Note that currently, no optional out parameters provided in the interface stubs, to use them, erl_com:invoke has to be called directly.

AUTHORS

Jakob Cederlund - support@erlang.ericsson.se