← Back to branch summary

~joel-auterson/ubuntu/maverick/ibus/newmenuname

« back to all changes in this revision

Viewing changes to docs/reference/ibus/xml/ibusserver.xml

  • Committer: Bazaar Package Importer
  • Author(s): LI Daobing
  • Date: 2009-10-05 20:45:18 UTC
  • mfrom: (1.1.5 upstream) (6.1.15 sid)
  • Revision ID: james.westby@ubuntu.com-20091005204518-069vlwrl3r8v7bbr
Tags: 1.2.0.20090927-2
https://launchpad.net/bugs/188690
https://launchpad.net/bugs/432375
* create po template when build (LP: #188690)
  - debian/rules: updated.
  - debian/clean: remove pot file when clean.
* debian/control: build depends on python-rsvg (LP: #432375)

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/reference/ibus/xml/ibusserver.xml
10
10
 
11
11
<refnamediv>
12
12
<refname>IBusServer</refname>
13
 
<refpurpose></refpurpose>
 
13
<refpurpose>Server that listen on a socket and wait for connection requests.</refpurpose>
14
14
</refnamediv>
 
15
<refsect1 id="IBusServer.stability-level">
 
16
<title>Stability Level</title>
 
17
Stable, unless otherwise indicated
 
18
</refsect1>
15
19
 
16
20
<refsynopsisdiv id="IBusServer.synopsis" role="synopsis">
17
21
<title role="synopsis.title">Synopsis</title>
36
40
<title role="object_hierarchy.title">Object Hierarchy</title>
37
41
<synopsis>
38
42
  <link linkend="GObject">GObject</link>
39
 
   +----<link linkend="IBusObject">IBusObject</link>
40
 
         +----IBusServer
 
43
   +----<link linkend="GInitiallyUnowned">GInitiallyUnowned</link>
 
44
         +----<link linkend="IBusObject">IBusObject</link>
 
45
               +----IBusServer
41
46
</synopsis>
42
47
</refsect1>
43
48
 
63
68
<refsect1 id="IBusServer.description" role="desc">
64
69
<title role="desc.title">Description</title>
65
70
<para>
 
71
An IBusServer listen on a socket and wait for connections requests,
 
72
just like DBusServer.</para>
 
73
<para>
66
74
</para>
67
75
</refsect1>
68
76
 
73
81
<indexterm zone="IBusNewConnectionFunc"><primary sortas="IBusNewConnectionFunc">IBusNewConnectionFunc</primary></indexterm><programlisting><link linkend="void">void</link>                (*IBusNewConnectionFunc)            (<link linkend="IBusServer">IBusServer</link> *server,
74
82
                                                         <link linkend="IBusConnection">IBusConnection</link> *connection);</programlisting>
75
83
<para>
 
84
Prototype of new connection callback function.
 
85
</para>
 
86
<para>
 
87
This callback should be connected to signal ::new-connection
 
88
to handle the event that a new connection is coming in.
 
89
In this handler, IBus could add a reference and continue processing the connection.
 
90
If no reference is added, the new connection will be released and closed after this signal.
 
91
</para>
 
92
<para>
 
93
<parameter>see_also</parameter>: ::new-connection</para>
 
94
<para>
76
95
</para><variablelist role="params">
77
96
<varlistentry><term><parameter>server</parameter>&#160;:</term>
78
 
<listitem><simpara>
 
97
<listitem><simpara> An IBusServer.
79
98
</simpara></listitem></varlistentry>
80
99
<varlistentry><term><parameter>connection</parameter>&#160;:</term>
81
 
<listitem><simpara>
 
100
<listitem><simpara> The corresponding IBusConnection.
82
101
</simpara></listitem></varlistentry>
83
102
</variablelist></refsect2>
84
103
<refsect2 id="IBusServer-struct" role="struct">
85
104
<title>IBusServer</title>
86
105
<indexterm zone="IBusServer-struct"><primary sortas="IBusServer">IBusServer</primary></indexterm><programlisting>typedef struct _IBusServer IBusServer;</programlisting>
87
106
<para>
 
107
An opaque object representing an IBusServer.</para>
 
108
<para>
88
109
</para></refsect2>
89
110
<refsect2 id="ibus-server-new" role="function">
90
111
<title>ibus_server_new ()</title>
91
112
<indexterm zone="ibus-server-new"><primary sortas="ibus_server_new">ibus_server_new</primary></indexterm><programlisting><link linkend="IBusServer">IBusServer</link> *        ibus_server_new                     (void);</programlisting>
92
113
<para>
 
114
New an IBusServer.</para>
 
115
<para>
93
116
</para><variablelist role="params">
94
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>
 
117
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> A newly allocated IBusServer instance.
95
118
</simpara></listitem></varlistentry>
96
119
</variablelist></refsect2>
97
120
<refsect2 id="ibus-server-listen" role="function">
99
122
<indexterm zone="ibus-server-listen"><primary sortas="ibus_server_listen">ibus_server_listen</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            ibus_server_listen                  (<link linkend="IBusServer">IBusServer</link> *server,
100
123
                                                         const <link linkend="gchar">gchar</link> *address);</programlisting>
101
124
<para>
 
125
Listens for new connections on the given address.
 
126
</para>
 
127
<para>
 
128
If there are multiple semicolon-separated address entries in the address,
 
129
tries each one and listens on the first one that works.
 
130
</para>
 
131
<para>
 
132
Returns FALSE if listening fails for any reason.
 
133
</para>
 
134
<para>
 
135
To free the server, applications must call first <link linkend="ibus-server-disconnect"><function>ibus_server_disconnect()</function></link> and then <link linkend="dbus-server-unref"><function>dbus_server_unref()</function></link>.</para>
 
136
<para>
102
137
</para><variablelist role="params">
103
138
<varlistentry><term><parameter>server</parameter>&#160;:</term>
104
 
<listitem><simpara>
 
139
<listitem><simpara> An IBusServer.
105
140
</simpara></listitem></varlistentry>
106
141
<varlistentry><term><parameter>address</parameter>&#160;:</term>
107
 
<listitem><simpara>
 
142
<listitem><simpara> Address of this server.
108
143
</simpara></listitem></varlistentry>
109
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>
 
144
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> TRUE if succeed ; FALSE otherwise.
110
145
</simpara></listitem></varlistentry>
111
146
</variablelist></refsect2>
112
147
<refsect2 id="ibus-server-disconnect" role="function">
113
148
<title>ibus_server_disconnect ()</title>
114
149
<indexterm zone="ibus-server-disconnect"><primary sortas="ibus_server_disconnect">ibus_server_disconnect</primary></indexterm><programlisting><link linkend="void">void</link>                ibus_server_disconnect              (<link linkend="IBusServer">IBusServer</link> *server);</programlisting>
115
150
<para>
 
151
Releases the server's address and stops listening for new clients.
 
152
</para>
 
153
<para>
 
154
If called more than once, only the first call has an effect. Does not modify the server's reference count.</para>
 
155
<para>
116
156
</para><variablelist role="params">
117
157
<varlistentry><term><parameter>server</parameter>&#160;:</term>
118
 
<listitem><simpara>
 
158
<listitem><simpara> An IBusServer.
119
159
</simpara></listitem></varlistentry>
120
160
</variablelist></refsect2>
121
161
<refsect2 id="ibus-server-get-address" role="function">
122
162
<title>ibus_server_get_address ()</title>
123
163
<indexterm zone="ibus-server-get-address"><primary sortas="ibus_server_get_address">ibus_server_get_address</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link> *       ibus_server_get_address             (<link linkend="IBusServer">IBusServer</link> *server);</programlisting>
124
164
<para>
 
165
Returns the address of the server, as a newly-allocated string which must be freed by the caller.</para>
 
166
<para>
125
167
</para><variablelist role="params">
126
168
<varlistentry><term><parameter>server</parameter>&#160;:</term>
127
 
<listitem><simpara>
 
169
<listitem><simpara> An IBusServer.
128
170
</simpara></listitem></varlistentry>
129
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>
 
171
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> A newly allocated string which contain address.
130
172
</simpara></listitem></varlistentry>
131
173
</variablelist></refsect2>
132
174
<refsect2 id="ibus-server-get-id" role="function">
133
175
<title>ibus_server_get_id ()</title>
134
176
<indexterm zone="ibus-server-get-id"><primary sortas="ibus_server_get_id">ibus_server_get_id</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link> *       ibus_server_get_id                  (<link linkend="IBusServer">IBusServer</link> *server);</programlisting>
135
177
<para>
 
178
Returns the unique ID of the server, as a newly-allocated string which must be freed by the caller.
 
179
</para>
 
180
<para>
 
181
This ID is normally used by clients to tell when two IBusConnection would be equivalent
 
182
(because the server address passed to <link linkend="ibus-connection-open"><function>ibus_connection_open()</function></link> will have the same guid in the two cases).
 
183
<link linkend="ibus-connection-open"><function>ibus_connection_open()</function></link> can re-use an existing connection with the same ID instead of opening a new connection.
 
184
</para>
 
185
<para>
 
186
This is an ID unique to each IBusServer. Remember that an IBusServer represents only one mode of connecting,
 
187
so e.g. a bus daemon can listen on multiple addresses which will mean it has multiple IBusServer each with
 
188
their own ID.
 
189
</para>
 
190
<para>
 
191
The ID is not a UUID in the sense of RFC4122; the details are explained in the D-Bus specification.
 
192
Returns the address of the server, as a newly-allocated string which must be freed by the caller.</para>
 
193
<para>
136
194
</para><variablelist role="params">
137
195
<varlistentry><term><parameter>server</parameter>&#160;:</term>
138
 
<listitem><simpara>
 
196
<listitem><simpara> An IBusServer.
139
197
</simpara></listitem></varlistentry>
140
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>
 
198
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> A newly allocated string which contain address.
141
199
</simpara></listitem></varlistentry>
142
200
</variablelist></refsect2>
143
201
<refsect2 id="ibus-server-is-connected" role="function">
144
202
<title>ibus_server_is_connected ()</title>
145
203
<indexterm zone="ibus-server-is-connected"><primary sortas="ibus_server_is_connected">ibus_server_is_connected</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            ibus_server_is_connected            (<link linkend="IBusServer">IBusServer</link> *server);</programlisting>
146
204
<para>
 
205
Returns TRUE if the server is still listening for new connections.</para>
 
206
<para>
147
207
</para><variablelist role="params">
148
208
<varlistentry><term><parameter>server</parameter>&#160;:</term>
149
 
<listitem><simpara>
 
209
<listitem><simpara> An IBusServer.
150
210
</simpara></listitem></varlistentry>
151
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>
 
211
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> TRUE if the server is still listening for new connections; FALSE otherwise.
152
212
</simpara></listitem></varlistentry>
153
213
</variablelist></refsect2>
154
214
<refsect2 id="ibus-server-set-auth-mechanisms" role="function">
156
216
<indexterm zone="ibus-server-set-auth-mechanisms"><primary sortas="ibus_server_set_auth_mechanisms">ibus_server_set_auth_mechanisms</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            ibus_server_set_auth_mechanisms     (<link linkend="IBusServer">IBusServer</link> *server,
157
217
                                                         const <link linkend="gchar">gchar</link> **mechanisms);</programlisting>
158
218
<para>
 
219
Sets the authentication mechanisms that this server offers to clients,
 
220
as a NULL-terminated array of mechanism names.
 
221
</para>
 
222
<para>
 
223
This function only affects connections created after it is called.
 
224
Pass NULL instead of an array to use all available mechanisms (this is the default behavior).
 
225
</para>
 
226
<para>
 
227
The D-Bus specification describes some of the supported mechanisms.</para>
 
228
<para>
159
229
</para><variablelist role="params">
160
230
<varlistentry><term><parameter>server</parameter>&#160;:</term>
161
 
<listitem><simpara>
 
231
<listitem><simpara> An IBusServer.
162
232
</simpara></listitem></varlistentry>
163
233
<varlistentry><term><parameter>mechanisms</parameter>&#160;:</term>
164
 
<listitem><simpara>
 
234
<listitem><simpara> NULL-terminated array of mechanisms.
165
235
</simpara></listitem></varlistentry>
166
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>
 
236
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>  TRUE if succeed; FALSE if insufficient memory.
167
237
</simpara></listitem></varlistentry>
168
238
</variablelist></refsect2>
169
239
 
172
242
<title role="property_details.title">Property Details</title>
173
243
<refsect2 id="IBusServer--connection-type" role="property"><title>The <literal>&quot;connection-type&quot;</literal> property</title>
174
244
<indexterm zone="IBusServer--connection-type"><primary sortas="IBusServer:connection-type">IBusServer:connection-type</primary></indexterm><programlisting>  &quot;connection-type&quot;          <link linkend="GType">GType</link>*                : Read / Write</programlisting>
175
 
<para>The connection type of server object.</para></refsect2>
 
245
<para>
 
246
The connection type of server object.</para>
 
247
<para>
 
248
</para></refsect2>
176
249
</refsect1>
177
250
 
178
251
<refsect1 id="IBusServer.signal-details" role="signals">
179
252
<title role="signals.title">Signal Details</title>
180
253
<refsect2 id="IBusServer-new-connection" role="signal"><title>The <literal>&quot;new-connection&quot;</literal> signal</title>
181
 
<indexterm zone="IBusServer-new-connection"><primary sortas="IBusServer::new-connection">IBusServer::new-connection</primary></indexterm><programlisting><link linkend="void">void</link>                user_function                      (<link linkend="IBusServer">IBusServer</link> *ibusserver,
182
 
                                                        <link linkend="GObject">GObject</link>    *arg1,
 
254
<indexterm zone="IBusServer-new-connection"><primary sortas="IBusServer::new-connection">IBusServer::new-connection</primary></indexterm><programlisting><link linkend="void">void</link>                user_function                      (<link linkend="IBusServer">IBusServer</link> *server,
 
255
                                                        <link linkend="GObject">GObject</link>    *connection,
183
256
                                                        <link linkend="gpointer">gpointer</link>    user_data)       : Run Last</programlisting>
184
257
<para>
 
258
Emitted when a new connection is coming in.
 
259
In this handler, IBus could add a reference and continue processing the connection.
 
260
If no reference is added, the new connection will be released and closed after this signal.
 
261
</para>
 
262
<para>
 
263
<note><para>Argument <parameter>user_data</parameter> is ignored in this function.</para></note>
 
264
</para>
 
265
<para>
 
266
See also: <link linkend="IBusNewConnectionFunc"><function>IBusNewConnectionFunc()</function></link>.</para>
 
267
<para>
185
268
</para><variablelist role="params">
186
 
<varlistentry><term><parameter>ibusserver</parameter>&#160;:</term>
187
 
<listitem><simpara>the object which received the signal.
 
269
<varlistentry><term><parameter>server</parameter>&#160;:</term>
 
270
<listitem><simpara> An IBusServer.
188
271
</simpara></listitem></varlistentry>
189
 
<varlistentry><term><parameter>arg1</parameter>&#160;:</term>
190
 
<listitem><simpara>
 
272
<varlistentry><term><parameter>connection</parameter>&#160;:</term>
 
273
<listitem><simpara> The corresponding IBusConnection.
191
274
</simpara></listitem></varlistentry>
192
275
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
193
276
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>