libhal.h revision 9823:d1a95ad35c68
1233628Sfabient/*************************************************************************** 2233628Sfabient * CVSID: $Id$ 3233628Sfabient * 4233628Sfabient * libhal.h : HAL daemon C convenience library headers 5233628Sfabient * 6233628Sfabient * Copyright (C) 2003 David Zeuthen, <david@fubar.dk> 7233628Sfabient * Copyright (C) 2007 Codethink Ltd. Author Rob Taylor <rob.taylor@codethink.co.uk> 8233628Sfabient * 9233628Sfabient * Licensed under the Academic Free License version 2.1 10233628Sfabient * 11233628Sfabient * This program is free software; you can redistribute it and/or modify 12233628Sfabient * it under the terms of the GNU General Public License as published by 13233628Sfabient * the Free Software Foundation; either version 2 of the License, or 14233628Sfabient * (at your option) any later version. 15233628Sfabient * 16233628Sfabient * This program is distributed in the hope that it will be useful, 17233628Sfabient * but WITHOUT ANY WARRANTY; without even the implied warranty of 18233628Sfabient * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 19233628Sfabient * GNU General Public License for more details. 20233628Sfabient * 21233628Sfabient * You should have received a copy of the GNU General Public License 22233628Sfabient * along with this program; if not, write to the Free Software 23233628Sfabient * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA 24233628Sfabient * 25233628Sfabient **************************************************************************/ 26233628Sfabient 27233628Sfabient#ifndef LIBHAL_H 28233628Sfabient#define LIBHAL_H 29233628Sfabient 30233628Sfabient#include <dbus/dbus.h> 31233628Sfabient 32233628Sfabient#if defined(__cplusplus) 33233628Sfabientextern "C" { 34233628Sfabient#if 0 35233628Sfabient} /* shut up emacs indenting */ 36233628Sfabient#endif 37233628Sfabient#endif 38233628Sfabient 39233628Sfabient#if defined(__GNUC__) 40233628Sfabient#define LIBHAL_DEPRECATED __attribute__ ((deprecated)) 41233628Sfabient#else 42233628Sfabient#define LIBHAL_DEPRECATED 43233628Sfabient#endif 44233628Sfabient 45233628Sfabient 46233628Sfabient#define LIBHAL_FREE_DBUS_ERROR(_dbus_error_) \ 47233628Sfabient do { \ 48233628Sfabient 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 */ 75typedef 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 99typedef 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 */ 109typedef 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 */ 119typedef 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 */ 129typedef 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 */ 141typedef 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 */ 154typedef 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 */ 168typedef 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 */ 183typedef 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 */ 190LibHalContext *libhal_ctx_new (void); 191 192/* Enable or disable caching */ 193dbus_bool_t libhal_ctx_set_cache (LibHalContext *ctx, dbus_bool_t use_cache); 194 195/* Set DBus connection to use to talk to hald. */ 196dbus_bool_t libhal_ctx_set_dbus_connection (LibHalContext *ctx, DBusConnection *conn); 197 198/* Get DBus connection to use to talk to hald. */ 199DBusConnection *libhal_ctx_get_dbus_connection (LibHalContext *ctx); 200 201/* Set user data for the context */ 202dbus_bool_t libhal_ctx_set_user_data (LibHalContext *ctx, void *user_data); 203 204/* Get user data for the context */ 205void* libhal_ctx_get_user_data (LibHalContext *ctx); 206 207/* Set the callback for when a device is added */ 208dbus_bool_t libhal_ctx_set_device_added (LibHalContext *ctx, LibHalDeviceAdded callback); 209 210/* Set the callback for when a device is removed */ 211dbus_bool_t libhal_ctx_set_device_removed (LibHalContext *ctx, LibHalDeviceRemoved callback); 212 213/* Set the callback for when a device gains a new capability */ 214dbus_bool_t libhal_ctx_set_device_new_capability (LibHalContext *ctx, LibHalDeviceNewCapability callback); 215 216/* Set the callback for when a device loses a capability */ 217dbus_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 */ 220dbus_bool_t libhal_ctx_set_device_property_modified (LibHalContext *ctx, LibHalDevicePropertyModified callback); 221 222/* Set the callback for when a device emits a condition */ 223dbus_bool_t libhal_ctx_set_device_condition (LibHalContext *ctx, LibHalDeviceCondition callback); 224 225/* Initialize the connection to hald */ 226dbus_bool_t libhal_ctx_init (LibHalContext *ctx, DBusError *error); 227 228/* Shut down a connection to hald */ 229dbus_bool_t libhal_ctx_shutdown (LibHalContext *ctx, DBusError *error); 230 231/* Free a LibHalContext resource */ 232dbus_bool_t libhal_ctx_free (LibHalContext *ctx); 233 234/* Create an already initialized connection to hald */ 235LibHalContext *libhal_ctx_init_direct (DBusError *error); 236 237/* Get all devices in the Global Device List (GDL). */ 238char **libhal_get_all_devices (LibHalContext *ctx, int *num_devices, DBusError *error); 239 240/* Determine if a device exists. */ 241dbus_bool_t libhal_device_exists (LibHalContext *ctx, const char *udi, DBusError *error); 242 243/* Print a device to stdout; useful for debugging. */ 244dbus_bool_t libhal_device_print (LibHalContext *ctx, const char *udi, DBusError *error); 245 246/* Determine if a property on a device exists. */ 247dbus_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. */ 253char *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. */ 259dbus_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. */ 265dbus_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. */ 271double 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. */ 277dbus_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. */ 283char **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. */ 289dbus_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. */ 296dbus_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. */ 303dbus_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. */ 310dbus_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. */ 317dbus_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. */ 324dbus_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. */ 331dbus_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. */ 338dbus_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. */ 345dbus_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. */ 352dbus_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. */ 358LibHalPropertyType libhal_device_get_property_type (LibHalContext *ctx, 359 const char *udi, 360 const char *key, 361 DBusError *error); 362 363struct LibHalChangeSet_s; 364typedef struct LibHalChangeSet_s LibHalChangeSet; 365 366LibHalChangeSet *libhal_device_new_changeset (const char *udi); 367 368dbus_bool_t libhal_changeset_set_property_string (LibHalChangeSet *changeset, 369 const char *key, 370 const char *value); 371 372dbus_bool_t libhal_changeset_set_property_int (LibHalChangeSet *changeset, 373 const char *key, 374 dbus_int32_t value); 375 376dbus_bool_t libhal_changeset_set_property_uint64 (LibHalChangeSet *changeset, 377 const char *key, 378 dbus_uint64_t value); 379 380dbus_bool_t libhal_changeset_set_property_double (LibHalChangeSet *changeset, 381 const char *key, 382 double value); 383 384dbus_bool_t libhal_changeset_set_property_bool (LibHalChangeSet *changeset, 385 const char *key, 386 dbus_bool_t value); 387 388dbus_bool_t libhal_changeset_set_property_strlist (LibHalChangeSet *changeset, 389 const char *key, 390 const char **value); 391 392dbus_bool_t libhal_device_commit_changeset (LibHalContext *ctx, 393 LibHalChangeSet *changeset, 394 DBusError *error); 395 396void libhal_device_free_changeset (LibHalChangeSet *changeset); 397 398 399struct LibHalProperty_s; 400typedef struct LibHalProperty_s LibHalProperty; 401 402struct LibHalPropertySet_s; 403typedef struct LibHalPropertySet_s LibHalPropertySet; 404 405 406/* Retrieve all the properties on a device. */ 407LibHalPropertySet *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(). */ 412void libhal_free_property_set (LibHalPropertySet *set); 413 414/* Get the number of properties in a property set. */ 415unsigned int libhal_property_set_get_num_elems (LibHalPropertySet *set); 416 417/* Get type of property. */ 418LibHalPropertyType libhal_ps_get_type (const LibHalPropertySet *set, const char *key); 419 420/* Get the value of a property of type string. */ 421const char *libhal_ps_get_string (const LibHalPropertySet *set, const char *key); 422 423/* Get the value of a property of type signed integer. */ 424dbus_int32_t libhal_ps_get_int32 (const LibHalPropertySet *set, const char *key); 425 426/* Get the value of a property of type unsigned integer. */ 427dbus_uint64_t libhal_ps_get_uint64 (const LibHalPropertySet *set, const char *key); 428 429/* Get the value of a property of type double. */ 430double libhal_ps_get_double (const LibHalPropertySet *set, const char *key); 431 432/* Get the value of a property of type bool. */ 433dbus_bool_t libhal_ps_get_bool (const LibHalPropertySet *set, const char *key); 434 435/* Get the value of a property of type string list. */ 436const 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 */ 445struct 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 454typedef struct LibHalPropertySetIterator_s LibHalPropertySetIterator; 455 456/* Initialize a property set iterator. */ 457void libhal_psi_init (LibHalPropertySetIterator *iter, LibHalPropertySet *set); 458 459/* Determine whether there are more properties to iterate over */ 460dbus_bool_t libhal_psi_has_more (LibHalPropertySetIterator *iter); 461 462/* Advance iterator to next property. */ 463void libhal_psi_next (LibHalPropertySetIterator *iter); 464 465/* Get type of property. */ 466LibHalPropertyType libhal_psi_get_type (LibHalPropertySetIterator *iter); 467 468/* Get the key of a property. */ 469char *libhal_psi_get_key (LibHalPropertySetIterator *iter); 470 471/* Get the value of a property of type string. */ 472char *libhal_psi_get_string (LibHalPropertySetIterator *iter); 473 474/* Get the value of a property of type signed integer. */ 475dbus_int32_t libhal_psi_get_int (LibHalPropertySetIterator *iter); 476 477/* Get the value of a property of type unsigned integer. */ 478dbus_uint64_t libhal_psi_get_uint64 (LibHalPropertySetIterator *iter); 479 480/* Get the value of a property of type double. */ 481double libhal_psi_get_double (LibHalPropertySetIterator *iter); 482 483/* Get the value of a property of type bool. */ 484dbus_bool_t libhal_psi_get_bool (LibHalPropertySetIterator *iter); 485 486/* Get the value of a property of type string list. */ 487char **libhal_psi_get_strlist (LibHalPropertySetIterator *iter); 488 489/* Get the length of an array of strings */ 490unsigned int libhal_string_array_length (char **str_array); 491 492/* Frees a NULL-terminated array of strings. If passed NULL, does nothing. */ 493void libhal_free_string_array (char **str_array); 494 495/* Frees a nul-terminated string */ 496void 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 */ 501char *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 */ 507dbus_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 */ 516dbus_bool_t libhal_remove_device (LibHalContext *ctx, 517 const char *udi, 518 DBusError *error); 519 520/* Merge properties from one device to another. */ 521dbus_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. */ 527dbus_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 */ 536char **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. */ 543dbus_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 */ 551dbus_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. */ 557char **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 */ 565dbus_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 */ 571dbus_bool_t libhal_device_add_property_watch (LibHalContext *ctx, 572 const char *udi, 573 DBusError *error); 574 575/* Remove a watch on a device */ 576dbus_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. */ 581dbus_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. */ 588dbus_bool_t libhal_device_unlock (LibHalContext *ctx, 589 const char *udi, 590 DBusError *error); 591 592dbus_bool_t libhal_device_rescan (LibHalContext *ctx, 593 const char *udi, 594 DBusError *error); 595 596dbus_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) */ 601dbus_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) */ 608dbus_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) */ 615dbus_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