← Back to branch summary

~ubuntu-branches/ubuntu/oneiric/dbus-glib/oneiric-updates

« back to all changes in this revision

Viewing changes to doc/reference/xml/dbus-glib-lowlevel.xml

  • Committer: Bazaar Package Importer
  • Author(s): Simon McVittie
  • Date: 2010-08-16 19:52:19 UTC
  • mfrom: (2.2.1 experimental) (2.1.9 squeeze)
  • Revision ID: james.westby@ubuntu.com-20100816195219-ig40gau6zeskqey2
Tags: 0.88-2
Re-upload to unstable, with release team acknowledgement for squeeze

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/reference/xml/dbus-glib-lowlevel.xml
1
 
<?xml version="1.0"?>
2
 
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
3
 
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
4
 
<!ENTITY dbus-binding-tool SYSTEM "dbus-binding-tool.xml">
5
 
<!ENTITY version SYSTEM "version.xml">
6
 
]>
7
 
<refentry id="dbus-glib-DBus-GLib-low-level">
8
 
<refmeta>
9
 
<refentrytitle role="top_of_page" id="dbus-glib-DBus-GLib-low-level.top_of_page">DBus GLib low level</refentrytitle>
10
 
<manvolnum>3</manvolnum>
11
 
<refmiscinfo>DBUS-GLIB Library</refmiscinfo>
12
 
</refmeta>
13
 
 
14
 
<refnamediv>
15
 
<refname>DBus GLib low level</refname>
16
 
<refpurpose>DBus lower level functions</refpurpose>
17
 
</refnamediv>
18
 
<refsect1 id="dbus-glib-DBus-GLib-low-level.stability-level">
19
 
<title>Stability Level</title>
20
 
Unstable, unless otherwise indicated
21
 
</refsect1>
22
 
 
23
 
<refsynopsisdiv id="dbus-glib-DBus-GLib-low-level.synopsis" role="synopsis">
24
 
<title role="synopsis.title">Synopsis</title>
25
 
 
26
 
<synopsis>
27
 
<link linkend="void">void</link>                <link linkend="dbus-set-g-error">dbus_set_g_error</link>                    (<link linkend="GError">GError</link> **gerror,
28
 
                                                         <link linkend="DBusError">DBusError</link> *derror);
29
 
<link linkend="void">void</link>                <link linkend="dbus-connection-setup-with-g-main">dbus_connection_setup_with_g_main</link>   (<link linkend="DBusConnection">DBusConnection</link> *connection,
30
 
                                                         <link linkend="GMainContext">GMainContext</link> *context);
31
 
<link linkend="void">void</link>                <link linkend="dbus-server-setup-with-g-main">dbus_server_setup_with_g_main</link>       (<link linkend="DBusServer">DBusServer</link> *server,
32
 
                                                         <link linkend="GMainContext">GMainContext</link> *context);
33
 
</synopsis>
34
 
</refsynopsisdiv>
35
 
 
36
 
 
37
 
 
38
 
 
39
 
 
40
 
 
41
 
 
42
 
 
43
 
 
44
 
<refsect1 id="dbus-glib-DBus-GLib-low-level.description" role="desc">
45
 
<title role="desc.title">Description</title>
46
 
<para>
47
 
These functions can be used to access lower level of DBus.</para>
48
 
<para>
49
 
</para>
50
 
</refsect1>
51
 
 
52
 
<refsect1 id="dbus-glib-DBus-GLib-low-level.details" role="details">
53
 
<title role="details.title">Details</title>
54
 
<refsect2 id="dbus-set-g-error" role="function">
55
 
<title>dbus_set_g_error ()</title>
56
 
<indexterm zone="dbus-set-g-error"><primary sortas="dbus_set_g_error">dbus_set_g_error</primary></indexterm><programlisting><link linkend="void">void</link>                dbus_set_g_error                    (<link linkend="GError">GError</link> **gerror,
57
 
                                                         <link linkend="DBusError">DBusError</link> *derror);</programlisting>
58
 
<para>
59
 
Store the information from a DBus method error return into a
60
 
GError.  For the normal case of an arbitrary remote process,
61
 
the error code will be DBUS_GERROR_REMOTE_EXCEPTION.  Now,
62
 
DBus errors have two components; a message and a "name". 
63
 
The former is an arbitrary (normally American English) string.  
64
 
The second is a string like com.example.FooFailure which 
65
 
programs can use as a conditional source.  Because a GError
66
 
only has one string, we use a hack to encode both values:
67
 
</para>
68
 
<para>
69
 
&lt;human readable string&gt;&lt;null&gt;&lt;error name&gt;&lt;null&gt;
70
 
</para>
71
 
<para>
72
 
You can use the following code to retrieve both values:
73
 
</para>
74
 
<para>
75
 
<informalexample><programlisting>const char *msg = error->message;
76
 
size_t len = strlen(msg);
77
 
const char *error_name = msg+len+1;</programlisting></informalexample></para>
78
 
<para>
79
 
</para><variablelist role="params">
80
 
<varlistentry><term><parameter>gerror</parameter>&#160;:</term>
81
 
<listitem><simpara> an error
82
 
</simpara></listitem></varlistentry>
83
 
<varlistentry><term><parameter>derror</parameter>&#160;:</term>
84
 
<listitem><simpara>
85
 
</simpara></listitem></varlistentry>
86
 
</variablelist></refsect2>
87
 
<refsect2 id="dbus-connection-setup-with-g-main" role="function">
88
 
<title>dbus_connection_setup_with_g_main ()</title>
89
 
<indexterm zone="dbus-connection-setup-with-g-main"><primary sortas="dbus_connection_setup_with_g_main">dbus_connection_setup_with_g_main</primary></indexterm><programlisting><link linkend="void">void</link>                dbus_connection_setup_with_g_main   (<link linkend="DBusConnection">DBusConnection</link> *connection,
90
 
                                                         <link linkend="GMainContext">GMainContext</link> *context);</programlisting>
91
 
<para>
92
 
Sets the watch and timeout functions of a <link linkend="DBusConnection"><type>DBusConnection</type></link>
93
 
to integrate the connection with the GLib main loop.
94
 
Pass in <link linkend="NULL--CAPS"><type>NULL</type></link> for the <link linkend="GMainContext"><type>GMainContext</type></link> unless you're
95
 
doing something specialized.
96
 
</para>
97
 
<para>
98
 
If called twice for the same context, does nothing the second
99
 
time. If called once with context A and once with context B,
100
 
context B replaces context A as the context monitoring the
101
 
connection.</para>
102
 
<para>
103
 
</para><variablelist role="params">
104
 
<varlistentry><term><parameter>connection</parameter>&#160;:</term>
105
 
<listitem><simpara> the connection
106
 
</simpara></listitem></varlistentry>
107
 
<varlistentry><term><parameter>context</parameter>&#160;:</term>
108
 
<listitem><simpara> the <link linkend="GMainContext"><type>GMainContext</type></link> or <link linkend="NULL--CAPS"><type>NULL</type></link> for default context
109
 
</simpara></listitem></varlistentry>
110
 
</variablelist></refsect2>
111
 
<refsect2 id="dbus-server-setup-with-g-main" role="function">
112
 
<title>dbus_server_setup_with_g_main ()</title>
113
 
<indexterm zone="dbus-server-setup-with-g-main"><primary sortas="dbus_server_setup_with_g_main">dbus_server_setup_with_g_main</primary></indexterm><programlisting><link linkend="void">void</link>                dbus_server_setup_with_g_main       (<link linkend="DBusServer">DBusServer</link> *server,
114
 
                                                         <link linkend="GMainContext">GMainContext</link> *context);</programlisting>
115
 
<para>
116
 
Sets the watch and timeout functions of a <link linkend="DBusServer"><type>DBusServer</type></link>
117
 
to integrate the server with the GLib main loop.
118
 
In most cases the context argument should be <link linkend="NULL--CAPS"><type>NULL</type></link>.
119
 
</para>
120
 
<para>
121
 
If called twice for the same context, does nothing the second
122
 
time. If called once with context A and once with context B,
123
 
context B replaces context A as the context monitoring the
124
 
connection.</para>
125
 
<para>
126
 
</para><variablelist role="params">
127
 
<varlistentry><term><parameter>server</parameter>&#160;:</term>
128
 
<listitem><simpara> the server
129
 
</simpara></listitem></varlistentry>
130
 
<varlistentry><term><parameter>context</parameter>&#160;:</term>
131
 
<listitem><simpara> the <link linkend="GMainContext"><type>GMainContext</type></link> or <link linkend="NULL--CAPS"><type>NULL</type></link> for default
132
 
</simpara></listitem></varlistentry>
133
 
</variablelist></refsect2>
134
 
 
135
 
</refsect1>
136
 
 
137
 
 
138
 
 
139
 
 
140
 
</refentry>