/usr/share/doc/camlidl/html/main005.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>
 Module Com: run-time library for COM components
</TITLE>
</HEAD>
<BODY >
<A HREF="main004.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Contents"></A>
<A HREF="main006.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H2><A NAME="htoc28">5</A>&nbsp;&nbsp;Module <TT>Com</TT>: run-time library for COM components</H2>
<A NAME="s:Com"></A>

<PRE>
type 'a interface
</PRE><BLOCKQUOTE>
The type of COM components implementing interface <CODE>'a</CODE> 
</BLOCKQUOTE>
<PRE>
type 'a iid
</PRE><BLOCKQUOTE>
The type of the interface identifier for interface <CODE>'a</CODE> 
</BLOCKQUOTE>
<PRE>
type clsid
</PRE><BLOCKQUOTE>
The type of component identifiers 
</BLOCKQUOTE>
<PRE>
type 'a opaque
</PRE><BLOCKQUOTE>
The type representing opaque pointers to values of type <CODE>'a</CODE>.
Opaque pointers are pointers with attribute <CODE>ptr</CODE> in IDL files. 
</BLOCKQUOTE>
<PRE>
exception Error of int * string * string
</PRE><BLOCKQUOTE>
Exception raised to report Com errors.
The arguments are <CODE>Error(errcode, who, what)</CODE>.
<CODE>errcode</CODE> is the Com error code (<CODE>HRESULT</CODE> code)
with the high bit clear.
<CODE>who</CODE> identifies the function or method that raised the exception.
<CODE>what</CODE> is a message explaining the cause of the error. 
</BLOCKQUOTE>
<PRE>
val initialize : unit -&gt; unit
</PRE><BLOCKQUOTE>
Initialize the COM library. Must be called once before
using any function in this module. <CODE>Com.initialize</CODE>
can be called several times, provided that <CODE>Com.uninitialize</CODE>
is called an equal number of times before the program exits. 
</BLOCKQUOTE>
<PRE>
val uninitialize : unit -&gt; unit
</PRE><BLOCKQUOTE>
Terminate the COM library. 
</BLOCKQUOTE>
<PRE>
val query_interface : 'a interface -&gt; 'b iid -&gt; 'b interface
</PRE><BLOCKQUOTE>
<CODE>Com.query_interface comp iid</CODE> asks the component <CODE>comp</CODE>
whether it supports the interface identified by <CODE>iid</CODE>.
If yes, it returns the corresponding interface of the component.
If not, it raises <CODE>Com.Error</CODE>. 
</BLOCKQUOTE>
<PRE>
type iUnknown
</PRE><BLOCKQUOTE>
The type of the interface <CODE>IUnknown</CODE>, from which all other
interfaces derive. 
</BLOCKQUOTE>
<PRE>
type iDispatch
</PRE><BLOCKQUOTE>
The type of the interface <CODE>IDispatch</CODE>, from which all
dispatch interfaces derive. 
</BLOCKQUOTE>
<PRE>
val iUnknown_of : 'a interface -&gt; iUnknown interface
</PRE><BLOCKQUOTE>
Return the <CODE>IUnknown</CODE> interface of the given component.
This operation never fails, since all components support
the <CODE>IUnknown</CODE> interface. 
</BLOCKQUOTE>
<PRE>
val combine : 'a interface -&gt; 'b interface -&gt; 'a interface
</PRE><BLOCKQUOTE>
Combine the interfaces of two components.
<CODE>Com.combine c1 c2</CODE> returns a component that supports the
union of the interfaces supported by <CODE>c1</CODE> and <CODE>c2</CODE>.
When queried for an interface, the resulting component
delegates its implementation to <CODE>c1</CODE> if <CODE>c1</CODE> implements that
interface, and otherwise delegates its implementation to <CODE>c2</CODE>. 
</BLOCKQUOTE>
<PRE>
val clsid : string -&gt; clsid
</PRE><BLOCKQUOTE>
Parse the string representation of a component identifier
(<CODE>hex8-hex4-hex4-hex4-hex12</CODE>, where <CODE>hexN</CODE> represents <CODE>N</CODE>
hexadecimal digits). 
</BLOCKQUOTE>
<PRE>
val create_instance : clsid -&gt; 'a iid -&gt; 'a interface
</PRE><BLOCKQUOTE>
<CODE>Com.create_instance clsid iid</CODE> creates an instance of
the component identified by <CODE>clsid</CODE>, and returns its <CODE>iid</CODE>
interface. The implementation of the component is searched
in the registry; if the component is implemented in a DLL,
the DLL is loaded in memory if necessary; if the component
is implemented in a separate server process, the server is
started if necessary. Raise <CODE>Com.Error</CODE> if the component
<CODE>clsid</CODE> cannot be found, or if it does not support interface
<CODE>iid</CODE>. 
</BLOCKQUOTE>
<PRE>
type 'a component_factory =
  { create : unit -&gt; 'a interface;
    clsid : clsid;
    friendly_name : string;
    ver_ind_prog_id : string;
    prog_id : string }
</PRE><BLOCKQUOTE>
Informations required for registering a Caml implementation
of a component.
<CODE>create</CODE> is a function that returns a fresh instance
of the component.
<CODE>clsid</CODE> is the component identifier.
<CODE>friendly_name</CODE> is a short description of the component
(for information only).
<CODE>ver_ind_prog_id</CODE> and <CODE>prog_id</CODE> are symbolic names for the
component. By convention, <CODE>prog_id</CODE> is <CODE>ver_ind_prog_id</CODE> plus
a version number at the end, i.e. <CODE>ver_ind_prog_id</CODE> is
<CODE>"MyCamlComponent"</CODE> while <CODE>prog_id</CODE> is <CODE>"MyCamlComponent.3"</CODE>. 
</BLOCKQUOTE>
<PRE>
val register_factory : 'a component_factory -&gt; unit
</PRE><BLOCKQUOTE>
Register a Caml implementation of a component.
<CODE>Com.register_factory f</CODE> stores the component factory <CODE>f</CODE>
in the registry. Other programs can then create instances
of the component by calling <CODE>CreateInstance</CODE> from C and C++
or <CODE>Com.create_instance</CODE> from Caml. 
</BLOCKQUOTE>
<PRE>
type hRESULT_int = int
type hRESULT_bool = bool
type bSTR = string
</PRE><BLOCKQUOTE>
The Caml types corresponding to the IDL types <CODE>HRESULT_int</CODE>,
<CODE>HRESULT_bool</CODE> and <CODE>BSTR</CODE>, respectively. 
</BLOCKQUOTE>

<HR>
<A HREF="main004.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Contents"></A>
<A HREF="main006.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
camlidl-doc 1.04-4 / usr / share / doc / camlidl / html / main005.html
