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

libhal.h

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

Generated on Mon May 23 10:13:20 2005 for HAL by  doxygen 1.4.2