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