← Back to branch summary

~ubuntu-branches/ubuntu/saucy/libbonobo/saucy-proposed

« back to all changes in this revision

Viewing changes to doc/activation-api/xml/registration.xml

  • Committer: Bazaar Package Importer
  • Author(s): Sebastien Bacher
  • Date: 2010-03-30 13:59:10 UTC
  • mfrom: (1.1.27 upstream)
  • Revision ID: james.westby@ubuntu.com-20100330135910-bq8awt4jhdd71oq1
Tags: 2.24.3-0ubuntu1
* New upstream version:
  - Set up dbus environment in test-activation/test.sh 
  - Fix memory corruption 
  - Updated translations 

Show diffs side-by-side

added added

removed removed

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