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