external/bsd/bind/dist/contrib/dbus/dbus_service.h

   1 /*      $NetBSD$        */
   2
   3 /*  D-BUS Service Utilities
   4  *
   5  *  Provides utilities for construction of D-BUS "Services"
   6  *
   7  *  Copyright(C) Jason Vas Dias, Red Hat Inc., 2005
   8  *  Modified by Adam Tkac, Red Hat Inc., 2007
   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 at
  13  *           http://www.fsf.org/licensing/licenses/gpl.txt
  14  *  and included in this software distribution as the "LICENSE" file.
  15  *
  16  *  This program is distributed in the hope that it will be useful,
  17  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19  *  GNU General Public License for more details.
  20  *
  21  */
  22
  23 #ifndef D_BUS_SERVER_UTILITIES_H
  24 #define D_BUS_SERVER_UTILITIES_H
  25
  26 #include <stdint.h>
  27 #include <stdarg.h>
  28 #include <isc/types.h>
  29
  30 typedef struct dbcs_s* DBUS_SVC;
  31
  32 typedef enum
  33 { HANDLED, NOT_HANDLED, HANDLED_NOW
  34 } dbus_svc_HandlerResult;
  35
  36 typedef enum
  37 {  INVALID, CALL, RETURN, ERROR, SIGNAL
  38 } dbus_svc_MessageType;
  39
  40 typedef enum
  41 {
  42     DBUS_SESSION,
  43     DBUS_SYSTEM,
  44     DBUS_STARTER,
  45     DBUS_PRIVATE_SYSTEM,
  46     DBUS_PRIVATE_SESSION
  47 } dbus_svc_DBUS_TYPE;
  48
  49 typedef enum /* D-BUS Protocol Type Codes / Signature Chars */
  50 {
  51    TYPE_INVALID  =   (int)'\0',
  52    TYPE_BYTE     =   (int)'y',
  53    TYPE_BOOLEAN  =   (int)'b',
  54    TYPE_INT16    =   (int)'n',
  55    TYPE_UINT16   =   (int)'q',
  56    TYPE_INT32    =   (int)'i',
  57    TYPE_UINT32   =   (int)'u',
  58    TYPE_INT64    =   (int)'x',
  59    TYPE_UINT64   =   (int)'t',
  60    TYPE_DOUBLE   =   (int)'d',
  61    TYPE_STRING   =   (int)'s',
  62    TYPE_OBJECT_PATH =(int)'o',
  63    TYPE_SIGNATURE=   (int)'g',
  64    TYPE_ARRAY    =   (int)'a',
  65    TYPE_VARIANT  =   (int)'v',
  66    TYPE_STRUCT   =   (int)'r',
  67    TYPE_DICT_ENTRY = (int)'e',
  68    STRUCT_BEGIN  =   (int)'(',
  69    STRUCT_END    =   (int)')',
  70    DICT_ENTRY_BEGIN =(int)'{',
  71    DICT_ENTRY_END   =(int)'}'
  72 } dbus_svc_DataType;
  73
  74 typedef struct DBusMessage* dbus_svc_MessageHandle;
  75
  76 typedef int
  77 (*dbus_svc_ErrorHandler)
  78 ( const char *errorFmt, ...
  79 ); /* Error Handler function prototype - handle FATAL errors from D-BUS calls */
  80
  81 typedef enum
  82 {
  83     WATCH_ENABLE = 8,
  84     WATCH_ERROR  = 4,
  85     WATCH_WRITE  = 2,
  86     WATCH_READ   = 1
  87 } dbus_svc_WatchFlags;
  88
  89 typedef void (*dbus_svc_WatchHandler)( int, dbus_svc_WatchFlags, void *arg );
  90
  91 typedef dbus_svc_HandlerResult
  92 (*dbus_svc_MessageHandler)
  93 ( DBUS_SVC dbus,
  94   dbus_svc_MessageType type,
  95   uint8_t  reply_expected,   /* 1 / 0 */
  96   uint32_t serial,           /* serial number of message; needed to reply */
  97   const char *destination,         /* D-BUS connection name / destination */
  98   const char *path,                /* D-BUS Object Path */
  99   const char *member,              /* D-BUS Object Member */
 100   const char *interface,           /* D-BUS Object interface */
 101   const char *if_suffix,           /* remainder of interface prefixed by ifPrefix */
 102   const char *sender,              /* Senders' connection destination */
 103   const char *signature,           /* Signature String composed of Type Codes      */
 104   dbus_svc_MessageHandle msg,/* Message pointer: call dbus_svc_get_args(msg,...) to get data */
 105   const char *prefix,              /* If non-null, this is the root prefix for this sub-path message */
 106   const char *suffix,              /* If non-null, this is the suffix of this sub-path message */
 107   void *prefixObject,        /* If non-null, this is the object that was registered for the prefix */
 108   void *object               /* If non-null, this is the object that was registered for the complete path */
 109 ); /* Message Handler function prototype */
 110
 111 #define DBusMsgHandlerArgs \
 112   DBUS_SVC dbus, \
 113   dbus_svc_MessageType type, \
 114   uint8_t  reply_expected, \
 115   uint32_t serial,         \
 116   const char *destination,       \
 117   const char *path,              \
 118   const char *member,            \
 119   const char *interface,         \
 120   const char *if_suffix,         \
 121   const char *sender,            \
 122   const char *signature,         \
 123   dbus_svc_MessageHandle msg, \
 124   const char *prefix,            \
 125   const char *suffix,            \
 126   void *prefixObject,      \
 127   void *object
 128
 129 #define SHUTDOWN 255
 130
 131 extern isc_result_t dbus_svc_init
 132 ( dbus_svc_DBUS_TYPE bus,
 133   char *name,                         /* name to register with D-BUS */
 134   DBUS_SVC *dbus,                     /* dbus handle */
 135   dbus_svc_WatchHandler wh,           /* optional handler for watch events */
 136   dbus_svc_ErrorHandler eh,           /* optional error log message handler */
 137   dbus_svc_ErrorHandler dh,           /* optional debug / info log message handler */
 138   void *wh_arg                        /* optional watch handler arg */
 139 );
 140 /*
 141  * Obtains connection to DBUS_BUS_STARTER and registers "name".
 142  * "eh" will be called for all errors from this server session.
 143  */
 144
 145 /* EITHER :
 146  *        pass a NULL WatchHandler to dbus_svc_init and use dbus_svc_main_loop
 147  * OR:
 148  *        supply a valid WatchHandler, and call dbus_svc_handle_watch when
 149  *        select() returns the watch fd as ready for the watch action, and
 150  *        call dbus_svc_dispatch when all watches have been handled.
 151  */
 152
 153
 154 uint8_t
 155 dbus_svc_add_filter
 156 (  DBUS_SVC, dbus_svc_MessageHandler mh, void *obj, int n_matches, ... );
 157 /*
 158  * Registers SINGLE message handler to handle ALL messages, adding match rules
 159  */
 160
 161 void  dbus_svc_main_loop( DBUS_SVC, void (*idle_handler)(DBUS_SVC) );
 162
 163 void  dbus_svc_handle_watch( DBUS_SVC, int watch_fd, dbus_svc_WatchFlags action);
 164
 165 void  dbus_svc_dispatch( DBUS_SVC );
 166
 167 /*
 168  * Enter message processing loop.
 169  * If "idle_handler" is non-null, it will be called once per iteration of loop.
 170  */
 171
 172 const char *dbus_svc_unique_name( DBUS_SVC );
 173 /*
 174  * Returns connection "unique" (socket) name
 175  */
 176
 177 void  dbus_svc_quit( DBUS_SVC );
 178 /*
 179  * Exit message processing loop
 180  */
 181
 182 void  dbus_svc_shutdown( DBUS_SVC );
 183 /*
 184  * Close connections and clean up.
 185  * DBUS_SVC pointer is invalid after this.
 186  */
 187
 188 uint8_t
 189 dbus_svc_get_args( DBUS_SVC, dbus_svc_MessageHandle, dbus_svc_DataType, ... );
 190 /* get arguments from message  */
 191
 192 uint8_t
 193 dbus_svc_get_args_va( DBUS_SVC, dbus_svc_MessageHandle, dbus_svc_DataType, va_list );
 194 /* get arguments from message  */
 195
 196
 197 typedef void (*dbus_svc_ShutdownHandler) ( DBUS_SVC, void * );
 198 uint8_t
 199 dbus_svc_add_shutdown_filter
 200 (
 201     DBUS_SVC, dbus_svc_ShutdownHandler sh, void *obj
 202 );
 203 /* Registers a filter for D-BUS shutdown event.
 204  * Cannot be used in conjunction with dbus_svc_add_message_filter.
 205  */
 206
 207 uint8_t
 208 dbus_svc_remove_message_filter
 209 ( DBUS_SVC, dbus_svc_MessageHandler mh);
 210 /* Unregisters the message filter */
 211
 212 uint8_t
 213 dbus_svc_send
 214 ( DBUS_SVC,
 215   dbus_svc_MessageType type,
 216   int32_t reply_serial,
 217   uint32_t *new_serial,
 218   const char *destination,
 219   const char *path,
 220   const char *member,
 221   const char *interface,
 222   dbus_svc_DataType firstType,
 223   ... /* pointer, { (dbus_svc_DataType, pointer )...} */
 224 ); /* sends messages / replies to "destination" */
 225
 226 uint8_t
 227 dbus_svc_send_va
 228 ( DBUS_SVC cs,
 229   dbus_svc_MessageType type,
 230   int32_t reply_serial,
 231   uint32_t *new_serial,
 232   const char *destination,
 233   const char *path,
 234   const char *member,
 235   const char *interface,
 236   dbus_svc_DataType firstType,
 237   va_list va
 238 ); /* sends messages / replies to "destination" */
 239
 240 dbus_svc_MessageHandle
 241 dbus_svc_call
 242 ( DBUS_SVC cs,
 243   const char *destination,
 244   const char *path,
 245   const char *member,
 246   const char *interface,
 247   dbus_svc_DataType firstType,
 248   ...
 249 ); /* constructs message, sends it, returns reply */
 250
 251 dbus_svc_MessageHandle
 252 dbus_svc_new_message
 253 ( DBUS_SVC cs,
 254   dbus_svc_MessageType type,
 255   int32_t reply_serial,
 256   const char *destination,
 257   const char *path,
 258   const char *interface,
 259   const char *member
 260 );
 261
 262 uint8_t
 263 dbus_svc_send_message(DBUS_SVC , dbus_svc_MessageHandle , uint32_t *  );
 264
 265 uint8_t
 266 dbus_svc_message_append_args( DBUS_SVC , dbus_svc_MessageHandle, dbus_svc_DataType, ...);
 267
 268 typedef struct DBusMessageIter *dbus_svc_MessageIterator;
 269
 270 dbus_svc_MessageIterator
 271 dbus_svc_message_iterator_new( DBUS_SVC, dbus_svc_MessageHandle );
 272
 273 uint32_t
 274 dbus_svc_message_next_arg_type( DBUS_SVC, dbus_svc_MessageIterator );
 275
 276 void
 277 dbus_svc_message_next_arg( DBUS_SVC, dbus_svc_MessageIterator,  void * );
 278
 279 uint32_t
 280 dbus_svc_message_element_type( DBUS_SVC, dbus_svc_MessageIterator );
 281
 282 void
 283 dbus_svc_message_get_elements( DBUS_SVC, dbus_svc_MessageIterator, uint32_t *n, void *array );
 284
 285 uint8_t dbus_svc_message_type( dbus_svc_MessageHandle );
 286
 287 void dbus_svc_message_iterator_free(  DBUS_SVC, dbus_svc_MessageIterator  );
 288
 289 #endif