HAL: libhal.h Source File

Main Page | Modules | Data Structures | Directories | File List | Data Fields | Related Pages

# libhal.h

    00001 /***************************************************************************
    00002  * CVSID: $Id: libhal.h,v 1.30 2005/07/29 20:32:57 david Exp $
    00003  *
    00004  * libhal.h : HAL daemon C convenience library headers
    00005  *
    00006  * Copyright (C) 2003 David Zeuthen, <david@fubar.dk>
    00007  *
    00008  * Licensed under the Academic Free License version 2.0
    00009  *
    00010  * This program is free software; you can redistribute it and/or modify
    00011  * it under the terms of the GNU General Public License as published by
    00012  * the Free Software Foundation; either version 2 of the License, or
    00013  * (at your option) any later version.
    00014  *
    00015  * This program is distributed in the hope that it will be useful,
    00016  * but WITHOUT ANY WARRANTY; without even the implied warranty of
    00017  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    00018  * GNU General Public License for more details.
    00019  *
    00020  * You should have received a copy of the GNU General Public License
    00021  * along with this program; if not, write to the Free Software
    00022  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
    00023  *
    00024  **************************************************************************/
    00025
    00026 #ifndef LIBHAL_H
    00027 #define LIBHAL_H
    00028
    00029 #include <dbus/dbus.h>
    00030
    00031 #if defined(__cplusplus)
    00032 extern "C" {
    00033 #if 0
    00034 } /* shut up emacs indenting */
    00035 #endif
    00036 #endif
    00037
    00039 #define LIBHAL_CHECK_LIBHALCONTEXT(_ctx_, _ret_)                    \
    00040     do {                                    \
    00041         if (_ctx_ == NULL) {                        \
    00042             fprintf (stderr,                    \
    00043                  "%s %d : LibHalContext *ctx is NULL\n",    \
    00044                  __FILE__, __LINE__);               \
    00045             return _ret_;                       \
    00046         }                               \
    00047     } while(0)
    00048
    00056 typedef enum {
    00058     LIBHAL_PROPERTY_TYPE_INVALID     =    DBUS_TYPE_INVALID,
    00059
    00061     LIBHAL_PROPERTY_TYPE_INT32   =    DBUS_TYPE_INT32,
    00062
    00064     LIBHAL_PROPERTY_TYPE_UINT64  =    DBUS_TYPE_UINT64,
    00065
    00067     LIBHAL_PROPERTY_TYPE_DOUBLE  =    DBUS_TYPE_DOUBLE,
    00068
    00070     LIBHAL_PROPERTY_TYPE_BOOLEAN =    DBUS_TYPE_BOOLEAN,
    00071
    00073     LIBHAL_PROPERTY_TYPE_STRING  =    DBUS_TYPE_STRING,
    00074
    00076     LIBHAL_PROPERTY_TYPE_STRLIST =     ((int) (DBUS_TYPE_STRING<<8)+('l'))
    00077 } LibHalPropertyType;
    00078
    00079 #ifndef DOXYGEN_SHOULD_SKIP_THIS
    00080 typedef struct LibHalContext_s LibHalContext;
    00081 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
    00082
    00089 typedef void (*LibHalIntegrateDBusIntoMainLoop) (LibHalContext *ctx,
    00090                          DBusConnection *dbus_connection);
    00091
    00097 typedef void (*LibHalDeviceAdded) (LibHalContext *ctx,
    00098                    const char *udi);
    00099
    00105 typedef void (*LibHalDeviceRemoved) (LibHalContext *ctx,
    00106                      const char *udi);
    00107
    00114 typedef void (*LibHalDeviceNewCapability) (LibHalContext *ctx,
    00115                        const char *udi,
    00116                        const char *capability);
    00117
    00124 typedef void (*LibHalDeviceLostCapability) (LibHalContext *ctx,
    00125                         const char *udi,
    00126                         const char *capability);
    00127
    00136 typedef void (*LibHalDevicePropertyModified) (LibHalContext *ctx,
    00137                           const char *udi,
    00138                           const char *key,
    00139                           dbus_bool_t is_removed,
    00140                           dbus_bool_t is_added);
    00141
    00151 typedef void (*LibHalDeviceCondition) (LibHalContext *ctx,
    00152                        const char *udi,
    00153                        const char *condition_name,
    00154                        const char *condition_detail);
    00155
    00156
    00157 /* Create a new context for a connection with hald */
    00158 LibHalContext *libhal_ctx_new                          (void);
    00159
    00160 /* Enable or disable caching */
    00161 dbus_bool_t    libhal_ctx_set_cache                    (LibHalContext *ctx, dbus_bool_t use_cache);
    00162
    00163 /* Set DBus connection to use to talk to hald. */
    00164 dbus_bool_t    libhal_ctx_set_dbus_connection          (LibHalContext *ctx, DBusConnection *conn);
    00165
    00166 /* Set user data for the context */
    00167 dbus_bool_t    libhal_ctx_set_user_data                (LibHalContext *ctx, void *user_data);
    00168
    00169 /* Get user data for the context */
    00170 void*          libhal_ctx_get_user_data                (LibHalContext *ctx);
    00171
    00172 /* Set the callback for when a device is added */
    00173 dbus_bool_t    libhal_ctx_set_device_added             (LibHalContext *ctx, LibHalDeviceAdded callback);
    00174
    00175 /* Set the callback for when a device is removed */
    00176 dbus_bool_t    libhal_ctx_set_device_removed           (LibHalContext *ctx, LibHalDeviceRemoved callback);
    00177
    00178 /* Set the callback for when a device gains a new capability */
    00179 dbus_bool_t    libhal_ctx_set_device_new_capability    (LibHalContext *ctx, LibHalDeviceNewCapability callback);
    00180
    00181 /* Set the callback for when a device loses a capability */
    00182 dbus_bool_t    libhal_ctx_set_device_lost_capability   (LibHalContext *ctx, LibHalDeviceLostCapability callback);
    00183
    00184 /* Set the callback for when a property is modified on a device */
    00185 dbus_bool_t    libhal_ctx_set_device_property_modified (LibHalContext *ctx, LibHalDevicePropertyModified callback);
    00186
    00187 /* Set the callback for when a device emits a condition */
    00188 dbus_bool_t    libhal_ctx_set_device_condition         (LibHalContext *ctx, LibHalDeviceCondition callback);
    00189
    00190 /* Initialize the connection to hald */
    00191 dbus_bool_t    libhal_ctx_init                         (LibHalContext *ctx, DBusError *error);
    00192
    00193 /* Shut down a connection to hald */
    00194 dbus_bool_t    libhal_ctx_shutdown                     (LibHalContext *ctx, DBusError *error);
    00195
    00196 /* Free a LibHalContext resource */
    00197 dbus_bool_t    libhal_ctx_free                         (LibHalContext *ctx);
    00198
    00199 /* Create an already initialized connection to hald */
    00200 LibHalContext *libhal_ctx_init_direct                  (DBusError *error);
    00201
    00202 /* Get all devices in the Global Device List (GDL). */
    00203 char        **libhal_get_all_devices (LibHalContext *ctx, int *num_devices, DBusError *error);
    00204
    00205 /* Determine if a device exists. */
    00206 dbus_bool_t   libhal_device_exists   (LibHalContext *ctx, const char *udi,  DBusError *error);
    00207
    00208 /* Print a device to stdout; useful for debugging. */
    00209 dbus_bool_t   libhal_device_print    (LibHalContext *ctx, const char *udi,  DBusError *error);
    00210
    00211 /* Determine if a property on a device exists. */
    00212 dbus_bool_t libhal_device_property_exists (LibHalContext *ctx,
    00213                        const char *udi,
    00214                        const char *key,
    00215                        DBusError *error);
    00216
    00217 /* Get the value of a property of type string. */
    00218 char *libhal_device_get_property_string (LibHalContext *ctx,
    00219                      const char *udi,
    00220                      const char *key,
    00221                      DBusError *error);
    00222
    00223 /* Get the value of a property of type signed integer. */
    00224 dbus_int32_t libhal_device_get_property_int (LibHalContext *ctx,
    00225                          const char *udi,
    00226                          const char *key,
    00227                          DBusError *error);
    00228
    00229 /* Get the value of a property of type unsigned integer. */
    00230 dbus_uint64_t libhal_device_get_property_uint64 (LibHalContext *ctx,
    00231                          const char *udi,
    00232                          const char *key,
    00233                          DBusError *error);
    00234
    00235 /* Get the value of a property of type double. */
    00236 double libhal_device_get_property_double (LibHalContext *ctx,
    00237                       const char *udi,
    00238                       const char *key,
    00239                       DBusError *error);
    00240
    00241 /* Get the value of a property of type bool. */
    00242 dbus_bool_t libhal_device_get_property_bool (LibHalContext *ctx,
    00243                          const char *udi,
    00244                          const char *key,
    00245                          DBusError *error);
    00246
    00247 /* Get the value of a property of type string list. */
    00248 char **libhal_device_get_property_strlist (LibHalContext *ctx,
    00249                        const char *udi,
    00250                        const char *key,
    00251                        DBusError *error);
    00252
    00253 /* Set a property of type string. */
    00254 dbus_bool_t libhal_device_set_property_string (LibHalContext *ctx,
    00255                            const char *udi,
    00256                            const char *key,
    00257                            const char *value,
    00258                            DBusError *error);
    00259
    00260 /* Set a property of type signed integer. */
    00261 dbus_bool_t libhal_device_set_property_int (LibHalContext *ctx,
    00262                         const char *udi,
    00263                         const char *key,
    00264                         dbus_int32_t value,
    00265                         DBusError *error);
    00266
    00267 /* Set a property of type unsigned integer. */
    00268 dbus_bool_t libhal_device_set_property_uint64 (LibHalContext *ctx,
    00269                            const char *udi,
    00270                            const char *key,
    00271                            dbus_uint64_t value,
    00272                            DBusError *error);
    00273
    00274 /* Set a property of type double. */
    00275 dbus_bool_t libhal_device_set_property_double (LibHalContext *ctx,
    00276                            const char *udi,
    00277                            const char *key,
    00278                            double value,
    00279                            DBusError *error);
    00280
    00281 /* Set a property of type bool. */
    00282 dbus_bool_t libhal_device_set_property_bool (LibHalContext *ctx,
    00283                          const char *udi,
    00284                          const char *key,
    00285                          dbus_bool_t value,
    00286                          DBusError *error);
    00287
    00288 /* Append to a property of type strlist. */
    00289 dbus_bool_t libhal_device_property_strlist_append (LibHalContext *ctx,
    00290                            const char *udi,
    00291                            const char *key,
    00292                            const char *value,
    00293                            DBusError *error);
    00294
    00295 /* Prepend to a property of type strlist. */
    00296 dbus_bool_t libhal_device_property_strlist_prepend (LibHalContext *ctx,
    00297                             const char *udi,
    00298                             const char *key,
    00299                             const char *value,
    00300                             DBusError *error);
    00301
    00302 /* Remove a specified string from a property of type strlist. */
    00303 dbus_bool_t libhal_device_property_strlist_remove_index (LibHalContext *ctx,
    00304                              const char *udi,
    00305                              const char *key,
    00306                              unsigned int index,
    00307                              DBusError *error);
    00308
    00309 /* Remove a specified string from a property of type strlist. */
    00310 dbus_bool_t libhal_device_property_strlist_remove (LibHalContext *ctx,
    00311                            const char *udi,
    00312                            const char *key,
    00313                            const char *value,
    00314                            DBusError *error);
    00315
    00316 /* Remove a property. */
    00317 dbus_bool_t libhal_device_remove_property (LibHalContext *ctx,
    00318                        const char *udi,
    00319                        const char *key,
    00320                        DBusError *error);
    00321
    00322 /* Query a property type of a device. */
    00323 LibHalPropertyType libhal_device_get_property_type (LibHalContext *ctx,
    00324                             const char *udi,
    00325                             const char *key,
    00326                             DBusError *error);
    00327
    00328
    00329 #ifndef DOXYGEN_SHOULD_SKIP_THIS
    00330 struct LibHalProperty_s;
    00331 typedef struct LibHalProperty_s LibHalProperty;
    00332
    00333 struct LibHalPropertySet_s;
    00334 typedef struct LibHalPropertySet_s LibHalPropertySet;
    00335 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
    00336
    00337 /* Retrieve all the properties on a device. */
    00338 LibHalPropertySet *libhal_device_get_all_properties (LibHalContext *ctx,
    00339                              const char *udi,
    00340                              DBusError *error);
    00341
    00342 /* Free a property set earlier obtained with libhal_device_get_all_properties(). */
    00343 void libhal_free_property_set (LibHalPropertySet *set);
    00344
    00345 /* Get the number of properties in a property set. */
    00346 unsigned int libhal_property_set_get_num_elems (LibHalPropertySet *set);
    00347
    00349 struct LibHalPropertySetIterator_s {
    00350     LibHalPropertySet *set;
    00351     unsigned int index;
    00352     LibHalProperty *cur_prop;
    00353     void *reservered0;
    00354     void *reservered1;
    00355 };
    00356
    00357 #ifndef DOXYGEN_SHOULD_SKIP_THIS
    00358 typedef struct LibHalPropertySetIterator_s LibHalPropertySetIterator;
    00359 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
    00360
    00361 /* Initialize a property set iterator. */
    00362 void libhal_psi_init (LibHalPropertySetIterator *iter, LibHalPropertySet *set);
    00363
    00364 /* Determine whether there are more properties to iterate over */
    00365 dbus_bool_t libhal_psi_has_more (LibHalPropertySetIterator *iter);
    00366
    00367 /* Advance iterator to next property. */
    00368 void libhal_psi_next (LibHalPropertySetIterator *iter);
    00369
    00370 /* Get type of property. */
    00371 LibHalPropertyType libhal_psi_get_type (LibHalPropertySetIterator *iter);
    00372
    00373 /* Get the key of a property. */
    00374 char *libhal_psi_get_key (LibHalPropertySetIterator *iter);
    00375
    00376 /* Get the value of a property of type string. */
    00377 char *libhal_psi_get_string (LibHalPropertySetIterator *iter);
    00378
    00379 /* Get the value of a property of type signed integer. */
    00380 dbus_int32_t libhal_psi_get_int (LibHalPropertySetIterator *iter);
    00381
    00382 /* Get the value of a property of type unsigned integer. */
    00383 dbus_uint64_t libhal_psi_get_uint64 (LibHalPropertySetIterator *iter);
    00384
    00385 /* Get the value of a property of type double. */
    00386 double libhal_psi_get_double (LibHalPropertySetIterator *iter);
    00387
    00388 /* Get the value of a property of type bool. */
    00389 dbus_bool_t libhal_psi_get_bool (LibHalPropertySetIterator *iter);
    00390
    00391 /* Get the value of a property of type string list. */
    00392 char **libhal_psi_get_strlist (LibHalPropertySetIterator *iter);
    00393
    00394 /* Get the length of an array of strings */
    00395 unsigned int libhal_string_array_length (char **str_array);
    00396
    00397 /* Frees a NULL-terminated array of strings. If passed NULL, does nothing. */
    00398 void libhal_free_string_array (char **str_array);
    00399
    00400 /* Frees a nul-terminated string */
    00401 void libhal_free_string (char *str);
    00402
    00403 /* Create a new device object which will be hidden from applications
    00404  * until the CommitToGdl(), ie. libhal_device_commit_to_gdl(), method is called.
    00405  */
    00406 char *libhal_new_device (LibHalContext *ctx, DBusError *error);
    00407
    00408 /* When a hidden device has been built using the NewDevice method, ie.
    00409  * libhal_new_device(), and the org.freedesktop.Hal.Device interface
    00410  * this function will commit it to the global device list.
    00411  */
    00412 dbus_bool_t libhal_device_commit_to_gdl (LibHalContext *ctx,
    00413                      const char *temp_udi,
    00414                      const char *udi,
    00415                      DBusError *error);
    00416
    00417 /* This method can be invoked when a device is removed. The HAL daemon
    00418  * will shut down the device. Note that the device may still be in the device
    00419  * list if the Persistent property is set to true.
    00420  */
    00421 dbus_bool_t libhal_remove_device (LibHalContext *ctx,
    00422                     const char *udi,
    00423                     DBusError *error);
    00424
    00425 /* Merge properties from one device to another. */
    00426 dbus_bool_t libhal_merge_properties (LibHalContext *ctx,
    00427                        const char *target_udi,
    00428                        const char *source_udi,
    00429                        DBusError *error);
    00430
    00431 /* Check a set of properties for two devices matches. */
    00432 dbus_bool_t libhal_device_matches (LibHalContext *ctx,
    00433                      const char *udi1,
    00434                      const char *udi2,
    00435                      const char *property_namespace,
    00436                      DBusError *error);
    00437
    00438 /* Find a device in the GDL where a single string property matches a
    00439  * given value.
    00440  */
    00441 char **libhal_manager_find_device_string_match (LibHalContext *ctx,
    00442                         const char *key,
    00443                         const char *value,
    00444                         int *num_devices,
    00445                         DBusError *error);
    00446
    00447 /* Assign a capability to a device. */
    00448 dbus_bool_t libhal_device_add_capability (LibHalContext *ctx,
    00449                       const char *udi,
    00450                       const char *capability,
    00451                       DBusError *error);
    00452
    00453 /* Check if a device has a capability. The result is undefined if the
    00454  * device doesn't exist.
    00455  */
    00456 dbus_bool_t libhal_device_query_capability (LibHalContext *ctx,
    00457                         const char *udi,
    00458                         const char *capability,
    00459                         DBusError *error);
    00460
    00461 /* Find devices with a given capability. */
    00462 char **libhal_find_device_by_capability (LibHalContext *ctx,
    00463                      const char *capability,
    00464                      int *num_devices,
    00465                      DBusError *error);
    00466
    00467 /* Watch all devices, ie. the device_property_changed callback is
    00468  * invoked when the properties on any device changes.
    00469  */
    00470 dbus_bool_t libhal_device_property_watch_all (LibHalContext *ctx,
    00471                           DBusError *error);
    00472
    00473 /* Add a watch on a device, so the device_property_changed callback is
    00474  * invoked when the properties on the given device changes.
    00475  */
    00476 dbus_bool_t libhal_device_add_property_watch (LibHalContext *ctx,
    00477                           const char *udi,
    00478                           DBusError *error);
    00479
    00480 /* Remove a watch on a device */
    00481 dbus_bool_t libhal_device_remove_property_watch (LibHalContext *ctx,
    00482                          const char *udi,
    00483                          DBusError *error);
    00484
    00485 /* Take an advisory lock on the device. */
    00486 dbus_bool_t libhal_device_lock (LibHalContext *ctx,
    00487                 const char *udi,
    00488                 const char *reason_to_lock,
    00489                 char **reason_why_locked,
    00490                 DBusError *error);
    00491
    00492 /* Release an advisory lock on the device. */
    00493 dbus_bool_t libhal_device_unlock (LibHalContext *ctx,
    00494                   const char *udi,
    00495                   DBusError *error);
    00496
    00497 dbus_bool_t libhal_device_rescan (LibHalContext *ctx,
    00498                   const char *udi,
    00499                   DBusError *error);
    00500
    00501 dbus_bool_t libhal_device_reprobe (LibHalContext *ctx,
    00502                    const char *udi,
    00503                    DBusError *error);
    00504
    00505 /* Emit a condition from a device */
    00506 dbus_bool_t libhal_device_emit_condition (LibHalContext *ctx,
    00507                       const char *udi,
    00508                       const char *condition_name,
    00509                       const char *condition_details,
    00510                       DBusError *error);
    00511
    00514 #if defined(__cplusplus)
    00515 }
    00516 #endif
    00517
    00518 #endif /* LIBHAL_H */