libhal.h

00001 /***************************************************************************
00002  * CVSID: $Id: libhal.h,v 1.31 2005/11/02 15:38:14 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.1
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 
00049 #define LIBHAL_FREE_DBUS_ERROR(_dbus_error_)        \
00050     do {                        \
00051         if (dbus_error_is_set(_dbus_error_))    \
00052             dbus_error_free (_dbus_error_); \
00053     } while (0)
00054 
00055 
00063 typedef enum {
00065     LIBHAL_PROPERTY_TYPE_INVALID     =    DBUS_TYPE_INVALID,
00066 
00068     LIBHAL_PROPERTY_TYPE_INT32   =    DBUS_TYPE_INT32,
00069 
00071     LIBHAL_PROPERTY_TYPE_UINT64  =    DBUS_TYPE_UINT64,
00072 
00074     LIBHAL_PROPERTY_TYPE_DOUBLE  =    DBUS_TYPE_DOUBLE,
00075 
00077     LIBHAL_PROPERTY_TYPE_BOOLEAN =    DBUS_TYPE_BOOLEAN,
00078 
00080     LIBHAL_PROPERTY_TYPE_STRING  =    DBUS_TYPE_STRING,
00081 
00083     LIBHAL_PROPERTY_TYPE_STRLIST =     ((int) (DBUS_TYPE_STRING<<8)+('l'))
00084 } LibHalPropertyType;
00085 
00086 #ifndef DOXYGEN_SHOULD_SKIP_THIS
00087 typedef struct LibHalContext_s LibHalContext;
00088 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
00089 
00096 typedef void (*LibHalIntegrateDBusIntoMainLoop) (LibHalContext *ctx,
00097                          DBusConnection *dbus_connection);
00098 
00104 typedef void (*LibHalDeviceAdded) (LibHalContext *ctx, 
00105                    const char *udi);
00106 
00112 typedef void (*LibHalDeviceRemoved) (LibHalContext *ctx, 
00113                      const char *udi);
00114 
00121 typedef void (*LibHalDeviceNewCapability) (LibHalContext *ctx, 
00122                        const char *udi,
00123                        const char *capability);
00124 
00131 typedef void (*LibHalDeviceLostCapability) (LibHalContext *ctx, 
00132                         const char *udi,
00133                         const char *capability);
00134 
00143 typedef void (*LibHalDevicePropertyModified) (LibHalContext *ctx,
00144                           const char *udi,
00145                           const char *key,
00146                           dbus_bool_t is_removed,
00147                           dbus_bool_t is_added);
00148 
00158 typedef void (*LibHalDeviceCondition) (LibHalContext *ctx,
00159                        const char *udi,
00160                        const char *condition_name,
00161                        const char *condition_detail);
00162 
00163 
00164 /* Create a new context for a connection with hald */
00165 LibHalContext *libhal_ctx_new                          (void);
00166 
00167 /* Enable or disable caching */
00168 dbus_bool_t    libhal_ctx_set_cache                    (LibHalContext *ctx, dbus_bool_t use_cache);
00169 
00170 /* Set DBus connection to use to talk to hald. */
00171 dbus_bool_t    libhal_ctx_set_dbus_connection          (LibHalContext *ctx, DBusConnection *conn);
00172 
00173 /* Set user data for the context */
00174 dbus_bool_t    libhal_ctx_set_user_data                (LibHalContext *ctx, void *user_data);
00175 
00176 /* Get user data for the context */
00177 void*          libhal_ctx_get_user_data                (LibHalContext *ctx);
00178 
00179 /* Set the callback for when a device is added */
00180 dbus_bool_t    libhal_ctx_set_device_added             (LibHalContext *ctx, LibHalDeviceAdded callback);
00181 
00182 /* Set the callback for when a device is removed */
00183 dbus_bool_t    libhal_ctx_set_device_removed           (LibHalContext *ctx, LibHalDeviceRemoved callback);
00184 
00185 /* Set the callback for when a device gains a new capability */
00186 dbus_bool_t    libhal_ctx_set_device_new_capability    (LibHalContext *ctx, LibHalDeviceNewCapability callback);
00187 
00188 /* Set the callback for when a device loses a capability */
00189 dbus_bool_t    libhal_ctx_set_device_lost_capability   (LibHalContext *ctx, LibHalDeviceLostCapability callback);
00190 
00191 /* Set the callback for when a property is modified on a device */
00192 dbus_bool_t    libhal_ctx_set_device_property_modified (LibHalContext *ctx, LibHalDevicePropertyModified callback);
00193 
00194 /* Set the callback for when a device emits a condition */
00195 dbus_bool_t    libhal_ctx_set_device_condition         (LibHalContext *ctx, LibHalDeviceCondition callback);
00196 
00197 /* Initialize the connection to hald */
00198 dbus_bool_t    libhal_ctx_init                         (LibHalContext *ctx, DBusError *error);
00199 
00200 /* Shut down a connection to hald */
00201 dbus_bool_t    libhal_ctx_shutdown                     (LibHalContext *ctx, DBusError *error);
00202 
00203 /* Free a LibHalContext resource */
00204 dbus_bool_t    libhal_ctx_free                         (LibHalContext *ctx);
00205 
00206 /* Create an already initialized connection to hald */
00207 LibHalContext *libhal_ctx_init_direct                  (DBusError *error);
00208 
00209 /* Get all devices in the Global Device List (GDL). */
00210 char        **libhal_get_all_devices (LibHalContext *ctx, int *num_devices, DBusError *error);
00211 
00212 /* Determine if a device exists. */
00213 dbus_bool_t   libhal_device_exists   (LibHalContext *ctx, const char *udi,  DBusError *error);
00214 
00215 /* Print a device to stdout; useful for debugging. */
00216 dbus_bool_t   libhal_device_print    (LibHalContext *ctx, const char *udi,  DBusError *error);
00217 
00218 /* Determine if a property on a device exists. */
00219 dbus_bool_t libhal_device_property_exists (LibHalContext *ctx, 
00220                        const char *udi,
00221                        const char *key,
00222                        DBusError *error);
00223 
00224 /* Get the value of a property of type string. */
00225 char *libhal_device_get_property_string (LibHalContext *ctx, 
00226                      const char *udi,
00227                      const char *key,
00228                      DBusError *error);
00229 
00230 /* Get the value of a property of type signed integer. */
00231 dbus_int32_t libhal_device_get_property_int (LibHalContext *ctx, 
00232                          const char *udi,
00233                          const char *key,
00234                          DBusError *error);
00235 
00236 /* Get the value of a property of type unsigned integer. */
00237 dbus_uint64_t libhal_device_get_property_uint64 (LibHalContext *ctx, 
00238                          const char *udi,
00239                          const char *key,
00240                          DBusError *error);
00241 
00242 /* Get the value of a property of type double. */
00243 double libhal_device_get_property_double (LibHalContext *ctx, 
00244                       const char *udi,
00245                       const char *key,
00246                       DBusError *error);
00247 
00248 /* Get the value of a property of type bool. */
00249 dbus_bool_t libhal_device_get_property_bool (LibHalContext *ctx, 
00250                          const char *udi,
00251                          const char *key,
00252                          DBusError *error);
00253 
00254 /* Get the value of a property of type string list. */
00255 char **libhal_device_get_property_strlist (LibHalContext *ctx, 
00256                        const char *udi, 
00257                        const char *key,
00258                        DBusError *error);
00259 
00260 /* Set a property of type string. */
00261 dbus_bool_t libhal_device_set_property_string (LibHalContext *ctx, 
00262                            const char *udi,
00263                            const char *key,
00264                            const char *value,
00265                            DBusError *error);
00266 
00267 /* Set a property of type signed integer. */
00268 dbus_bool_t libhal_device_set_property_int (LibHalContext *ctx, 
00269                         const char *udi,
00270                         const char *key,
00271                         dbus_int32_t value,
00272                         DBusError *error);
00273 
00274 /* Set a property of type unsigned integer. */
00275 dbus_bool_t libhal_device_set_property_uint64 (LibHalContext *ctx, 
00276                            const char *udi,
00277                            const char *key,
00278                            dbus_uint64_t value,
00279                            DBusError *error);
00280 
00281 /* Set a property of type double. */
00282 dbus_bool_t libhal_device_set_property_double (LibHalContext *ctx, 
00283                            const char *udi,
00284                            const char *key,
00285                            double value,
00286                            DBusError *error);
00287 
00288 /* Set a property of type bool. */
00289 dbus_bool_t libhal_device_set_property_bool (LibHalContext *ctx, 
00290                          const char *udi,
00291                          const char *key,
00292                          dbus_bool_t value,
00293                          DBusError *error);
00294 
00295 /* Append to a property of type strlist. */
00296 dbus_bool_t libhal_device_property_strlist_append (LibHalContext *ctx, 
00297                            const char *udi,
00298                            const char *key,
00299                            const char *value,
00300                            DBusError *error);
00301 
00302 /* Prepend to a property of type strlist. */
00303 dbus_bool_t libhal_device_property_strlist_prepend (LibHalContext *ctx, 
00304                             const char *udi,
00305                             const char *key,
00306                             const char *value,
00307                             DBusError *error);
00308 
00309 /* Remove a specified string from a property of type strlist. */
00310 dbus_bool_t libhal_device_property_strlist_remove_index (LibHalContext *ctx, 
00311                              const char *udi,
00312                              const char *key,
00313                              unsigned int index,
00314                              DBusError *error);
00315 
00316 /* Remove a specified string from a property of type strlist. */
00317 dbus_bool_t libhal_device_property_strlist_remove (LibHalContext *ctx, 
00318                            const char *udi,
00319                            const char *key,
00320                            const char *value,
00321                            DBusError *error);
00322 
00323 /* Remove a property. */
00324 dbus_bool_t libhal_device_remove_property (LibHalContext *ctx, 
00325                        const char *udi,
00326                        const char *key,
00327                        DBusError *error);
00328 
00329 /* Query a property type of a device. */
00330 LibHalPropertyType libhal_device_get_property_type (LibHalContext *ctx, 
00331                             const char *udi,
00332                             const char *key,
00333                             DBusError *error);
00334 
00335 
00336 #ifndef DOXYGEN_SHOULD_SKIP_THIS
00337 struct LibHalProperty_s;
00338 typedef struct LibHalProperty_s LibHalProperty;
00339 
00340 struct LibHalPropertySet_s;
00341 typedef struct LibHalPropertySet_s LibHalPropertySet;
00342 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
00343 
00344 /* Retrieve all the properties on a device. */
00345 LibHalPropertySet *libhal_device_get_all_properties (LibHalContext *ctx, 
00346                              const char *udi,
00347                              DBusError *error);
00348 
00349 /* Free a property set earlier obtained with libhal_device_get_all_properties(). */
00350 void libhal_free_property_set (LibHalPropertySet *set);
00351 
00352 /* Get the number of properties in a property set. */
00353 unsigned int libhal_property_set_get_num_elems (LibHalPropertySet *set);
00354 
00356 struct LibHalPropertySetIterator_s {
00357     LibHalPropertySet *set;    
00358     unsigned int index;        
00359     LibHalProperty *cur_prop;  
00360     void *reservered0;         
00361     void *reservered1;         
00362 };
00363 
00364 #ifndef DOXYGEN_SHOULD_SKIP_THIS
00365 typedef struct LibHalPropertySetIterator_s LibHalPropertySetIterator;
00366 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
00367 
00368 /* Initialize a property set iterator. */
00369 void libhal_psi_init (LibHalPropertySetIterator *iter, LibHalPropertySet *set);
00370 
00371 /* Determine whether there are more properties to iterate over */
00372 dbus_bool_t libhal_psi_has_more (LibHalPropertySetIterator *iter);
00373 
00374 /* Advance iterator to next property. */
00375 void libhal_psi_next (LibHalPropertySetIterator *iter);
00376 
00377 /* Get type of property. */
00378 LibHalPropertyType libhal_psi_get_type (LibHalPropertySetIterator *iter);
00379 
00380 /* Get the key of a property. */
00381 char *libhal_psi_get_key (LibHalPropertySetIterator *iter);
00382 
00383 /* Get the value of a property of type string. */
00384 char *libhal_psi_get_string (LibHalPropertySetIterator *iter);
00385 
00386 /* Get the value of a property of type signed integer. */
00387 dbus_int32_t libhal_psi_get_int (LibHalPropertySetIterator *iter);
00388 
00389 /* Get the value of a property of type unsigned integer. */
00390 dbus_uint64_t libhal_psi_get_uint64 (LibHalPropertySetIterator *iter);
00391 
00392 /* Get the value of a property of type double. */
00393 double libhal_psi_get_double (LibHalPropertySetIterator *iter);
00394 
00395 /* Get the value of a property of type bool. */
00396 dbus_bool_t libhal_psi_get_bool (LibHalPropertySetIterator *iter);
00397 
00398 /* Get the value of a property of type string list. */
00399 char **libhal_psi_get_strlist (LibHalPropertySetIterator *iter);
00400 
00401 /* Get the length of an array of strings */
00402 unsigned int libhal_string_array_length (char **str_array);
00403 
00404 /* Frees a NULL-terminated array of strings. If passed NULL, does nothing. */
00405 void libhal_free_string_array (char **str_array);
00406 
00407 /* Frees a nul-terminated string */
00408 void libhal_free_string (char *str);
00409 
00410 /* Create a new device object which will be hidden from applications
00411  * until the CommitToGdl(), ie. libhal_device_commit_to_gdl(), method is called.
00412  */
00413 char *libhal_new_device (LibHalContext *ctx, DBusError *error);
00414 
00415 /* When a hidden device has been built using the NewDevice method, ie.
00416  * libhal_new_device(), and the org.freedesktop.Hal.Device interface
00417  * this function will commit it to the global device list. 
00418  */
00419 dbus_bool_t libhal_device_commit_to_gdl (LibHalContext *ctx,
00420                      const char *temp_udi,
00421                      const char *udi,
00422                      DBusError *error);
00423 
00424 /* This method can be invoked when a device is removed. The HAL daemon
00425  * will shut down the device. Note that the device may still be in the device
00426  * list if the Persistent property is set to true. 
00427  */
00428 dbus_bool_t libhal_remove_device (LibHalContext *ctx, 
00429                     const char *udi,
00430                     DBusError *error);
00431 
00432 /* Merge properties from one device to another. */
00433 dbus_bool_t libhal_merge_properties (LibHalContext *ctx,
00434                        const char *target_udi,
00435                        const char *source_udi,
00436                        DBusError *error);
00437 
00438 /* Check a set of properties for two devices matches. */
00439 dbus_bool_t libhal_device_matches (LibHalContext *ctx,
00440                      const char *udi1,
00441                      const char *udi2,
00442                      const char *property_namespace,
00443                      DBusError *error);
00444 
00445 /* Find a device in the GDL where a single string property matches a
00446  * given value.
00447  */
00448 char **libhal_manager_find_device_string_match (LibHalContext *ctx,
00449                         const char *key,
00450                         const char *value,
00451                         int *num_devices,
00452                         DBusError *error);
00453 
00454 /* Assign a capability to a device. */
00455 dbus_bool_t libhal_device_add_capability (LibHalContext *ctx,
00456                       const char *udi,
00457                       const char *capability,
00458                       DBusError *error);
00459 
00460 /* Check if a device has a capability. The result is undefined if the
00461  * device doesn't exist.
00462  */
00463 dbus_bool_t libhal_device_query_capability (LibHalContext *ctx,
00464                         const char *udi,
00465                         const char *capability,
00466                         DBusError *error);
00467 
00468 /* Find devices with a given capability. */
00469 char **libhal_find_device_by_capability (LibHalContext *ctx,
00470                      const char *capability,
00471                      int *num_devices,
00472                      DBusError *error);
00473 
00474 /* Watch all devices, ie. the device_property_changed callback is
00475  * invoked when the properties on any device changes.
00476  */
00477 dbus_bool_t libhal_device_property_watch_all (LibHalContext *ctx,
00478                           DBusError *error);
00479 
00480 /* Add a watch on a device, so the device_property_changed callback is
00481  * invoked when the properties on the given device changes.
00482  */
00483 dbus_bool_t libhal_device_add_property_watch (LibHalContext *ctx, 
00484                           const char *udi,
00485                           DBusError *error);
00486 
00487 /* Remove a watch on a device */
00488 dbus_bool_t libhal_device_remove_property_watch (LibHalContext *ctx, 
00489                          const char *udi,
00490                          DBusError *error);
00491 
00492 /* Take an advisory lock on the device. */
00493 dbus_bool_t libhal_device_lock (LibHalContext *ctx,
00494                 const char *udi,
00495                 const char *reason_to_lock,
00496                 char **reason_why_locked,
00497                 DBusError *error);
00498 
00499 /* Release an advisory lock on the device. */
00500 dbus_bool_t libhal_device_unlock (LibHalContext *ctx,
00501                   const char *udi,
00502                   DBusError *error);
00503 
00504 dbus_bool_t libhal_device_rescan (LibHalContext *ctx,
00505                   const char *udi,
00506                   DBusError *error);
00507 
00508 dbus_bool_t libhal_device_reprobe (LibHalContext *ctx,
00509                    const char *udi,
00510                    DBusError *error);
00511 
00512 /* Emit a condition from a device */
00513 dbus_bool_t libhal_device_emit_condition (LibHalContext *ctx,
00514                       const char *udi,
00515                       const char *condition_name,
00516                       const char *condition_details,
00517                       DBusError *error);
00518 
00521 #if defined(__cplusplus)
00522 }
00523 #endif
00524 
00525 #endif /* LIBHAL_H */

Generated on Fri Nov 23 17:14:31 2007 for HAL by  doxygen 1.4.6