source: pkg/main/libbonobo/trunk/doc/activation-api/xml/registration.xml @ 479

Revision 479, 16.7 KB checked in by alanbach-guest, 6 years ago (diff)

Libbonobo 2.18.0 updates
Line 
1<refentry id="bonobo-activation-Registration">
2<refmeta>
3<refentrytitle role="top_of_page">Registration</refentrytitle>
4<manvolnum>3</manvolnum>
5<refmiscinfo>BONOBO-ACTIVATION Library</refmiscinfo>
6</refmeta>
7
8<refnamediv>
9<refname>Registration</refname>
10<refpurpose>Registering CORBA objects to Bonobo Activation.</refpurpose>
11<!--[<xref linkend="desc" endterm="desc.title"/>]-->
12</refnamediv>
13
14<refsynopsisdiv role="synopsis">
15<title role="synopsis.title">Synopsis</title>
16
17<synopsis>
18
19#include &lt;bonobo-activation/bonobo-activation.h&gt;
20
21
22enum                <link linkend="Bonobo-RegistrationResult">Bonobo_RegistrationResult</link>;
23<link linkend="void">void</link>                <link linkend="bonobo-activation-unregister-active-server">bonobo_activation_unregister_active_server</link>
24                                                        (const <link linkend="char">char</link> *iid,
25                                                         <link linkend="CORBA-Object">CORBA_Object</link> obj);
26<link linkend="void">void</link>                <link linkend="bonobo-activation-registration-env-free">bonobo_activation_registration_env_free</link>
27                                                        (<link linkend="GSList">GSList</link> *reg_env);
28<link linkend="GSList">GSList</link>*             <link linkend="bonobo-activation-registration-env-set">bonobo_activation_registration_env_set</link>
29                                                        (<link linkend="GSList">GSList</link> *reg_env,
30                                                         const <link linkend="char">char</link> *name,
31                                                         const <link linkend="char">char</link> *value);
32<link linkend="void">void</link>                <link linkend="bonobo-activation-registration-env-set-global">bonobo_activation_registration_env_set_global</link>
33                                                        (<link linkend="GSList">GSList</link> *reg_env,
34                                                         <link linkend="gboolean">gboolean</link> append_if_existing);
35<link linkend="Bonobo-RegistrationResult">Bonobo_RegistrationResult</link> <link linkend="bonobo-activation-register-active-server">bonobo_activation_register_active_server</link>
36                                                        (const <link linkend="char">char</link> *iid,
37                                                         <link linkend="CORBA-Object">CORBA_Object</link> obj,
38                                                         <link linkend="GSList">GSList</link> *reg_env);
39const <link linkend="char">char</link>*         <link linkend="bonobo-activation-iid-get">bonobo_activation_iid_get</link>           (void);
40                    <link linkend="BonoboActivationPlugin">BonoboActivationPlugin</link>;
41                    <link linkend="BonoboActivationPluginObject">BonoboActivationPluginObject</link>;
42<link linkend="void">void</link>                <link linkend="bonobo-activation-plugin-use">bonobo_activation_plugin_use</link>        (<link linkend="PortableServer-Servant">PortableServer_Servant</link> servant,
43                                                         <link linkend="gpointer">gpointer</link> impl_ptr);
44<link linkend="void">void</link>                <link linkend="bonobo-activation-plugin-unuse">bonobo_activation_plugin_unuse</link>      (<link linkend="gpointer">gpointer</link> impl_ptr);
45
46</synopsis>
47</refsynopsisdiv>
48
49
50
51
52
53
54
55
56
57<refsect1 role="desc">
58<title role="desc.title">Description</title>
59<para>
60When writing a component which can be activated through
61Bonobo Activation by clients, you need to be register your component
62to Bonobo Activation once it is created.
63</para>
64</refsect1>
65
66<refsect1 role="details">
67<title role="details.title">Details</title>
68<refsect2>
69<title><anchor id="Bonobo-RegistrationResult" role="enum"/>enum Bonobo_RegistrationResult</title>
70<indexterm><primary>Bonobo_RegistrationResult</primary></indexterm><programlisting>typedef enum {
71  Bonobo_ACTIVATION_REG_SUCCESS,
72  Bonobo_ACTIVATION_REG_NOT_LISTED,
73  Bonobo_ACTIVATION_REG_ALREADY_ACTIVE,
74  Bonobo_ACTIVATION_REG_ERROR
75} Bonobo_RegistrationResult;
76</programlisting>
77<para>
78
79</para></refsect2>
80<refsect2>
81<title><anchor id="bonobo-activation-unregister-active-server" role="function"/>bonobo_activation_unregister_active_server ()</title>
82<indexterm><primary>bonobo_activation_unregister_active_server</primary></indexterm><programlisting><link linkend="void">void</link>                bonobo_activation_unregister_active_server
83                                                        (const <link linkend="char">char</link> *iid,
84                                                         <link linkend="CORBA-Object">CORBA_Object</link> obj);</programlisting>
85<para>
86Unregisters <parameter>obj</parameter> with <parameter>iid</parameter> with the local bonobo-activation-server
87daemon.</para>
88<para>
89
90</para><variablelist role="params">
91<varlistentry><term><parameter>iid</parameter>&nbsp;:</term>
92<listitem><simpara> IID of the server to unregister.
93</simpara></listitem></varlistentry>
94<varlistentry><term><parameter>obj</parameter>&nbsp;:</term>
95<listitem><simpara> CORBA::Object to unregister.
96</simpara></listitem></varlistentry>
97</variablelist></refsect2>
98<refsect2>
99<title><anchor id="bonobo-activation-registration-env-free" role="function"/>bonobo_activation_registration_env_free ()</title>
100<indexterm><primary>bonobo_activation_registration_env_free</primary></indexterm><programlisting><link linkend="void">void</link>                bonobo_activation_registration_env_free
101                                                        (<link linkend="GSList">GSList</link> *reg_env);</programlisting>
102<para>
103Frees the registration environment list, <parameter>reg_env</parameter>.</para>
104<para>
105
106</para><variablelist role="params">
107<varlistentry><term><parameter>reg_env</parameter>&nbsp;:</term>
108<listitem><simpara> a GSList pointer.
109</simpara></listitem></varlistentry>
110</variablelist></refsect2>
111<refsect2>
112<title><anchor id="bonobo-activation-registration-env-set" role="function"/>bonobo_activation_registration_env_set ()</title>
113<indexterm><primary>bonobo_activation_registration_env_set</primary></indexterm><programlisting><link linkend="GSList">GSList</link>*             bonobo_activation_registration_env_set
114                                                        (<link linkend="GSList">GSList</link> *reg_env,
115                                                         const <link linkend="char">char</link> *name,
116                                                         const <link linkend="char">char</link> *value);</programlisting>
117<para>
118Sets the environment variable <parameter>name</parameter> to <parameter>value</parameter> in the
119registration environment list <parameter>reg_env</parameter>.</para>
120<para>
121
122</para><variablelist role="params">
123<varlistentry><term><parameter>reg_env</parameter>&nbsp;:</term>
124<listitem><simpara> a GSList pointer.
125</simpara></listitem></varlistentry>
126<varlistentry><term><parameter>name</parameter>&nbsp;:</term>
127<listitem><simpara> the name of the env variable (must not be <link linkend="NULL:CAPS"><literal>NULL</literal></link>).
128</simpara></listitem></varlistentry>
129<varlistentry><term><parameter>value</parameter>&nbsp;:</term>
130<listitem><simpara> the value of the env variable (may be <link linkend="NULL:CAPS"><literal>NULL</literal></link>).
131</simpara></listitem></varlistentry>
132<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the new start of <parameter>reg_env</parameter>.
133</simpara></listitem></varlistentry>
134</variablelist></refsect2>
135<refsect2>
136<title><anchor id="bonobo-activation-registration-env-set-global" role="function"/>bonobo_activation_registration_env_set_global ()</title>
137<indexterm><primary>bonobo_activation_registration_env_set_global</primary></indexterm><programlisting><link linkend="void">void</link>                bonobo_activation_registration_env_set_global
138                                                        (<link linkend="GSList">GSList</link> *reg_env,
139                                                         <link linkend="gboolean">gboolean</link> append_if_existing);</programlisting>
140<para>
141Sets the global registration environment list with the
142contents of <parameter>reg_env</parameter>. If <parameter>append_if_existing</parameter> is set to
143<link linkend="FALSE:CAPS"><literal>FALSE</literal></link>, the an existing global list will be overwritten.</para>
144<para>
145
146</para><variablelist role="params">
147<varlistentry><term><parameter>reg_env</parameter>&nbsp;:</term>
148<listitem><simpara> a GSList pointer.
149</simpara></listitem></varlistentry>
150<varlistentry><term><parameter>append_if_existing</parameter>&nbsp;:</term>
151<listitem><simpara> whether or not to append to the global list.
152</simpara></listitem></varlistentry>
153</variablelist></refsect2>
154<refsect2>
155<title><anchor id="bonobo-activation-register-active-server" role="function"/>bonobo_activation_register_active_server ()</title>
156<indexterm><primary>bonobo_activation_register_active_server</primary></indexterm><programlisting><link linkend="Bonobo-RegistrationResult">Bonobo_RegistrationResult</link> bonobo_activation_register_active_server
157                                                        (const <link linkend="char">char</link> *iid,
158                                                         <link linkend="CORBA-Object">CORBA_Object</link> obj,
159                                                         <link linkend="GSList">GSList</link> *reg_env);</programlisting>
160<para>
161Registers <parameter>obj</parameter> with <parameter>iid</parameter> with the local bonobo-activation-server
162daemon.
163</para>
164<para>
165If <parameter>reg_env</parameter> is not <link linkend="NULL:CAPS"><literal>NULL</literal></link>, <parameter>obj</parameter> will be registered in such a
166way that if a client who's environment differs from the
167environment specified in <parameter>reg_env</parameter>, then another attempt
168to activate <parameter>iid</parameter> will not result in a reference to <parameter>obj</parameter>
169being returned, but rather another instance of <parameter>iid</parameter> being
170activated.
171</para>
172<para>
173So, for example, you can ensure that a seperate instance
174of the component is activated for each distinct X display
175(and screen) by:
176</para>
177<para>
178<informalexample><programlisting>
179  display_name = gdk_display_get_name (gdk_display_get_default());
180  reg_env = bonobo_activation_registration_env_set (
181                             reg_env, "DISPLAY", display_name);
182  bonobo_activation_register_active_server (iid, active_server, reg_env);
183  bonobo_activation_registration_env_free (reg_env);
184</programlisting></informalexample>
185</para>
186<para>
187If <parameter>reg_env</parameter> is <link linkend="NULL:CAPS"><literal>NULL</literal></link>, the global registration environment
188list will be used if it is set. See
189<link linkend="bonobo-activation-registration-env-set-global"><function>bonobo_activation_registration_env_set_global()</function></link>.</para>
190<para>
191
192</para><variablelist role="params">
193<varlistentry><term><parameter>iid</parameter>&nbsp;:</term>
194<listitem><simpara> IID of the server to register.
195</simpara></listitem></varlistentry>
196<varlistentry><term><parameter>obj</parameter>&nbsp;:</term>
197<listitem><simpara> CORBA::Object to register.
198</simpara></listitem></varlistentry>
199<varlistentry><term><parameter>reg_env</parameter>&nbsp;:</term>
200<listitem><simpara> the registration environment.
201</simpara></listitem></varlistentry>
202<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> status of the registration.
203</simpara></listitem></varlistentry>
204</variablelist></refsect2>
205<refsect2>
206<title><anchor id="bonobo-activation-iid-get" role="function"/>bonobo_activation_iid_get ()</title>
207<indexterm><primary>bonobo_activation_iid_get</primary></indexterm><programlisting>const <link linkend="char">char</link>*         bonobo_activation_iid_get           (void);</programlisting>
208<para>
209
210</para><variablelist role="params">
211<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>
212
213
214</simpara></listitem></varlistentry>
215</variablelist></refsect2>
216<refsect2>
217<title><anchor id="BonoboActivationPlugin" role="struct"/>BonoboActivationPlugin</title>
218<indexterm><primary>BonoboActivationPlugin</primary></indexterm><programlisting>typedef struct {
219        const BonoboActivationPluginObject *plugin_object_list;
220        const char *description;
221        gpointer dummy[8];
222} BonoboActivationPlugin;
223</programlisting>
224<para>
225Components which want to be activated as
226shared libraries must export an BonoboActivationPlugin
227structure of name <structname>Bonobo_Plugin_info</structname>.
228An exmaple of how to use it folows:
229<programlisting>
230static CORBA_Object
231hi_shlib_make_object (PortableServer_POA poa,
232                      const char *iid,
233                      gpointer impl_ptr,
234                      CORBA_Environment *ev)
235{
236        CORBA_Object object_ref;
237
238        object_ref = impl_Hi__create (poa, ev);
239        if (object_ref == CORBA_OBJECT_NIL
240            || ev->_major != CORBA_NO_EXCEPTION) {
241                printf ("Server cannot get objref\n");
242                return CORBA_OBJECT_NIL;
243        }
244
245        bonobo_activation_plugin_use (poa, impl_ptr);
246
247        return object_ref;
248}
249
250static const BonoboActivationPluginObject hi_plugin_list[] = {
251        {
252                "OAFIID:Hi:20000923",
253                hi_shlib_make_object
254        },
255        {
256                NULL
257        }
258};
259
260const BonoboActivationPlugin Bonobo_Plugin_info = {
261        hi_plugin_list,
262        "Hi example"
263};
264</programlisting>
265</para></refsect2>
266<refsect2>
267<title><anchor id="BonoboActivationPluginObject" role="struct"/>BonoboActivationPluginObject</title>
268<indexterm><primary>BonoboActivationPluginObject</primary></indexterm><programlisting>typedef struct {
269        const char *iid;
270
271        /* This routine should call bonobo_activation_plugin_use(servant, impl_ptr),
272         * as should all routines which activate CORBA objects
273         * implemented by this shared library. This needs to be done
274         * before making any CORBA calls on the object, or
275         * passing that object around. First thing after servant creation
276         * always works. :)
277         */
278
279        CORBA_Object (*activate) (PortableServer_POA poa,
280                                  const char *iid,
281                                  gpointer impl_ptr,    /* This pointer should be stored by the implementation
282                                                         * to be passed to bonobo_activation_plugin_unuse() in the
283                                                         * implementation's destruction routine. */
284                                  CORBA_Environment *ev);
285        gpointer dummy[4];
286} BonoboActivationPluginObject;
287</programlisting>
288<para>
289
290</para></refsect2>
291<refsect2>
292<title><anchor id="bonobo-activation-plugin-use" role="function"/>bonobo_activation_plugin_use ()</title>
293<indexterm><primary>bonobo_activation_plugin_use</primary></indexterm><programlisting><link linkend="void">void</link>                bonobo_activation_plugin_use        (<link linkend="PortableServer-Servant">PortableServer_Servant</link> servant,
294                                                         <link linkend="gpointer">gpointer</link> impl_ptr);</programlisting>
295<para>
296You should call this routine to activate a shared library-based
297CORBA Object. It will be called by OAF if the component exports
298correctly an <link linkend="BonoboActivationPlugin"><literal>BonoboActivationPlugin</literal></link> structure named "Bonobo_Plugin_info".</para>
299<para>
300
301</para><variablelist role="params">
302<varlistentry><term><parameter>servant</parameter>&nbsp;:</term>
303<listitem><simpara> The servant that was created
304</simpara></listitem></varlistentry>
305<varlistentry><term><parameter>impl_ptr</parameter>&nbsp;:</term>
306<listitem><simpara> The impl_ptr that was passed to the original activation routine
307</simpara></listitem></varlistentry>
308</variablelist></refsect2>
309<refsect2>
310<title><anchor id="bonobo-activation-plugin-unuse" role="function"/>bonobo_activation_plugin_unuse ()</title>
311<indexterm><primary>bonobo_activation_plugin_unuse</primary></indexterm><programlisting><link linkend="void">void</link>                bonobo_activation_plugin_unuse      (<link linkend="gpointer">gpointer</link> impl_ptr);</programlisting>
312<para>
313Side effects: May arrange for the shared library that the
314implementation is in to be unloaded.
315</para>
316<para>
317When a shlib plugin for a CORBA object is destroying an
318implementation, it should call this function to make sure that the
319shared library is unloaded as needed.</para>
320<para>
321
322</para><variablelist role="params">
323<varlistentry><term><parameter>impl_ptr</parameter>&nbsp;:</term>
324<listitem><simpara> The impl_ptr that was passed to the activation routine
325</simpara></listitem></varlistentry>
326</variablelist></refsect2>
327
328</refsect1>
329
330
331
332
333</refentry>
Note: See TracBrowser for help on using the repository browser.