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