xref: /titanic_41/usr/src/lib/hal/libhal/common/libhal.h (revision de7d23d85e06f547e8cd4ed4bce494209d63612a)
1 /***************************************************************************
2  * CVSID: $Id$
3  *
4  * libhal.h : HAL daemon C convenience library headers
5  *
6  * Copyright (C) 2003 David Zeuthen, <david@fubar.dk>
7  * Copyright (C) 2007 Codethink Ltd. Author Rob Taylor <rob.taylor@codethink.co.uk>
8  *
9  * Licensed under the Academic Free License version 2.1
10  *
11  * This program is free software; you can redistribute it and/or modify
12  * it under the terms of the GNU General Public License as published by
13  * the Free Software Foundation; either version 2 of the License, or
14  * (at your option) any later version.
15  *
16  * This program is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
19  * GNU General Public License for more details.
20  *
21  * You should have received a copy of the GNU General Public License
22  * along with this program; if not, write to the Free Software
23  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
24  *
25  **************************************************************************/
26 
27 #ifndef LIBHAL_H
28 #define LIBHAL_H
29 
30 #include <dbus/dbus.h>
31 
32 #if defined(__cplusplus)
33 extern "C" {
34 #if 0
35 } /* shut up emacs indenting */
36 #endif
37 #endif
38 
39 #if defined(__GNUC__)
40 #define LIBHAL_DEPRECATED __attribute__ ((deprecated))
41 #else
42 #define LIBHAL_DEPRECATED
43 #endif
44 
45 
46 #define LIBHAL_FREE_DBUS_ERROR(_dbus_error_)					\
47 	do {									\
48 		if (dbus_error_is_set(_dbus_error_))				\
49 			dbus_error_free (_dbus_error_);				\
50 	} while (0)
51 
52 
53 /**
54  * LIBHAL_CHECK_LIBHALCONTEXT:
55  * @_ctx_: the context
56  * @_ret_: what to use for return value if context is invalid
57  *
58  * Handy macro for checking whether a context is valid.
59  */
60 #define LIBHAL_CHECK_LIBHALCONTEXT(_ctx_, _ret_)				\
61 	do {									\
62 		if (_ctx_ == NULL) {						\
63 			fprintf (stderr,					\
64 				 "%s %d : LibHalContext *ctx is NULL\n", 	\
65 				 __FILE__, __LINE__);				\
66 			return _ret_;						\
67 		}								\
68 	} while(0)
69 
70 /**
71  * LibHalPropertyType:
72  *
73  * Possible types for properties on hal device objects
74  */
75 typedef enum {
76         /** Used to report error condition */
77 	LIBHAL_PROPERTY_TYPE_INVALID =    DBUS_TYPE_INVALID,
78 
79 	/** Type for 32-bit signed integer property */
80 	LIBHAL_PROPERTY_TYPE_INT32   =    DBUS_TYPE_INT32,
81 
82 	/** Type for 64-bit unsigned integer property */
83 	LIBHAL_PROPERTY_TYPE_UINT64  =    DBUS_TYPE_UINT64,
84 
85 	/** Type for double precision floating point property */
86 	LIBHAL_PROPERTY_TYPE_DOUBLE  =    DBUS_TYPE_DOUBLE,
87 
88 	/** Type for boolean property */
89 	LIBHAL_PROPERTY_TYPE_BOOLEAN =    DBUS_TYPE_BOOLEAN,
90 
91 	/** Type for UTF-8 string property */
92 	LIBHAL_PROPERTY_TYPE_STRING  =    DBUS_TYPE_STRING,
93 
94 	/** Type for list of UTF-8 strings property */
95 	LIBHAL_PROPERTY_TYPE_STRLIST =    ((int) (DBUS_TYPE_STRING<<8)+('l'))
96 } LibHalPropertyType;
97 
98 
99 typedef struct LibHalContext_s LibHalContext;
100 
101 /**
102  * LibHalIntegrateDBusIntoMainLoop:
103  * @ctx: context for connection to hald
104  * @dbus_connection: DBus connection to use in ctx
105  *
106  * Type for function in application code that integrates a
107  * DBusConnection object into its own mainloop.
108  */
109 typedef void (*LibHalIntegrateDBusIntoMainLoop) (LibHalContext *ctx,
110 						 DBusConnection *dbus_connection);
111 
112 /**
113  * LibHalDeviceAdded:
114  * @ctx: context for connection to hald
115  * @udi: the Unique Device Id
116  *
117  * Type for callback when a device is added.
118  */
119 typedef void (*LibHalDeviceAdded) (LibHalContext *ctx,
120 				   const char *udi);
121 
122 /**
123  * LibHalDeviceRemoved:
124  * @ctx: context for connection to hald
125  * @udi: the Unique Device Id
126  *
127  * Type for callback when a device is removed.
128  */
129 typedef void (*LibHalDeviceRemoved) (LibHalContext *ctx,
130 				     const char *udi);
131 
132 /**
133  * LibHalDeviceNewCapability:
134  * @ctx: context for connection to hald
135  * @udi: the Unique Device Id
136  * @capability: capability of the device
137  *
138  * Type for callback when a device gains a new capability.
139  *
140  */
141 typedef void (*LibHalDeviceNewCapability) (LibHalContext *ctx,
142 					   const char *udi,
143 					   const char *capability);
144 
145 /**
146  * LibHalDeviceLostCapability:
147  * @ctx: context for connection to hald
148  * @udi: the Unique Device Id
149  * @capability: capability of the device
150  *
151  * Type for callback when a device loses a capability.
152  *
153  */
154 typedef void (*LibHalDeviceLostCapability) (LibHalContext *ctx,
155 					    const char *udi,
156 					    const char *capability);
157 
158 /**
159  * LibHalDevicePropertyModified:
160  * @ctx: context for connection to hald
161  * @udi: the Unique Device Id
162  * @key: name of the property that has changed
163  * @is_removed: whether or not property was removed
164  * @is_added: whether or not property was added
165  *
166  * Type for callback when a property of a device changes.
167  */
168 typedef void (*LibHalDevicePropertyModified) (LibHalContext *ctx,
169 					      const char *udi,
170 					      const char *key,
171 					      dbus_bool_t is_removed,
172 					      dbus_bool_t is_added);
173 
174 /**
175  * LibHalDeviceCondition:
176  * @ctx: context for connection to hald
177  * @udi: the Unique Device Id
178  * @condition_name: name of the condition, e.g. ProcessorOverheating. Consult the HAL spec for details
179  * @condition_detail: detail of condition
180  *
181  * Type for callback when a non-continuous condition occurs on a device.
182  */
183 typedef void (*LibHalDeviceCondition) (LibHalContext *ctx,
184 				       const char *udi,
185 				       const char *condition_name,
186 				       const char *condition_detail);
187 
188 
189 /* Create a new context for a connection with hald */
190 LibHalContext *libhal_ctx_new                          (void);
191 
192 /* Enable or disable caching */
193 dbus_bool_t    libhal_ctx_set_cache                    (LibHalContext *ctx, dbus_bool_t use_cache);
194 
195 /* Set DBus connection to use to talk to hald. */
196 dbus_bool_t    libhal_ctx_set_dbus_connection          (LibHalContext *ctx, DBusConnection *conn);
197 
198 /* Get DBus connection to use to talk to hald. */
199 DBusConnection *libhal_ctx_get_dbus_connection          (LibHalContext *ctx);
200 
201 /* Set user data for the context */
202 dbus_bool_t    libhal_ctx_set_user_data                (LibHalContext *ctx, void *user_data);
203 
204 /* Get user data for the context */
205 void*          libhal_ctx_get_user_data                (LibHalContext *ctx);
206 
207 /* Set the callback for when a device is added */
208 dbus_bool_t    libhal_ctx_set_device_added             (LibHalContext *ctx, LibHalDeviceAdded callback);
209 
210 /* Set the callback for when a device is removed */
211 dbus_bool_t    libhal_ctx_set_device_removed           (LibHalContext *ctx, LibHalDeviceRemoved callback);
212 
213 /* Set the callback for when a device gains a new capability */
214 dbus_bool_t    libhal_ctx_set_device_new_capability    (LibHalContext *ctx, LibHalDeviceNewCapability callback);
215 
216 /* Set the callback for when a device loses a capability */
217 dbus_bool_t    libhal_ctx_set_device_lost_capability   (LibHalContext *ctx, LibHalDeviceLostCapability callback);
218 
219 /* Set the callback for when a property is modified on a device */
220 dbus_bool_t    libhal_ctx_set_device_property_modified (LibHalContext *ctx, LibHalDevicePropertyModified callback);
221 
222 /* Set the callback for when a device emits a condition */
223 dbus_bool_t    libhal_ctx_set_device_condition         (LibHalContext *ctx, LibHalDeviceCondition callback);
224 
225 /* Initialize the connection to hald */
226 dbus_bool_t    libhal_ctx_init                         (LibHalContext *ctx, DBusError *error);
227 
228 /* Shut down a connection to hald */
229 dbus_bool_t    libhal_ctx_shutdown                     (LibHalContext *ctx, DBusError *error);
230 
231 /* Free a LibHalContext resource */
232 dbus_bool_t    libhal_ctx_free                         (LibHalContext *ctx);
233 
234 /* Create an already initialized connection to hald */
235 LibHalContext *libhal_ctx_init_direct                  (DBusError *error);
236 
237 /* Get all devices in the Global Device List (GDL). */
238 char        **libhal_get_all_devices (LibHalContext *ctx, int *num_devices, DBusError *error);
239 
240 /* Determine if a device exists. */
241 dbus_bool_t   libhal_device_exists   (LibHalContext *ctx, const char *udi,  DBusError *error);
242 
243 /* Print a device to stdout; useful for debugging. */
244 dbus_bool_t   libhal_device_print    (LibHalContext *ctx, const char *udi,  DBusError *error);
245 
246 /* Determine if a property on a device exists. */
247 dbus_bool_t libhal_device_property_exists (LibHalContext *ctx,
248 					   const char *udi,
249 					   const char *key,
250 					   DBusError *error);
251 
252 /* Get the value of a property of type string. */
253 char *libhal_device_get_property_string (LibHalContext *ctx,
254 					 const char *udi,
255 					 const char *key,
256 					 DBusError *error);
257 
258 /* Get the value of a property of type signed integer. */
259 dbus_int32_t libhal_device_get_property_int (LibHalContext *ctx,
260 					     const char *udi,
261 					     const char *key,
262 					     DBusError *error);
263 
264 /* Get the value of a property of type unsigned integer. */
265 dbus_uint64_t libhal_device_get_property_uint64 (LibHalContext *ctx,
266 						 const char *udi,
267 						 const char *key,
268 						 DBusError *error);
269 
270 /* Get the value of a property of type double. */
271 double libhal_device_get_property_double (LibHalContext *ctx,
272 					  const char *udi,
273 					  const char *key,
274 					  DBusError *error);
275 
276 /* Get the value of a property of type bool. */
277 dbus_bool_t libhal_device_get_property_bool (LibHalContext *ctx,
278 					     const char *udi,
279 					     const char *key,
280 					     DBusError *error);
281 
282 /* Get the value of a property of type string list. */
283 char **libhal_device_get_property_strlist (LibHalContext *ctx,
284 					   const char *udi,
285 					   const char *key,
286 					   DBusError *error);
287 
288 /* Set a property of type string. */
289 dbus_bool_t libhal_device_set_property_string (LibHalContext *ctx,
290 					       const char *udi,
291 					       const char *key,
292 					       const char *value,
293 					       DBusError *error);
294 
295 /* Set a property of type signed integer. */
296 dbus_bool_t libhal_device_set_property_int (LibHalContext *ctx,
297 					    const char *udi,
298 					    const char *key,
299 					    dbus_int32_t value,
300 					    DBusError *error);
301 
302 /* Set a property of type unsigned integer. */
303 dbus_bool_t libhal_device_set_property_uint64 (LibHalContext *ctx,
304 					       const char *udi,
305 					       const char *key,
306 					       dbus_uint64_t value,
307 					       DBusError *error);
308 
309 /* Set a property of type double. */
310 dbus_bool_t libhal_device_set_property_double (LibHalContext *ctx,
311 					       const char *udi,
312 					       const char *key,
313 					       double value,
314 					       DBusError *error);
315 
316 /* Set a property of type bool. */
317 dbus_bool_t libhal_device_set_property_bool (LibHalContext *ctx,
318 					     const char *udi,
319 					     const char *key,
320 					     dbus_bool_t value,
321 					     DBusError *error);
322 
323 /* Append to a property of type strlist. */
324 dbus_bool_t libhal_device_property_strlist_append (LibHalContext *ctx,
325 						   const char *udi,
326 						   const char *key,
327 						   const char *value,
328 						   DBusError *error);
329 
330 /* Prepend to a property of type strlist. */
331 dbus_bool_t libhal_device_property_strlist_prepend (LibHalContext *ctx,
332 						    const char *udi,
333 						    const char *key,
334 						    const char *value,
335 						    DBusError *error);
336 
337 /* Remove a specified string from a property of type strlist. */
338 dbus_bool_t libhal_device_property_strlist_remove_index (LibHalContext *ctx,
339 							 const char *udi,
340 							 const char *key,
341 							 unsigned int idx,
342 							 DBusError *error);
343 
344 /* Remove a specified string from a property of type strlist. */
345 dbus_bool_t libhal_device_property_strlist_remove (LibHalContext *ctx,
346 						   const char *udi,
347 						   const char *key,
348 						   const char *value,
349 						   DBusError *error);
350 
351 /* Remove a property. */
352 dbus_bool_t libhal_device_remove_property (LibHalContext *ctx,
353 					   const char *udi,
354 					   const char *key,
355 					   DBusError *error);
356 
357 /* Query a property type of a device. */
358 LibHalPropertyType libhal_device_get_property_type (LibHalContext *ctx,
359 						    const char *udi,
360 						    const char *key,
361 						    DBusError *error);
362 
363 struct LibHalChangeSet_s;
364 typedef struct LibHalChangeSet_s LibHalChangeSet;
365 
366 LibHalChangeSet *libhal_device_new_changeset (const char *udi);
367 
368 dbus_bool_t libhal_changeset_set_property_string (LibHalChangeSet *changeset,
369 						  const char *key,
370 						  const char *value);
371 
372 dbus_bool_t libhal_changeset_set_property_int (LibHalChangeSet *changeset,
373 					       const char *key,
374 					       dbus_int32_t value);
375 
376 dbus_bool_t libhal_changeset_set_property_uint64 (LibHalChangeSet *changeset,
377 						  const char *key,
378 						  dbus_uint64_t value);
379 
380 dbus_bool_t libhal_changeset_set_property_double (LibHalChangeSet *changeset,
381 						  const char *key,
382 						  double value);
383 
384 dbus_bool_t libhal_changeset_set_property_bool (LibHalChangeSet *changeset,
385 						const char *key,
386 						dbus_bool_t value);
387 
388 dbus_bool_t libhal_changeset_set_property_strlist (LibHalChangeSet *changeset,
389 						   const char *key,
390 						   const char **value);
391 
392 dbus_bool_t libhal_device_commit_changeset (LibHalContext *ctx,
393 					    LibHalChangeSet *changeset,
394 					    DBusError *error);
395 
396 void libhal_device_free_changeset (LibHalChangeSet *changeset);
397 
398 
399 struct LibHalProperty_s;
400 typedef struct LibHalProperty_s LibHalProperty;
401 
402 struct LibHalPropertySet_s;
403 typedef struct LibHalPropertySet_s LibHalPropertySet;
404 
405 
406 /* Retrieve all the properties on a device. */
407 LibHalPropertySet *libhal_device_get_all_properties (LibHalContext *ctx,
408 						     const char *udi,
409 						     DBusError *error);
410 
411 /* Free a property set earlier obtained with libhal_device_get_all_properties(). */
412 void libhal_free_property_set (LibHalPropertySet *set);
413 
414 /* Get the number of properties in a property set. */
415 unsigned int libhal_property_set_get_num_elems (LibHalPropertySet *set);
416 
417 /* Get type of property. */
418 LibHalPropertyType libhal_ps_get_type (const LibHalPropertySet *set, const char *key);
419 
420 /* Get the value of a property of type string. */
421 const char *libhal_ps_get_string  (const LibHalPropertySet *set, const char *key);
422 
423 /* Get the value of a property of type signed integer. */
424 dbus_int32_t libhal_ps_get_int32 (const LibHalPropertySet *set, const char *key);
425 
426 /* Get the value of a property of type unsigned integer. */
427 dbus_uint64_t libhal_ps_get_uint64 (const LibHalPropertySet *set, const char *key);
428 
429 /* Get the value of a property of type double. */
430 double libhal_ps_get_double (const LibHalPropertySet *set, const char *key);
431 
432 /* Get the value of a property of type bool. */
433 dbus_bool_t libhal_ps_get_bool (const LibHalPropertySet *set, const char *key);
434 
435 /* Get the value of a property of type string list. */
436 const char * const *libhal_ps_get_strlist (const LibHalPropertySet *set, const char *key);
437 
438 
439 /**
440  * LibHalPropertySetIterator:
441  *
442  * Iterator for inspecting all properties. Do not access any members;
443  * use the libhal_psi_* family of functions instead.
444  */
445 struct LibHalPropertySetIterator_s {
446 	LibHalPropertySet *set;    /**< Property set we are iterating over */
447 	unsigned int idx;          /**< Index into current element */
448 	LibHalProperty *cur_prop;  /**< Current property being visited */
449 	void *reservered0;         /**< Reserved for future use */
450 	void *reservered1;         /**< Reserved for future use */
451 };
452 
453 
454 typedef struct LibHalPropertySetIterator_s LibHalPropertySetIterator;
455 
456 /* Initialize a property set iterator. */
457 void libhal_psi_init (LibHalPropertySetIterator *iter, LibHalPropertySet *set);
458 
459 /* Determine whether there are more properties to iterate over */
460 dbus_bool_t libhal_psi_has_more (LibHalPropertySetIterator *iter);
461 
462 /* Advance iterator to next property. */
463 void libhal_psi_next (LibHalPropertySetIterator *iter);
464 
465 /* Get type of property. */
466 LibHalPropertyType libhal_psi_get_type (LibHalPropertySetIterator *iter);
467 
468 /* Get the key of a property. */
469 char *libhal_psi_get_key (LibHalPropertySetIterator *iter);
470 
471 /* Get the value of a property of type string. */
472 char *libhal_psi_get_string (LibHalPropertySetIterator *iter);
473 
474 /* Get the value of a property of type signed integer. */
475 dbus_int32_t libhal_psi_get_int (LibHalPropertySetIterator *iter);
476 
477 /* Get the value of a property of type unsigned integer. */
478 dbus_uint64_t libhal_psi_get_uint64 (LibHalPropertySetIterator *iter);
479 
480 /* Get the value of a property of type double. */
481 double libhal_psi_get_double (LibHalPropertySetIterator *iter);
482 
483 /* Get the value of a property of type bool. */
484 dbus_bool_t libhal_psi_get_bool (LibHalPropertySetIterator *iter);
485 
486 /* Get the value of a property of type string list. */
487 char **libhal_psi_get_strlist (LibHalPropertySetIterator *iter);
488 
489 /* Get the length of an array of strings */
490 unsigned int libhal_string_array_length (char **str_array);
491 
492 /* Frees a NULL-terminated array of strings. If passed NULL, does nothing. */
493 void libhal_free_string_array (char **str_array);
494 
495 /* Frees a nul-terminated string */
496 void libhal_free_string (char *str);
497 
498 /* Create a new device object which will be hidden from applications
499  * until the CommitToGdl(), ie. libhal_device_commit_to_gdl(), method is called.
500  */
501 char *libhal_new_device (LibHalContext *ctx, DBusError *error);
502 
503 /* When a hidden device has been built using the NewDevice method, ie.
504  * libhal_new_device(), and the org.freedesktop.Hal.Device interface
505  * this function will commit it to the global device list.
506  */
507 dbus_bool_t libhal_device_commit_to_gdl (LibHalContext *ctx,
508 					 const char *temp_udi,
509 					 const char *udi,
510 					 DBusError *error);
511 
512 /* This method can be invoked when a device is removed. The HAL daemon
513  * will shut down the device. Note that the device may still be in the device
514  * list if the Persistent property is set to true.
515  */
516 dbus_bool_t libhal_remove_device (LibHalContext *ctx,
517 					const char *udi,
518 					DBusError *error);
519 
520 /* Merge properties from one device to another. */
521 dbus_bool_t libhal_merge_properties (LibHalContext *ctx,
522 					   const char *target_udi,
523 					   const char *source_udi,
524 					   DBusError *error);
525 
526 /* Check a set of properties for two devices matches. */
527 dbus_bool_t libhal_device_matches (LibHalContext *ctx,
528 					 const char *udi1,
529 					 const char *udi2,
530 					 const char *property_namespace,
531 					 DBusError *error);
532 
533 /* Find a device in the GDL where a single string property matches a
534  * given value.
535  */
536 char **libhal_manager_find_device_string_match (LibHalContext *ctx,
537 						const char *key,
538 						const char *value,
539 						int *num_devices,
540 						DBusError *error);
541 
542 /* Assign a capability to a device. */
543 dbus_bool_t libhal_device_add_capability (LibHalContext *ctx,
544 					  const char *udi,
545 					  const char *capability,
546 					  DBusError *error);
547 
548 /* Check if a device has a capability. The result is undefined if the
549  * device doesn't exist.
550  */
551 dbus_bool_t libhal_device_query_capability (LibHalContext *ctx,
552 					    const char *udi,
553 					    const char *capability,
554 					    DBusError *error);
555 
556 /* Find devices with a given capability. */
557 char **libhal_find_device_by_capability (LibHalContext *ctx,
558 					 const char *capability,
559 					 int *num_devices,
560 					 DBusError *error);
561 
562 /* Watch all devices, ie. the device_property_changed callback is
563  * invoked when the properties on any device changes.
564  */
565 dbus_bool_t libhal_device_property_watch_all (LibHalContext *ctx,
566 					      DBusError *error);
567 
568 /* Add a watch on a device, so the device_property_changed callback is
569  * invoked when the properties on the given device changes.
570  */
571 dbus_bool_t libhal_device_add_property_watch (LibHalContext *ctx,
572 					      const char *udi,
573 					      DBusError *error);
574 
575 /* Remove a watch on a device */
576 dbus_bool_t libhal_device_remove_property_watch (LibHalContext *ctx,
577 						 const char *udi,
578 						 DBusError *error);
579 
580 /* Take an advisory lock on the device. */
581 dbus_bool_t libhal_device_lock (LibHalContext *ctx,
582 				const char *udi,
583 				const char *reason_to_lock,
584 				char **reason_why_locked,
585 				DBusError *error);
586 
587 /* Release an advisory lock on the device. */
588 dbus_bool_t libhal_device_unlock (LibHalContext *ctx,
589 				  const char *udi,
590 				  DBusError *error);
591 
592 dbus_bool_t libhal_device_rescan (LibHalContext *ctx,
593 				  const char *udi,
594 				  DBusError *error);
595 
596 dbus_bool_t libhal_device_reprobe (LibHalContext *ctx,
597 				   const char *udi,
598 				   DBusError *error);
599 
600 /* Emit a condition from a device (for hald helpers only) */
601 dbus_bool_t libhal_device_emit_condition (LibHalContext *ctx,
602 					  const char *udi,
603 					  const char *condition_name,
604 					  const char *condition_details,
605 					  DBusError *error);
606 
607 /* Claim an interface for a device (for hald helpers only) */
608 dbus_bool_t libhal_device_claim_interface (LibHalContext *ctx,
609 					   const char *udi,
610 					   const char *interface_name,
611 					   const char *introspection_xml,
612 					   DBusError *error);
613 
614 /* hald waits for all addons to call this function before announcing the addon (for hald helpers only) */
615 dbus_bool_t libhal_device_addon_is_ready (LibHalContext *ctx, const char *udi, DBusError *error);
616 
617 
618 #if defined(__cplusplus)
619 }
620 #endif
621 
622 #endif /* LIBHAL_H */
623