libhal.h

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

Generated on Thu Sep 14 19:54:27 2006 for HAL by  doxygen 1.4.7