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