Debian Codegraph @

htmlman/main005.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 Module Com: run-time library for COM components
10 </TITLE>
11 </HEAD>
12 <BODY >
13 <A HREF="main004.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="main006.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
16 <HR>
17
18 <H2><A NAME="htoc28">5</A>&nbsp;&nbsp;Module <TT>Com</TT>: run-time library for COM components</H2>
19 <A NAME="s:Com"></A>
20
21 <PRE>
22 type 'a interface
23 </PRE><BLOCKQUOTE>
24 The type of COM components implementing interface <CODE>'a</CODE>
25 </BLOCKQUOTE>
26 <PRE>
27 type 'a iid
28 </PRE><BLOCKQUOTE>
29 The type of the interface identifier for interface <CODE>'a</CODE>
30 </BLOCKQUOTE>
31 <PRE>
32 type clsid
33 </PRE><BLOCKQUOTE>
34 The type of component identifiers
35 </BLOCKQUOTE>
36 <PRE>
37 type 'a opaque
38 </PRE><BLOCKQUOTE>
39 The type representing opaque pointers to values of type <CODE>'a</CODE>.
40 Opaque pointers are pointers with attribute <CODE>ptr</CODE> in IDL files.
41 </BLOCKQUOTE>
42 <PRE>
43 exception Error of int * string * string
44 </PRE><BLOCKQUOTE>
45 Exception raised to report Com errors.
46 The arguments are <CODE>Error(errcode, who, what)</CODE>.
47 <CODE>errcode</CODE> is the Com error code (<CODE>HRESULT</CODE> code)
48 with the high bit clear.
49 <CODE>who</CODE> identifies the function or method that raised the exception.
50 <CODE>what</CODE> is a message explaining the cause of the error.
51 </BLOCKQUOTE>
52 <PRE>
53 val initialize : unit -&gt; unit
54 </PRE><BLOCKQUOTE>
55 Initialize the COM library. Must be called once before
56 using any function in this module. <CODE>Com.initialize</CODE>
57 can be called several times, provided that <CODE>Com.uninitialize</CODE>
58 is called an equal number of times before the program exits.
59 </BLOCKQUOTE>
60 <PRE>
61 val uninitialize : unit -&gt; unit
62 </PRE><BLOCKQUOTE>
63 Terminate the COM library.
64 </BLOCKQUOTE>
65 <PRE>
66 val query_interface : 'a interface -&gt; 'b iid -&gt; 'b interface
67 </PRE><BLOCKQUOTE>
68 <CODE>Com.query_interface comp iid</CODE> asks the component <CODE>comp</CODE>
69 whether it supports the interface identified by <CODE>iid</CODE>.
70 If yes, it returns the corresponding interface of the component.
71 If not, it raises <CODE>Com.Error</CODE>.
72 </BLOCKQUOTE>
73 <PRE>
74 type iUnknown
75 </PRE><BLOCKQUOTE>
76 The type of the interface <CODE>IUnknown</CODE>, from which all other
77 interfaces derive.
78 </BLOCKQUOTE>
79 <PRE>
80 type iDispatch
81 </PRE><BLOCKQUOTE>
82 The type of the interface <CODE>IDispatch</CODE>, from which all
83 dispatch interfaces derive.
84 </BLOCKQUOTE>
85 <PRE>
86 val iUnknown_of : 'a interface -&gt; iUnknown interface
87 </PRE><BLOCKQUOTE>
88 Return the <CODE>IUnknown</CODE> interface of the given component.
89 This operation never fails, since all components support
90 the <CODE>IUnknown</CODE> interface.
91 </BLOCKQUOTE>
92 <PRE>
93 val combine : 'a interface -&gt; 'b interface -&gt; 'a interface
94 </PRE><BLOCKQUOTE>
95 Combine the interfaces of two components.
96 <CODE>Com.combine c1 c2</CODE> returns a component that supports the
97 union of the interfaces supported by <CODE>c1</CODE> and <CODE>c2</CODE>.
98 When queried for an interface, the resulting component
99 delegates its implementation to <CODE>c1</CODE> if <CODE>c1</CODE> implements that
100 interface, and otherwise delegates its implementation to <CODE>c2</CODE>.
101 </BLOCKQUOTE>
102 <PRE>
103 val clsid : string -&gt; clsid
104 </PRE><BLOCKQUOTE>
105 Parse the string representation of a component identifier
106 (<CODE>hex8-hex4-hex4-hex4-hex12</CODE>, where <CODE>hexN</CODE> represents <CODE>N</CODE>
107 hexadecimal digits).
108 </BLOCKQUOTE>
109 <PRE>
110 val create_instance : clsid -&gt; 'a iid -&gt; 'a interface
111 </PRE><BLOCKQUOTE>
112 <CODE>Com.create_instance clsid iid</CODE> creates an instance of
113 the component identified by <CODE>clsid</CODE>, and returns its <CODE>iid</CODE>
114 interface. The implementation of the component is searched
115 in the registry; if the component is implemented in a DLL,
116 the DLL is loaded in memory if necessary; if the component
117 is implemented in a separate server process, the server is
118 started if necessary. Raise <CODE>Com.Error</CODE> if the component
119 <CODE>clsid</CODE> cannot be found, or if it does not support interface
120 <CODE>iid</CODE>.
121 </BLOCKQUOTE>
122 <PRE>
123 type 'a component_factory =
124 { create : unit -&gt; 'a interface;
125 clsid : clsid;
126 friendly_name : string;
127 ver_ind_prog_id : string;
128 prog_id : string }
129 </PRE><BLOCKQUOTE>
130 Informations required for registering a Caml implementation
131 of a component.
132 <CODE>create</CODE> is a function that returns a fresh instance
133 of the component.
134 <CODE>clsid</CODE> is the component identifier.
135 <CODE>friendly_name</CODE> is a short description of the component
136 (for information only).
137 <CODE>ver_ind_prog_id</CODE> and <CODE>prog_id</CODE> are symbolic names for the
138 component. By convention, <CODE>prog_id</CODE> is <CODE>ver_ind_prog_id</CODE> plus
139 a version number at the end, i.e. <CODE>ver_ind_prog_id</CODE> is
140 <CODE>"MyCamlComponent"</CODE> while <CODE>prog_id</CODE> is <CODE>"MyCamlComponent.3"</CODE>.
141 </BLOCKQUOTE>
142 <PRE>
143 val register_factory : 'a component_factory -&gt; unit
144 </PRE><BLOCKQUOTE>
145 Register a Caml implementation of a component.
146 <CODE>Com.register_factory f</CODE> stores the component factory <CODE>f</CODE>
147 in the registry. Other programs can then create instances
148 of the component by calling <CODE>CreateInstance</CODE> from C and C++
149 or <CODE>Com.create_instance</CODE> from Caml.
150 </BLOCKQUOTE>
151 <PRE>
152 type hRESULT_int = int
153 type hRESULT_bool = bool
154 type bSTR = string
155 </PRE><BLOCKQUOTE>
156 The Caml types corresponding to the IDL types <CODE>HRESULT_int</CODE>,
157 <CODE>HRESULT_bool</CODE> and <CODE>BSTR</CODE>, respectively.
158 </BLOCKQUOTE>
159
160 <HR>
161 <A HREF="main004.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
162 <A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Contents"></A>
163 <A HREF="main006.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
164 </BODY>
165 </HTML>