← Back to branch summary

~ubuntu-branches/ubuntu/quantal/libbonobo/quantal-201207170711

« back to all changes in this revision

Viewing changes to doc/api/sgml/bonobo-context.sgml

  • Committer: Bazaar Package Importer
  • Author(s): Sebastien Bacher
  • Date: 2005-02-18 14:40:51 UTC
  • mto: (3.1.1 etch) (1.1.25 upstream)
  • mto: This revision was merged to the branch mainline in revision 3.
  • Revision ID: james.westby@ubuntu.com-20050218144051-fo4h9qh2gim8x3wt
Tags: upstream-2.8.1
Import upstream version 2.8.1

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/api/sgml/bonobo-context.sgml
1
 
<refentry id="libbonobo-bonobo-context">
2
 
<refmeta>
3
 
<refentrytitle>bonobo-context</refentrytitle>
4
 
<manvolnum>3</manvolnum>
5
 
<refmiscinfo>LIBBONOBO Library</refmiscinfo>
6
 
</refmeta>
7
 
 
8
 
<refnamediv>
9
 
<refname>bonobo-context</refname><refpurpose>Extensible runtime service interface</refpurpose>
10
 
</refnamediv>
11
 
 
12
 
<refsynopsisdiv><title>Synopsis</title>
13
 
<synopsis>
14
 
 
15
 
 
16
 
 
17
 
<link linkend="Bonobo-Unknown">Bonobo_Unknown</link> <link linkend="bonobo-context-get">bonobo_context_get</link>           (const <link linkend="CORBA-char">CORBA_char</link> *context_name,
18
 
                                             <link linkend="CORBA-Environment">CORBA_Environment</link> *opt_ev);
19
 
void        <link linkend="bonobo-context-add">bonobo_context_add</link>              (const <link linkend="CORBA-char">CORBA_char</link> *context_name,
20
 
                                             <link linkend="Bonobo-Unknown">Bonobo_Unknown</link> context);
21
 
<link linkend="BonoboObject">BonoboObject</link>* <link linkend="bonobo-context-running-get">bonobo_context_running_get</link>    (void);
22
 
void        <link linkend="bonobo-running-context-auto-exit-unref">bonobo_running_context_auto_exit_unref</link>
23
 
                                            (<link linkend="BonoboObject">BonoboObject</link> *object);
24
 
</synopsis>
25
 
</refsynopsisdiv>
26
 
 
27
 
 
28
 
 
29
 
 
30
 
 
31
 
<refsect1>
32
 
<title>Description</title>
33
 
<para>
34
 
The bonobo-context code is designed to provide a way to
35
 
expose CORBA contexts through a single C interface. This
36
 
is so that language bindings can get away with wrapping
37
 
a single function, and yet have access to the whole
38
 
Bonobo service framework. Two examples of this are the
39
 
MonikerContext and the RunningContext ( see
40
 
Bonobo_Context.idl ).
41
 
</para>
42
 
 
43
 
<para>
44
 
  <example>
45
 
     <title>Getting and using the moniker context</title>
46
 
     <programlisting>
47
 
Bonobo_MonikerContext context;
48
 
Bonobo_Unknown        object;
49
 
 
50
 
context = bonobo_context_get ("Activation", NULL);
51
 
 
52
 
if (context == CORBA_OBJECT_NIL)
53
 
        g_error (_("Internal error, no activation context"));
54
 
 
55
 
object = Bonobo_MonikerContext_getObject (
56
 
        "file:/demo/a.jpeg", "Bonobo/Control", ev);
57
 
...
58
 
     </programlisting>
59
 
  </example>
60
 
</para>
61
 
 
62
 
<para>
63
 
The list of contexts is open and may be expanded in the future,
64
 
currently there are the following:
65
 
  <itemizedlist>
66
 
    <listitem>
67
 
      <para>
68
 
        Activation - Bonobo/MonikerContext
69
 
      </para>
70
 
    </listitem>
71
 
    <listitem>
72
 
      <para>
73
 
        Running - Bonobo/RunningContext
74
 
      </para>
75
 
    </listitem>
76
 
  </itemizedlist>
77
 
</para>
78
 
 
79
 
<para>
80
 
The running context is particularly useful for ensuring that
81
 
server processes exit cleanly when all their objects and
82
 
derived objects are dead. To do this we can simply do the
83
 
following:
84
 
</para>
85
 
<para>
86
 
  <example>
87
 
    <title>How to get a factory to quit when it is idle</title>
88
 
    <programlisting>
89
 
static void
90
 
last_unref_exit_cb (gpointer      context,
91
 
                    BonoboObject *factory)
92
 
{
93
 
        bonobo_object_unref (factory);
94
 
        <link linkend="gtk-main-quit">gtk_main_quit</link>();
95
 
}
96
 
...
97
 
int main (int argc, char **argv)
98
 
{
99
 
        ...
100
 
        bonobo_running_context_ignore_object (BONOBO_OBJREF (object));
101
 
 
102
 
        gtk_signal_connect (GTK_OBJECT (<link linkend="bonobo-context-running-get">bonobo_context_running_get</link>()),
103
 
                            "last_unref", last_unref_exit_cb, factory);
104
 
        ...
105
 
        <link linkend="bonobo-main">bonobo_main</link>();
106
 
}
107
 
    </programlisting>
108
 
  </example>
109
 
</para>
110
 
<para>
111
 
  Since this is a commonly used thing there is a helper to make this
112
 
easier:
113
 
  <example>
114
 
    <title>How to get a factory to quit when it is idle</title>
115
 
    <programlisting>
116
 
bonobo_running_context_auto_exit_unref (factory) 
117
 
    </programlisting>
118
 
  </example>
119
 
</para>
120
 
</refsect1>
121
 
 
122
 
<refsect1>
123
 
<title>Details</title>
124
 
<refsect2>
125
 
<title><anchor id="bonobo-context-get">bonobo_context_get ()</title>
126
 
<programlisting><link linkend="Bonobo-Unknown">Bonobo_Unknown</link> bonobo_context_get           (const <link linkend="CORBA-char">CORBA_char</link> *context_name,
127
 
                                             <link linkend="CORBA-Environment">CORBA_Environment</link> *opt_ev);</programlisting>
128
 
<para>
129
 
The most useful context is named 'Activation' and returns
130
 
the IDL:Bonobo/ActivationContext:1.0 interface.</para>
131
 
<para>
132
 
 
133
 
</para><informaltable pgwide="1" frame="none" role="params">
134
 
<tgroup cols="2">
135
 
<colspec colwidth="2*">
136
 
<colspec colwidth="8*">
137
 
<tbody>
138
 
<row><entry align="right"><parameter>context_name</parameter>&nbsp;:</entry>
139
 
<entry> the name of the context
140
 
</entry></row>
141
 
<row><entry align="right"><parameter>opt_ev</parameter>&nbsp;:</entry>
142
 
<entry> optional Environment, or NULL
143
 
</entry></row>
144
 
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a new reference to a global Bonobo context or CORBA_OBJECT_NIL
145
 
</entry></row>
146
 
</tbody></tgroup></informaltable></refsect2>
147
 
<refsect2>
148
 
<title><anchor id="bonobo-context-add">bonobo_context_add ()</title>
149
 
<programlisting>void        bonobo_context_add              (const <link linkend="CORBA-char">CORBA_char</link> *context_name,
150
 
                                             <link linkend="Bonobo-Unknown">Bonobo_Unknown</link> context);</programlisting>
151
 
<para>
152
 
This function adds a new context to the context system</para>
153
 
<para>
154
 
 
155
 
</para><informaltable pgwide="1" frame="none" role="params">
156
 
<tgroup cols="2">
157
 
<colspec colwidth="2*">
158
 
<colspec colwidth="8*">
159
 
<tbody>
160
 
<row><entry align="right"><parameter>context_name</parameter>&nbsp;:</entry>
161
 
<entry> the name to refer to the context by
162
 
</entry></row>
163
 
<row><entry align="right"><parameter>context</parameter>&nbsp;:</entry>
164
 
<entry> The Bonobo_Unknown; a ref. is taken on this.
165
 
</entry></row>
166
 
</tbody></tgroup></informaltable></refsect2>
167
 
<refsect2>
168
 
<title><anchor id="bonobo-context-running-get">bonobo_context_running_get ()</title>
169
 
<programlisting><link linkend="BonoboObject">BonoboObject</link>* bonobo_context_running_get    (void);</programlisting>
170
 
<para>
171
 
 
172
 
</para><informaltable pgwide="1" frame="none" role="params">
173
 
<tgroup cols="2">
174
 
<colspec colwidth="2*">
175
 
<colspec colwidth="8*">
176
 
<tbody>
177
 
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>
178
 
 
179
 
 
180
 
</entry></row>
181
 
</tbody></tgroup></informaltable></refsect2>
182
 
<refsect2>
183
 
<title><anchor id="bonobo-running-context-auto-exit-unref">bonobo_running_context_auto_exit_unref ()</title>
184
 
<programlisting>void        bonobo_running_context_auto_exit_unref
185
 
                                            (<link linkend="BonoboObject">BonoboObject</link> *object);</programlisting>
186
 
<para>
187
 
 
188
 
</para><informaltable pgwide="1" frame="none" role="params">
189
 
<tgroup cols="2">
190
 
<colspec colwidth="2*">
191
 
<colspec colwidth="8*">
192
 
<tbody>
193
 
<row><entry align="right"><parameter>object</parameter>&nbsp;:</entry>
194
 
<entry>
195
 
 
196
 
 
197
 
</entry></row>
198
 
</tbody></tgroup></informaltable></refsect2>
199
 
 
200
 
</refsect1>
201
 
 
202
 
 
203
 
 
204
 
 
205
 
</refentry>