1
<chapter id="server-xml-reference">
2
<title><filename>.server</filename> file format reference</title>
5
This section describes the format of the <filename>.server</filename> files
6
used by applications to tell the Bonobo Activation daemon about the
7
interfaces they support.
10
<sect1 id="server-tag">
11
<title>The <sgmltag>oaf_server</sgmltag> tag</title>
14
Here follows a simple example of a minimalist
15
<filename>.server</filename> file.
19
<oaf_server iid="OAFIID:Bonobo_CosNaming_NamingContext"
21
location="/usr/lib/bonobo-activation/bonobo-activation-server">
23
</oaf_info></programlisting>
25
Each <sgmltag>oaf_server</sgmltag> entry conventionally has three mandatory
27
<emphasis>iid</emphasis> (the FAQ of the Bonobo API reference manual
28
explains how to create an iid), <!-- FIXME real link -->
29
<emphasis>type</emphasis> (can be <emphasis>exe,</emphasis> <!-- for
30
proper typesetting -->
31
<emphasis>factory,</emphasis> or <emphasis>shlib</emphasis>) and
32
<emphasis>location</emphasis>.
36
If the type is <emphasis>exe,</emphasis> <emphasis>location</emphasis> is
37
the name of the executable which creates the CORBA interfaces associated to
38
this entry and registers them to Bonobo Activation.
39
If the type is <emphasis>factory,</emphasis> <emphasis>location</emphasis>
40
is the iid of the component which can create the corresponding CORBA
42
If the type is <emphasis>shlib,</emphasis> <emphasis>location</emphasis> is
43
the name of the library the code is in: <filename>libgmf</filename>
48
<title>Portability Note</title>
50
Don't include the <filename>.so</filename> suffix common on Linux
51
systems in the <emphasis>location</emphasis> of a
52
<emphasis>shlib</emphasis> component.
57
Here follows a simple example of a component activated through a factory:
61
<oaf_server iid="OAFIID:Bonobo_Sample_Echo_Factory" type="exe"
62
location="/usr/lib/bonobo-2.0/samples/bonobo-echo-2">
65
<oaf_server iid="OAFIID:Bonobo_Sample_Echo" type="factory"
66
location="OAFIID:Bonobo_Sample_Echo_Factory">
68
</oaf_info></programlisting>
70
If you ask Bonobo Activation to activate the
71
<classname>OAFIID:Bonobo_Sample_Echo</classname> component,
72
Bonobo Activation will first check if it is a factory, make sure the
73
corresponding factory compoenent is running (by activating it. Here,
74
activating the factory component is a matter of launching the executable)
75
and call <function>create</function> on the factory.
76
It will return you that object.
80
<sect1 id="attribute-tag">
81
<title>The <sgmltag>oaf_attribute</sgmltag> tag</title>
84
Defining servers is useful (that is what <filename>.goad</filename> files
85
did light-years ago) but to use all the power of Bonobo Activation
86
(<abbrev>i.e.</abbrev> queries ;-), you have to define
87
<emphasis><sgmltag>oaf_attribute</sgmltag>s</emphasis> for each of those
88
<sgmltag>oaf_server</sgmltag> entries.
89
An example is worth all words.
93
<oaf_server iid="OAFIID:Bonobo_Sample_Echo_Factory" type="exe"
94
location="/usr/lib/bonobo-2.0/samples/bonobo-echo-2">
95
<oaf_attribute name="repo_ids" type="stringv">
96
<item value="IDL:Bonobo/GenericFactory:1.0"/>
98
<oaf_attribute name="name" type="string" value="Echo component factory"/>
99
<oaf_attribute name="description" type="string"
100
value="Bonobo Echo server factory"/>
103
<oaf_server iid="OAFIID:Bonobo_Sample_Echo" type="factory"
104
location="OAFIID:Bonobo_Sample_Echo_Factory">
105
<oaf_attribute name="repo_ids" type="stringv">
106
<item value="IDL:Demo/Echo:1.0"/>
108
<oaf_attribute name="name" type="string" value="Echo component"/>
109
<oaf_attribute name="description" type="string"
110
value="Bonobo Echo server sample program"/>
112
</oaf_info></programlisting>
114
Each <sgmltag>oaf_server</sgmltag> entry defines a set of attributes.
115
Each attribute has a given <emphasis>name,</emphasis>
116
<emphasis>type,</emphasis> and <emphasis>value.</emphasis> The types of the
117
attributes are those defined in the Bonobo Activation query langage reference
118
(<xref linkend="oaf-query-ref-types"/>).
119
Type name should be non-caps.
123
Values of type <emphasis>stringv</emphasis> are represented as follows:
126
<oaf_attribute name="repo_ids" type="stringv">
127
<item value="IDL:Bonobo/Unknown:1.0"/>
128
<item value="IDL:Bonobo/Control:1.0"/>
129
</oaf_attribute></programlisting>
131
All other types' values are simply in the <emphasis>value</emphasis> field.
135
A certain number of attributes have been normalized for GNOME.
136
If a component uses any attribute from the list, it ought to have the
137
meaning described here.
140
<!-- FIXME explode the table to paragraphs or a list or xxx -->
142
<title>Normalized attributes</title>
144
<colspec colwidth="3*" colnum="1" align="left"/>
145
<colspec colwidth="*" colnum="2" align="left"/>
146
<colspec colwidth="10*" colnum="3" align="left"/>
149
<entry>Attribute name</entry>
151
<entry>Signification</entry>
156
<!-- FIXME mention which attributes can be translated -->
158
<entry>repo_ids</entry>
159
<entry><type>stringv</type></entry>
161
the list of all <acronym>IDL</acronym> interfaces this component
162
implements, including inherited interfaces.
163
If <classname>Bonobo::Unknown</classname> is one of the
164
interfaces, the list should include all interfaces for which a
165
<function>queryInterface</function> operation on the component
171
<entry>description</entry>
172
<entry><type>string</type></entry>
174
a human readable string describing what the component can do
180
<entry><type>string</type></entry>
182
a short name for the component, suitable for display to the
183
end user, <abbrev>e.g.</abbrev> in a menu.
188
<entry>bonobo:editable</entry>
189
<entry><type>boolean</type></entry>
190
<entry>if the component allows editing of its content</entry>
195
<entry>bonobo:supported_uri_schemes</entry>
196
<entry><type>stringv</type></entry>
197
<entry>a list of protocols this component knows how to handle.
198
This only really makes sense if the component implements one
199
of the following interfaces:
200
<classname>Bonobo::PersistFile</classname> or
201
<classname>Nautilus::View</classname>
206
<entry>bonobo:supported_mime_types</entry>
207
<entry><type>stringv</type></entry>
208
<entry>a list of <acronym>MIME</acronym> types this component
209
understands as input.
210
In addition to specific <acronym>MIME</acronym> types, it is
211
possible to include supertypes (<abbrev>e.g.</abbrev>
212
<quote>image/*</quote> or <quote>text/*</quote>) or
213
<quote>*/*</quote> to indicate the component can display any
214
<acronym>MIME</acronym> type.
215
Specifying <quote>*/*</quote> is only necessary if neither
216
<emphasis>supported_uri_schemes</emphasis> nor
217
<emphasis>additional_uri_schemes</emphasis> is not specified,
218
otherwise <quote>*/*</quote> is assumed.
219
This only really makes sense if the component implements one
220
of the following interfaces:
221
<classname>Bonobo::PersistStream</classname>,
222
<classname>Bonobo::PersistFile</classname>,
223
or <classname>Nautilus::View</classname>.
228
<entry>bonobo:additional_uri_schemes</entry>
229
<entry><type>stringv</type></entry>
230
<entry>a list of protocols this component knows how to handle.
231
The component is applicable to any <acronym>URI</acronym> which
232
uses such a protocol, even if its <acronym>MIME</acronym> type is
233
not among <emphasis>supported_mime_types.</emphasis>
234
This only really makes sense if the component implements one
235
of the following interfaces:
236
<classname>Bonobo::PersistFile</classname> or
237
<classname>Nautilus::View</classname>
242
<entry>bonobo:moniker</entry>
243
<entry><type>stringv</type></entry>
249
<entry>bonobo:moniker_extender</entry>
250
<entry><type>stringv</type></entry>
256
<entry>bonobo:environment</entry>
257
<entry><type>stringv</type></entry>
258
<entry>List of environment variables that must have the
259
same values in both activator (client) and component.
260
This is useful for exe type factories. If there is
261
already a running process serving the component being
262
activated, its environment variables are compared to the
263
ones in the activator. If they match, a new reference
264
from that process is returned. If not, a new process is
265
started, which receives an evironment modified to match
266
the one in the activator for the environment keys
267
specified in this property.
273
<!-- for nautilus:view_as_foo see
274
nautilus/libnautilus-private/nautilus-view-identifier.c -->
276
<entry>nautilus:view_as_name</entry>
277
<entry><type>string</type></entry>
278
<entry>a suitable name for use as a <emphasis>View as</emphasis>
279
name. Several labels in Nautilus will be built from this value,
280
see the following attributes.
281
This must be present for any Bonobo Controls that can be
282
used as Nautilus views.
283
<!-- add reference to HIG chapter 2? (Desktop integration) -->
288
<entry>nautilus:view_as_label</entry>
289
<entry><type>string</type></entry>
290
<entry>a label (without keyboard mnemonic) for the component's menu
291
item in Nautilus' <emphasis>View as</emphasis> list (next to the
292
zoom control) as well as for its entry in the
293
<emphasis>Open with Other Viewer</emphasis> window.
295
<quote>View as <replaceable>name</replaceable></quote> where
296
<replaceable>name</replaceable> is the value of the
297
<emphasis>view_as_name</emphasis> attribute.
298
It is discouraged to rely on this fallback because it makes
299
correct translation impossible for some languages.
304
<entry>nautilus:view_as_label_with_mnemonic</entry>
305
<entry><type>string</type></entry>
306
<entry>a label (with keyboard mnemonic) for the component's menu
307
item in Nautilus' <guimenu>View</guimenu> menu.
308
Thus the mnemonic must not clash with one from a built-in menu
310
If omitted, the value of <emphasis>view_as_label</emphasis> will
316
<entry>nautilus:viewer_label</entry>
317
<entry><type>string</type></entry>
318
<entry>a label for the component's menu item in the
319
<guimenu>Open With</guimenu> submenu of Nautilus' context menu
320
for files and the <guimenu>File</guimenu> menu.
322
<quote><replaceable>name</replaceable> Viewer</quote> where
323
<replaceable>name</replaceable> is the value of the
324
<emphasis>view_as_name</emphasis> attribute.
325
It is discouraged to rely on this fallback because it makes
326
correct translation impossible for some languages.
331
<entry>nautilus:required_directory_content_mime_types</entry>
332
<entry><type>stringv</type></entry>
333
<entry>if the component is to be activated on a
334
<acronym>URI</acronym> with <acronym>MIME</acronym> type
335
<quote>special/directory</quote>, it is only really applicable
336
if the directory contains a file with one of the
337
<acronym>MIME</acronym> types listed in this attribute.
338
As before, supertypes like <quote>audio/*</quote> are allowed.
339
If this attribute is omitted, <quote>*/*</quote> is assumed.
344
<entry>nautilus:sidebar_panel_name</entry>
345
<entry><type>string</type></entry>
346
<entry>a suitable name for use as a sidebar panel label name.
347
This must be implemented by any Bonobo Controls that can be
348
used as a Nautilus sidebar view.
353
<entry>nautilus:context_menu_handler</entry>
357
<entry>nautilus:can_handle_multiple_files</entry>
361
<entry>nautilus:property_page_name</entry>
365
<entry>nautilusverb:<replaceable>verbname</replaceable></entry>
376
If <emphasis>bonobo:supported_uri_schemes</emphasis> or
377
<emphasis>bonobo:additional_uri_schemes</emphasis> is specified but
378
<emphasis>bonobo:supported_mime_types</emphasis> is not, it is assumed the
379
component can handle any type of data that might come via that protocol.
381
Some schemes may not even have an associated <acronym>MIME</acronym>
382
type for any given URI, for instance <filename>irc:</filename> or
383
<filename>news:</filename>
387
If <emphasis>bonobo:supported_mime_types</emphasis> is specified but
388
<emphasis>bonobo:supported_uri_schemes</emphasis> is not, the component
389
is assumed to be able to handle all common URI schemes (possible
390
definition: anything gnome-vfs can handle).
394
If neither <emphasis>bonobo:supported_uri_schemes</emphasis> nor
395
<emphasis>bonobo:additional_uri_schemes</emphasis> nor
396
<emphasis>bonobo:supported_mime_types</emphasis> is specified, it is
397
assumed the component cannot handle any data at all in a general way
398
and should never be generically selected for such purposes.
402
Nautilus considers a component as a view if it can handle the data
403
from a URI and implements the <classname>Nautilus::View</classname>
404
interface or <classname>Bonobo::Control</classname> and
405
<classname>Bonobo::PersistStream</classname> or
406
<classname>Bonobo::PersistFile</classname>.
414
sgml-namecase-general: t
415
sgml-general-insert-case: lower
416
sgml-parent-document: ("bonobo-activation-docs.sgml" "BOOK" "CHAPTER")
added
removed
doc/activation-api/server-xml-reference.sgml
