xref: /illumos-gate/usr/src/lib/hal/libhal/common/libhal.h (revision 55fea89d)
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 code marking a D-Bus array type */
92 	LIBHAL_PROPERTY_TYPE_ARRAY   =    DBUS_TYPE_ARRAY,
93 
94 	/** Type for UTF-8 string property */
95 	LIBHAL_PROPERTY_TYPE_STRING  =    DBUS_TYPE_STRING,
96 
97 	/** Type for list of UTF-8 strings property */
98 	LIBHAL_PROPERTY_TYPE_STRLIST =    ((int) (DBUS_TYPE_STRING<<8)+('l'))
99 } LibHalPropertyType;
100 
101 
102 typedef struct LibHalContext_s LibHalContext;
103 
104 /**
105  * LibHalIntegrateDBusIntoMainLoop:
106  * @ctx: context for connection to hald
107  * @dbus_connection: DBus connection to use in ctx
108  *
109  * Type for function in application code that integrates a
110  * DBusConnection object into its own mainloop.
111  */
112 typedef void (*LibHalIntegrateDBusIntoMainLoop) (LibHalContext *ctx,
113 						 DBusConnection *dbus_connection);
114 
115 /**
116  * LibHalDeviceAdded:
117  * @ctx: context for connection to hald
118  * @udi: the Unique Device Id
119  *
120  * Type for callback when a device is added.
121  */
122 typedef void (*LibHalDeviceAdded) (LibHalContext *ctx,
123 				   const char *udi);
124 
125 /**
126  * LibHalDeviceRemoved:
127  * @ctx: context for connection to hald
128  * @udi: the Unique Device Id
129  *
130  * Type for callback when a device is removed.
131  */
132 typedef void (*LibHalDeviceRemoved) (LibHalContext *ctx,
133 				     const char *udi);
134 
135 /**
136  * LibHalDeviceNewCapability:
137  * @ctx: context for connection to hald
138  * @udi: the Unique Device Id
139  * @capability: capability of the device
140  *
141  * Type for callback when a device gains a new capability.
142  *
143  */
144 typedef void (*LibHalDeviceNewCapability) (LibHalContext *ctx,
145 					   const char *udi,
146 					   const char *capability);
147 
148 /**
149  * LibHalDeviceLostCapability:
150  * @ctx: context for connection to hald
151  * @udi: the Unique Device Id
152  * @capability: capability of the device
153  *
154  * Type for callback when a device loses a capability.
155  *
156  */
157 typedef void (*LibHalDeviceLostCapability) (LibHalContext *ctx,
158 					    const char *udi,
159 					    const char *capability);
160 
161 /**
162  * LibHalDevicePropertyModified:
163  * @ctx: context for connection to hald
164  * @udi: the Unique Device Id
165  * @key: name of the property that has changed
166  * @is_removed: whether or not property was removed
167  * @is_added: whether or not property was added
168  *
169  * Type for callback when a property of a device changes.
170  */
171 typedef void (*LibHalDevicePropertyModified) (LibHalContext *ctx,
172 					      const char *udi,
173 					      const char *key,
174 					      dbus_bool_t is_removed,
175 					      dbus_bool_t is_added);
176 
177 /**
178  * LibHalDeviceCondition:
179  * @ctx: context for connection to hald
180  * @udi: the Unique Device Id
181  * @condition_name: name of the condition, e.g. ProcessorOverheating. Consult the HAL spec for details
182  * @condition_detail: detail of condition
183  *
184  * Type for callback when a non-continuous condition occurs on a device.
185  */
186 typedef void (*LibHalDeviceCondition) (LibHalContext *ctx,
187 				       const char *udi,
188 				       const char *condition_name,
189 				       const char *condition_detail);
190 
191 
192 /* Create a new context for a connection with hald */
193 LibHalContext *libhal_ctx_new                          (void);
194 
195 /* Enable or disable caching */
196 dbus_bool_t    libhal_ctx_set_cache                    (LibHalContext *ctx, dbus_bool_t use_cache);
197 
198 /* Set DBus connection to use to talk to hald. */
199 dbus_bool_t    libhal_ctx_set_dbus_connection          (LibHalContext *ctx, DBusConnection *conn);
200 
201 /* Get DBus connection to use to talk to hald. */
202 DBusConnection *libhal_ctx_get_dbus_connection          (LibHalContext *ctx);
203 
204 /* Set user data for the context */
205 dbus_bool_t    libhal_ctx_set_user_data                (LibHalContext *ctx, void *user_data);
206 
207 /* Get user data for the context */
208 void*          libhal_ctx_get_user_data                (LibHalContext *ctx);
209 
210 /* Set the callback for when a device is added */
211 dbus_bool_t    libhal_ctx_set_device_added             (LibHalContext *ctx, LibHalDeviceAdded callback);
212 
213 /* Set the callback for when a device is removed */
214 dbus_bool_t    libhal_ctx_set_device_removed           (LibHalContext *ctx, LibHalDeviceRemoved callback);
215 
216 /* Set the callback for when a device gains a new capability */
217 dbus_bool_t    libhal_ctx_set_device_new_capability    (LibHalContext *ctx, LibHalDeviceNewCapability callback);
218 
219 /* Set the callback for when a device loses a capability */
220 dbus_bool_t    libhal_ctx_set_device_lost_capability   (LibHalContext *ctx, LibHalDeviceLostCapability callback);
221 
222 /* Set the callback for when a property is modified on a device */
223 dbus_bool_t    libhal_ctx_set_device_property_modified (LibHalContext *ctx, LibHalDevicePropertyModified callback);
224 
225 /* Set the callback for when a device emits a condition */
226 dbus_bool_t    libhal_ctx_set_device_condition         (LibHalContext *ctx, LibHalDeviceCondition callback);
227 
228 /* Initialize the connection to hald */
229 dbus_bool_t    libhal_ctx_init                         (LibHalContext *ctx, DBusError *error);
230 
231 /* Shut down a connection to hald */
232 dbus_bool_t    libhal_ctx_shutdown                     (LibHalContext *ctx, DBusError *error);
233 
234 /* Free a LibHalContext resource */
235 dbus_bool_t    libhal_ctx_free                         (LibHalContext *ctx);
236 
237 /* Create an already initialized connection to hald */
238 LibHalContext *libhal_ctx_init_direct                  (DBusError *error);
239 
240 /* Get all devices in the Global Device List (GDL). */
241 char        **libhal_get_all_devices (LibHalContext *ctx, int *num_devices, DBusError *error);
242 
243 /* Determine if a device exists. */
244 dbus_bool_t   libhal_device_exists   (LibHalContext *ctx, const char *udi,  DBusError *error);
245 
246 /* Print a device to stdout; useful for debugging. */
247 dbus_bool_t   libhal_device_print    (LibHalContext *ctx, const char *udi,  DBusError *error);
248 
249 /* Determine if a property on a device exists. */
250 dbus_bool_t libhal_device_property_exists (LibHalContext *ctx,
251 					   const char *udi,
252 					   const char *key,
253 					   DBusError *error);
254 
255 /* Get the value of a property of type string. */
256 char *libhal_device_get_property_string (LibHalContext *ctx,
257 					 const char *udi,
258 					 const char *key,
259 					 DBusError *error);
260 
261 /* Get the value of a property of type signed integer. */
262 dbus_int32_t libhal_device_get_property_int (LibHalContext *ctx,
263 					     const char *udi,
264 					     const char *key,
265 					     DBusError *error);
266 
267 /* Get the value of a property of type unsigned integer. */
268 dbus_uint64_t libhal_device_get_property_uint64 (LibHalContext *ctx,
269 						 const char *udi,
270 						 const char *key,
271 						 DBusError *error);
272 
273 /* Get the value of a property of type double. */
274 double libhal_device_get_property_double (LibHalContext *ctx,
275 					  const char *udi,
276 					  const char *key,
277 					  DBusError *error);
278 
279 /* Get the value of a property of type bool. */
280 dbus_bool_t libhal_device_get_property_bool (LibHalContext *ctx,
281 					     const char *udi,
282 					     const char *key,
283 					     DBusError *error);
284 
285 /* Get the value of a property of type string list. */
286 char **libhal_device_get_property_strlist (LibHalContext *ctx,
287 					   const char *udi,
288 					   const char *key,
289 					   DBusError *error);
290 
291 /* Set a property of type string. */
292 dbus_bool_t libhal_device_set_property_string (LibHalContext *ctx,
293 					       const char *udi,
294 					       const char *key,
295 					       const char *value,
296 					       DBusError *error);
297 
298 /* Set a property of type signed integer. */
299 dbus_bool_t libhal_device_set_property_int (LibHalContext *ctx,
300 					    const char *udi,
301 					    const char *key,
302 					    dbus_int32_t value,
303 					    DBusError *error);
304 
305 /* Set a property of type unsigned integer. */
306 dbus_bool_t libhal_device_set_property_uint64 (LibHalContext *ctx,
307 					       const char *udi,
308 					       const char *key,
309 					       dbus_uint64_t value,
310 					       DBusError *error);
311 
312 /* Set a property of type double. */
313 dbus_bool_t libhal_device_set_property_double (LibHalContext *ctx,
314 					       const char *udi,
315 					       const char *key,
316 					       double value,
317 					       DBusError *error);
318 
319 /* Set a property of type bool. */
320 dbus_bool_t libhal_device_set_property_bool (LibHalContext *ctx,
321 					     const char *udi,
322 					     const char *key,
323 					     dbus_bool_t value,
324 					     DBusError *error);
325 
326 /* Append to a property of type strlist. */
327 dbus_bool_t libhal_device_property_strlist_append (LibHalContext *ctx,
328 						   const char *udi,
329 						   const char *key,
330 						   const char *value,
331 						   DBusError *error);
332 
333 /* Prepend to a property of type strlist. */
334 dbus_bool_t libhal_device_property_strlist_prepend (LibHalContext *ctx,
335 						    const char *udi,
336 						    const char *key,
337 						    const char *value,
338 						    DBusError *error);
339 
340 /* Remove a specified string from a property of type strlist. */
341 dbus_bool_t libhal_device_property_strlist_remove_index (LibHalContext *ctx,
342 							 const char *udi,
343 							 const char *key,
344 							 unsigned int idx,
345 							 DBusError *error);
346 
347 /* Remove a specified string from a property of type strlist. */
348 dbus_bool_t libhal_device_property_strlist_remove (LibHalContext *ctx,
349 						   const char *udi,
350 						   const char *key,
351 						   const char *value,
352 						   DBusError *error);
353 
354 /* Remove a property. */
355 dbus_bool_t libhal_device_remove_property (LibHalContext *ctx,
356 					   const char *udi,
357 					   const char *key,
358 					   DBusError *error);
359 
360 /* Query a property type of a device. */
361 LibHalPropertyType libhal_device_get_property_type (LibHalContext *ctx,
362 						    const char *udi,
363 						    const char *key,
364 						    DBusError *error);
365 
366 struct LibHalChangeSet_s;
367 typedef struct LibHalChangeSet_s LibHalChangeSet;
368 
369 LibHalChangeSet *libhal_device_new_changeset (const char *udi);
370 
371 dbus_bool_t libhal_changeset_set_property_string (LibHalChangeSet *changeset,
372 						  const char *key,
373 						  const char *value);
374 
375 dbus_bool_t libhal_changeset_set_property_int (LibHalChangeSet *changeset,
376 					       const char *key,
377 					       dbus_int32_t value);
378 
379 dbus_bool_t libhal_changeset_set_property_uint64 (LibHalChangeSet *changeset,
380 						  const char *key,
381 						  dbus_uint64_t value);
382 
383 dbus_bool_t libhal_changeset_set_property_double (LibHalChangeSet *changeset,
384 						  const char *key,
385 						  double value);
386 
387 dbus_bool_t libhal_changeset_set_property_bool (LibHalChangeSet *changeset,
388 						const char *key,
389 						dbus_bool_t value);
390 
391 dbus_bool_t libhal_changeset_set_property_strlist (LibHalChangeSet *changeset,
392 						   const char *key,
393 						   const char **value);
394 
395 dbus_bool_t libhal_device_commit_changeset (LibHalContext *ctx,
396 					    LibHalChangeSet *changeset,
397 					    DBusError *error);
398 
399 void libhal_device_free_changeset (LibHalChangeSet *changeset);
400 
401 
402 struct LibHalProperty_s;
403 typedef struct LibHalProperty_s LibHalProperty;
404 
405 struct LibHalPropertySet_s;
406 typedef struct LibHalPropertySet_s LibHalPropertySet;
407 
408 
409 /* Retrieve all the properties on a device. */
410 LibHalPropertySet *libhal_device_get_all_properties (LibHalContext *ctx,
411 						     const char *udi,
412 						     DBusError *error);
413 
414 /* Free a property set earlier obtained with libhal_device_get_all_properties(). */
415 void libhal_free_property_set (LibHalPropertySet *set);
416 
417 /* Get the number of properties in a property set. */
418 unsigned int libhal_property_set_get_num_elems (LibHalPropertySet *set);
419 
420 /* Get type of property. */
421 LibHalPropertyType libhal_ps_get_type (const LibHalPropertySet *set, const char *key);
422 
423 /* Get the value of a property of type string. */
424 const char *libhal_ps_get_string  (const LibHalPropertySet *set, const char *key);
425 
426 /* Get the value of a property of type signed integer. */
427 dbus_int32_t libhal_ps_get_int32 (const LibHalPropertySet *set, const char *key);
428 
429 /* Get the value of a property of type unsigned integer. */
430 dbus_uint64_t libhal_ps_get_uint64 (const LibHalPropertySet *set, const char *key);
431 
432 /* Get the value of a property of type double. */
433 double libhal_ps_get_double (const LibHalPropertySet *set, const char *key);
434 
435 /* Get the value of a property of type bool. */
436 dbus_bool_t libhal_ps_get_bool (const LibHalPropertySet *set, const char *key);
437 
438 /* Get the value of a property of type string list. */
439 const char * const *libhal_ps_get_strlist (const LibHalPropertySet *set, const char *key);
440 
441 
442 /**
443  * LibHalPropertySetIterator:
444  *
445  * Iterator for inspecting all properties. Do not access any members;
446  * use the libhal_psi_* family of functions instead.
447  */
448 struct LibHalPropertySetIterator_s {
449 	LibHalPropertySet *set;    /**< Property set we are iterating over */
450 	unsigned int idx;          /**< Index into current element */
451 	LibHalProperty *cur_prop;  /**< Current property being visited */
452 	void *reservered0;         /**< Reserved for future use */
453 	void *reservered1;         /**< Reserved for future use */
454 };
455 
456 
457 typedef struct LibHalPropertySetIterator_s LibHalPropertySetIterator;
458 
459 /* Initialize a property set iterator. */
460 void libhal_psi_init (LibHalPropertySetIterator *iter, LibHalPropertySet *set);
461 
462 /* Determine whether there are more properties to iterate over */
463 dbus_bool_t libhal_psi_has_more (LibHalPropertySetIterator *iter);
464 
465 /* Advance iterator to next property. */
466 void libhal_psi_next (LibHalPropertySetIterator *iter);
467 
468 /* Get type of property. */
469 LibHalPropertyType libhal_psi_get_type (LibHalPropertySetIterator *iter);
470 
471 /* Get the key of a property. */
472 char *libhal_psi_get_key (LibHalPropertySetIterator *iter);
473 
474 /* Get the value of a property of type string. */
475 char *libhal_psi_get_string (LibHalPropertySetIterator *iter);
476 
477 /* Get the value of a property of type signed integer. */
478 dbus_int32_t libhal_psi_get_int (LibHalPropertySetIterator *iter);
479 
480 /* Get the value of a property of type unsigned integer. */
481 dbus_uint64_t libhal_psi_get_uint64 (LibHalPropertySetIterator *iter);
482 
483 /* Get the value of a property of type double. */
484 double libhal_psi_get_double (LibHalPropertySetIterator *iter);
485 
486 /* Get the value of a property of type bool. */
487 dbus_bool_t libhal_psi_get_bool (LibHalPropertySetIterator *iter);
488 
489 /* Get the value of a property of type string list. */
490 char **libhal_psi_get_strlist (LibHalPropertySetIterator *iter);
491 
492 /* Get the length of an array of strings */
493 unsigned int libhal_string_array_length (char **str_array);
494 
495 /* Frees a NULL-terminated array of strings. If passed NULL, does nothing. */
496 void libhal_free_string_array (char **str_array);
497 
498 /* Frees a nul-terminated string */
499 void libhal_free_string (char *str);
500 
501 /* Create a new device object which will be hidden from applications
502  * until the CommitToGdl(), ie. libhal_device_commit_to_gdl(), method is called.
503  */
504 char *libhal_new_device (LibHalContext *ctx, DBusError *error);
505 
506 /* When a hidden device has been built using the NewDevice method, ie.
507  * libhal_new_device(), and the org.freedesktop.Hal.Device interface
508  * this function will commit it to the global device list.
509  */
510 dbus_bool_t libhal_device_commit_to_gdl (LibHalContext *ctx,
511 					 const char *temp_udi,
512 					 const char *udi,
513 					 DBusError *error);
514 
515 /* This method can be invoked when a device is removed. The HAL daemon
516  * will shut down the device. Note that the device may still be in the device
517  * list if the Persistent property is set to true.
518  */
519 dbus_bool_t libhal_remove_device (LibHalContext *ctx,
520 					const char *udi,
521 					DBusError *error);
522 
523 /* Merge properties from one device to another. */
524 dbus_bool_t libhal_merge_properties (LibHalContext *ctx,
525 					   const char *target_udi,
526 					   const char *source_udi,
527 					   DBusError *error);
528 
529 /* Check a set of properties for two devices matches. */
530 dbus_bool_t libhal_device_matches (LibHalContext *ctx,
531 					 const char *udi1,
532 					 const char *udi2,
533 					 const char *property_namespace,
534 					 DBusError *error);
535 
536 /* Find a device in the GDL where a single string property matches a
537  * given value.
538  */
539 char **libhal_manager_find_device_string_match (LibHalContext *ctx,
540 						const char *key,
541 						const char *value,
542 						int *num_devices,
543 						DBusError *error);
544 
545 /* Assign a capability to a device. */
546 dbus_bool_t libhal_device_add_capability (LibHalContext *ctx,
547 					  const char *udi,
548 					  const char *capability,
549 					  DBusError *error);
550 
551 /* Check if a device has a capability. The result is undefined if the
552  * device doesn't exist.
553  */
554 dbus_bool_t libhal_device_query_capability (LibHalContext *ctx,
555 					    const char *udi,
556 					    const char *capability,
557 					    DBusError *error);
558 
559 /* Find devices with a given capability. */
560 char **libhal_find_device_by_capability (LibHalContext *ctx,
561 					 const char *capability,
562 					 int *num_devices,
563 					 DBusError *error);
564 
565 /* Watch all devices, ie. the device_property_changed callback is
566  * invoked when the properties on any device changes.
567  */
568 dbus_bool_t libhal_device_property_watch_all (LibHalContext *ctx,
569 					      DBusError *error);
570 
571 /* Add a watch on a device, so the device_property_changed callback is
572  * invoked when the properties on the given device changes.
573  */
574 dbus_bool_t libhal_device_add_property_watch (LibHalContext *ctx,
575 					      const char *udi,
576 					      DBusError *error);
577 
578 /* Remove a watch on a device */
579 dbus_bool_t libhal_device_remove_property_watch (LibHalContext *ctx,
580 						 const char *udi,
581 						 DBusError *error);
582 
583 /* Take an advisory lock on the device. */
584 dbus_bool_t libhal_device_lock (LibHalContext *ctx,
585 				const char *udi,
586 				const char *reason_to_lock,
587 				char **reason_why_locked,
588 				DBusError *error);
589 
590 /* Release an advisory lock on the device. */
591 dbus_bool_t libhal_device_unlock (LibHalContext *ctx,
592 				  const char *udi,
593 				  DBusError *error);
594 
595 dbus_bool_t libhal_device_rescan (LibHalContext *ctx,
596 				  const char *udi,
597 				  DBusError *error);
598 
599 dbus_bool_t libhal_device_reprobe (LibHalContext *ctx,
600 				   const char *udi,
601 				   DBusError *error);
602 
603 /* Emit a condition from a device (for hald helpers only) */
604 dbus_bool_t libhal_device_emit_condition (LibHalContext *ctx,
605 					  const char *udi,
606 					  const char *condition_name,
607 					  const char *condition_details,
608 					  DBusError *error);
609 
610 /* Claim an interface for a device (for hald helpers only) */
611 dbus_bool_t libhal_device_claim_interface (LibHalContext *ctx,
612 					   const char *udi,
613 					   const char *interface_name,
614 					   const char *introspection_xml,
615 					   DBusError *error);
616 
617 /* hald waits for all addons to call this function before announcing the addon (for hald helpers only) */
618 dbus_bool_t libhal_device_addon_is_ready (LibHalContext *ctx, const char *udi, DBusError *error);
619 
620 
621 #if defined(__cplusplus)
622 }
623 #endif
624 
625 #endif /* LIBHAL_H */
626