Add IgnoreOnIsolate=yes to dbus.service
[platform/upstream/dbus.git] / dbus / dbus-misc.c
1 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
2 /* dbus-misc.c  A few assorted public functions that don't fit elsewhere
3  *
4  * Copyright (C) 2006 Red Hat, Inc.
5  *
6  * Licensed under the Academic Free License version 2.1
7  * 
8  * This program is free software; you can redistribute it and/or modify
9  * it under the terms of the GNU General Public License as published by
10  * the Free Software Foundation; either version 2 of the License, or
11  * (at your option) any later version.
12  *
13  * This program is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16  * GNU General Public License for more details.
17  * 
18  * You should have received a copy of the GNU General Public License
19  * along with this program; if not, write to the Free Software
20  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
21  *
22  */
23
24 #include <config.h>
25 #include "dbus-misc.h"
26 #include "dbus-internals.h"
27 #include "dbus-string.h"
28
29 /**
30  * @defgroup DBusMisc Miscellaneous
31  * @ingroup  DBus
32  * @brief Miscellaneous API that doesn't cleanly fit anywhere else
33  *
34  * @{
35  */
36
37 /**
38  * Obtains the machine UUID of the machine this process is running on.
39  *
40  * The returned string must be freed with dbus_free().
41  * 
42  * This UUID is guaranteed to remain the same until the next reboot
43  * (unless the sysadmin foolishly changes it and screws themselves).
44  * It will usually remain the same across reboots also, but hardware
45  * configuration changes or rebuilding the machine could break that.
46  *
47  * The idea is that two processes with the same machine ID should be
48  * able to use shared memory, UNIX domain sockets, process IDs, and other
49  * features of the OS that require both processes to be running
50  * on the same OS kernel instance.
51  *
52  * The machine ID can also be used to create unique per-machine
53  * instances. For example, you could use it in bus names or
54  * X selection names.
55  *
56  * The machine ID is preferred over the machine hostname, because
57  * the hostname is frequently set to "localhost.localdomain" and
58  * may also change at runtime.
59  *
60  * You can get the machine ID of a remote application by invoking the
61  * method GetMachineId from interface org.freedesktop.DBus.Peer.
62  *
63  * If the remote application has the same machine ID as the one
64  * returned by this function, then the remote application is on the
65  * same machine as your application.
66  *
67  * The UUID is not a UUID in the sense of RFC4122; the details
68  * are explained in the D-Bus specification.
69  *
70  * @returns a 32-byte-long hex-encoded UUID string, or #NULL on failure
71  */
72 char *
73 dbus_try_get_local_machine_id (DBusError *error)
74 {
75   DBusString uuid;
76   char *s;
77
78   s = NULL;
79
80   if (!_dbus_string_init (&uuid))
81     {
82       dbus_set_error (error, DBUS_ERROR_NO_MEMORY, NULL);
83       return NULL;
84     }
85
86   if (!_dbus_get_local_machine_uuid_encoded (&uuid, error))
87     {
88       _dbus_string_free (&uuid);
89       return NULL;
90     }
91
92   if (!_dbus_string_steal_data (&uuid, &s))
93     {
94       dbus_set_error (error, DBUS_ERROR_NO_MEMORY, NULL);
95       _dbus_string_free (&uuid);
96       return NULL;
97     }
98   else
99     {
100       _dbus_string_free (&uuid);
101       return s;
102     }
103
104 }
105
106 /**
107  * Obtains the machine UUID of the machine this process is running on.
108  *
109  * The returned string must be freed with dbus_free().
110  *
111  * This function returns #NULL if there was not enough memory to read
112  * the UUID, or if the UUID could not be read because the D-Bus
113  * library was installed incorrectly. In the latter case, a warning
114  * is logged.
115  *
116  * Other than its deficient error reporting, this function is the same as
117  * dbus_try_get_local_machine_id().
118  *
119  * @returns a 32-byte-long hex-encoded UUID string, or #NULL on failure
120  */
121 char *
122 dbus_get_local_machine_id (void)
123 {
124   DBusError error = DBUS_ERROR_INIT;
125   char *s;
126
127   s = dbus_try_get_local_machine_id (&error);
128
129   /* The documentation says dbus_get_local_machine_id() only fails on OOM;
130    * this can actually also fail if the D-Bus installation is faulty
131    * (no UUID), but we have no good way to report that. Historically,
132    * _dbus_get_local_machine_uuid_encoded was responsible for issuing the
133    * warning; now we do that here. */
134   if (s == NULL)
135     {
136       if (!dbus_error_has_name (&error, DBUS_ERROR_NO_MEMORY))
137         _dbus_warn_check_failed ("%s", error.message);
138
139       dbus_error_free (&error);
140       return NULL;
141     }
142
143   return s;
144 }
145
146 /**
147  * @def DBUS_MAJOR_VERSION
148  *
149  * The COMPILE TIME major version of libdbus, that is, the "X" in "X.Y.Z",
150  * as an integer literal. Consider carefully whether to use this or the
151  * runtime version from dbus_get_version().
152  */
153
154 /**
155  * @def DBUS_MINOR_VERSION
156  *
157  * The COMPILE TIME minor version of libdbus, that is, the "Y" in "X.Y.Z",
158  * as an integer literal. Consider carefully whether to use this or the
159  * runtime version from dbus_get_version().
160  */
161
162 /**
163  * @def DBUS_MICRO_VERSION
164  *
165  * The COMPILE TIME micro version of libdbus, that is, the "Z" in "X.Y.Z",
166  * as an integer literal. Consider carefully whether to use this or the
167  * runtime version from dbus_get_version().
168  */
169
170 /**
171  * @def DBUS_VERSION
172  *
173  * The COMPILE TIME version of libdbus, as a single integer that has 0 in the most
174  * significant byte, the major version in the next most significant byte,
175  * the minor version in the third most significant, and the micro version in the
176  * least significant byte. This means two DBUS_VERSION can be compared to see
177  * which is higher.
178  *
179  * Consider carefully whether to use this or the runtime version from
180  * dbus_get_version().
181  */
182
183 /**
184  * @def DBUS_VERSION_STRING
185  *
186  * The COMPILE TIME version of libdbus, as a string "X.Y.Z".
187  *
188  * Consider carefully whether to use this or the runtime version from
189  * dbus_get_version().
190  */
191
192 /**
193  * Gets the DYNAMICALLY LINKED version of libdbus. Alternatively, there
194  * are macros #DBUS_MAJOR_VERSION, #DBUS_MINOR_VERSION, #DBUS_MICRO_VERSION,
195  * and #DBUS_VERSION which allow you to test the VERSION YOU ARE COMPILED AGAINST.
196  * In other words, you can get either the runtime or the compile-time version.
197  * Think carefully about which of these you want in a given case.
198  *
199  * The libdbus full version number is "MAJOR.MINOR.MICRO" where the
200  * MINOR changes if API is added, and the MICRO changes with each
201  * release of a MAJOR.MINOR series.  The MINOR is an odd number for
202  * development releases and an even number for stable releases.
203  * 
204  * @param major_version_p pointer to return the major version, or #NULL
205  * @param minor_version_p pointer to return the minor version, or #NULL
206  * @param micro_version_p pointer to return the micro version, or #NULL 
207  * 
208  */
209 void
210 dbus_get_version (int *major_version_p,
211                   int *minor_version_p,
212                   int *micro_version_p)
213 {
214   if (major_version_p)
215     *major_version_p = DBUS_MAJOR_VERSION;
216   if (minor_version_p)
217     *minor_version_p = DBUS_MINOR_VERSION;
218   if (micro_version_p)
219     *micro_version_p = DBUS_MICRO_VERSION;
220 }
221
222
223 /** @} */ /* End of public API */
224
225 #ifdef DBUS_ENABLE_EMBEDDED_TESTS
226
227 #ifndef DOXYGEN_SHOULD_SKIP_THIS
228
229 #include "dbus-test.h"
230 #include <stdlib.h>
231
232
233 dbus_bool_t
234 _dbus_misc_test (void)
235 {
236   int major, minor, micro;
237   DBusString str;
238
239   /* make sure we don't crash on NULL */
240   dbus_get_version (NULL, NULL, NULL);
241
242   /* Now verify that all the compile-time version stuff
243    * is right and matches the runtime. These tests
244    * are mostly intended to catch various kinds of
245    * typo (mixing up major and minor, that sort of thing).
246    */
247   dbus_get_version (&major, &minor, &micro);
248
249   _dbus_assert (major == DBUS_MAJOR_VERSION);
250   _dbus_assert (minor == DBUS_MINOR_VERSION);
251   _dbus_assert (micro == DBUS_MICRO_VERSION);
252
253 #define MAKE_VERSION(x, y, z) (((x) << 16) | ((y) << 8) | (z))
254
255   /* check that MAKE_VERSION works and produces the intended ordering */
256   _dbus_assert (MAKE_VERSION (1, 0, 0) > MAKE_VERSION (0, 0, 0));
257   _dbus_assert (MAKE_VERSION (1, 1, 0) > MAKE_VERSION (1, 0, 0));
258   _dbus_assert (MAKE_VERSION (1, 1, 1) > MAKE_VERSION (1, 1, 0));
259
260   _dbus_assert (MAKE_VERSION (2, 0, 0) > MAKE_VERSION (1, 1, 1));
261   _dbus_assert (MAKE_VERSION (2, 1, 0) > MAKE_VERSION (1, 1, 1));
262   _dbus_assert (MAKE_VERSION (2, 1, 1) > MAKE_VERSION (1, 1, 1));
263
264   /* check DBUS_VERSION */
265   _dbus_assert (MAKE_VERSION (major, minor, micro) == DBUS_VERSION);
266
267   /* check that ordering works with DBUS_VERSION */
268   _dbus_assert (MAKE_VERSION (major - 1, minor, micro) < DBUS_VERSION);
269   _dbus_assert (MAKE_VERSION (major, minor - 1, micro) < DBUS_VERSION);
270   _dbus_assert (MAKE_VERSION (major, minor, micro - 1) < DBUS_VERSION);
271   
272   _dbus_assert (MAKE_VERSION (major + 1, minor, micro) > DBUS_VERSION);
273   _dbus_assert (MAKE_VERSION (major, minor + 1, micro) > DBUS_VERSION);
274   _dbus_assert (MAKE_VERSION (major, minor, micro + 1) > DBUS_VERSION);
275
276   /* Check DBUS_VERSION_STRING */
277
278   if (!_dbus_string_init (&str))
279     _dbus_assert_not_reached ("no memory");
280
281   if (!(_dbus_string_append_int (&str, major) &&
282         _dbus_string_append_byte (&str, '.') &&
283         _dbus_string_append_int (&str, minor) &&
284         _dbus_string_append_byte (&str, '.') &&
285         _dbus_string_append_int (&str, micro)))
286     _dbus_assert_not_reached ("no memory");
287
288   _dbus_assert (_dbus_string_equal_c_str (&str, DBUS_VERSION_STRING));
289
290   _dbus_string_free (&str);
291    
292   return TRUE;
293 }
294
295 #endif /* !DOXYGEN_SHOULD_SKIP_THIS */
296
297 #endif