dbus/dbus-message.h

   1 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
   2 /* dbus-message.h DBusMessage object
   3  *
   4  * Copyright (C) 2002, 2003, 2005 Red Hat Inc.
   5  * Copyright (C) 2015  Samsung Electronics
   6  *
   7  * Licensed under the Academic Free License version 2.1
   8  *
   9  * This program is free software; you can redistribute it and/or modify
  10  * it under the terms of the GNU General Public License as published by
  11  * the Free Software Foundation; either version 2 of the License, or
  12  * (at your option) any later version.
  13  *
  14  * This program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17  * GNU General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU General Public License
  20  * along with this program; if not, write to the Free Software
  21  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
  22  *
  23  */
  24 #if !defined (DBUS_INSIDE_DBUS_H) && !defined (DBUS_COMPILATION)
  25 #error "Only <dbus/dbus.h> can be included directly, this file may disappear or change contents."
  26 #endif
  27
  28 #ifndef DBUS_MESSAGE_H
  29 #define DBUS_MESSAGE_H
  30
  31 #include <dbus/dbus-macros.h>
  32 #include <dbus/dbus-types.h>
  33 #include <dbus/dbus-arch-deps.h>
  34 #include <dbus/dbus-memory.h>
  35 #include <dbus/dbus-errors.h>
  36 #include <stdarg.h>
  37
  38 DBUS_BEGIN_DECLS
  39
  40 /**
  41  * @addtogroup DBusMessage
  42  * @{
  43  */
  44
  45 typedef struct DBusMessage DBusMessage;
  46 /** Opaque type representing a message iterator. Can be copied by value, and contains no allocated memory so never needs to be freed and can be allocated on the stack. */
  47 typedef struct DBusMessageIter DBusMessageIter;
  48
  49 /**
  50  * DBusMessageIter struct; contains no public fields.
  51  */
  52 struct DBusMessageIter
  53 {                                              /* layout on a standard 64-bit system */
  54   void *dummy1;         /**< Don't use this */ /* message */
  55   dbus_uint32_t dummy3a : 21; /**< Don't use this */
  56   dbus_uint32_t dummy3b : 3; /**< Don't use this */
  57   dbus_uint32_t dummy3c : 8; /**< Don't use this */
  58
  59                                              /* padding before union */
  60   union {
  61     struct
  62     {
  63       dbus_uint32_t dummy1a : 8;     /**< Don't use this */
  64       dbus_uint32_t dummy1b : 1;     /**< Don't use this */
  65       dbus_uint32_t dummy1c : 3;     /**< Don't use this */
  66       dbus_uint32_t dummy1d : 1;     /**< Don't use this */
  67       dbus_uint32_t dummy1e : 1;     /**< Don't use this */
  68       dbus_uint32_t dummy1f : 1;     /**< Don't use this */
  69       void *dummy2;             /**< Don't use this */
  70       int dummy3;               /**< Don't use this */
  71       void *dummy4;             /**< Don't use this */
  72       int dummy5;               /**< Don't use this */
  73       int dummy6;               /**< Don't use this */
  74       size_t dummy7;            /**< Don't use this */
  75       size_t dummy8;            /**< Don't use this */
  76       int dummy9;               /**< Don't use this */
  77
  78       void *dummy10;            /**< Don't use this */
  79       union
  80       {
  81         struct {
  82           int dummy11;          /**< Don't use this */
  83         };
  84       } u;
  85     } s1;
  86
  87     struct
  88     {
  89       dbus_uint32_t dummy1a : 8;     /**< Don't use this */
  90       dbus_uint32_t dummy1b : 8;     /**< Don't use this */
  91       dbus_uint32_t dummy1c : 1;     /**< Don't use this */
  92       dbus_uint32_t dummy1d : 1;     /**< Don't use this */
  93       dbus_uint32_t dummy1e : 1;     /**< Don't use this */
  94       dbus_uint32_t dummy1f : 1;     /**< Don't use this */
  95       dbus_uint32_t dummy1g : 1;     /**< Don't use this */
  96
  97       void *dummy2;             /**< Don't use this */
  98       int dummy3;               /**< Don't use this */
  99       void *dummy4;             /**< Don't use this */
 100       int dummy5;               /**< Don't use this */
 101       size_t dummy6;            /**< Don't use this */
 102       void *dummy7;             /**< Don't use this */
 103       int dummy8;               /**< Don't use this */
 104       char dummy9;              /**< Don't use this */
 105
 106       union
 107       {
 108         struct {
 109           int dummy10;           /**< Don't use this */
 110           int dummy11;           /**< Don't use this */
 111           int dummy12;           /**< Don't use this */
 112         };
 113         struct {
 114           size_t dummy13;        /**< Don't use this */
 115         };
 116       } u;
 117     } s2;
 118   } u;
 119 };
 120
 121 DBUS_EXPORT
 122 DBusMessage* dbus_message_new               (int          message_type);
 123 DBUS_EXPORT
 124 DBusMessage* dbus_message_new_method_call   (const char  *bus_name,
 125                                              const char  *path,
 126                                              const char  *iface,
 127                                              const char  *method);
 128 DBUS_EXPORT
 129 DBusMessage* dbus_message_new_method_return (DBusMessage *method_call);
 130 DBUS_EXPORT
 131 DBusMessage* dbus_message_new_signal        (const char  *path,
 132                                              const char  *iface,
 133                                              const char  *name);
 134 DBUS_EXPORT
 135 DBusMessage* dbus_message_new_error         (DBusMessage *reply_to,
 136                                              const char  *error_name,
 137                                              const char  *error_message);
 138 DBUS_EXPORT
 139 DBusMessage* dbus_message_new_error_printf  (DBusMessage *reply_to,
 140                                              const char  *error_name,
 141                                              const char  *error_format,
 142                                              ...);
 143
 144 DBUS_EXPORT
 145 DBusMessage* dbus_message_copy              (const DBusMessage *message);
 146
 147 DBUS_EXPORT
 148 DBusMessage*  dbus_message_ref              (DBusMessage   *message);
 149 DBUS_EXPORT
 150 void          dbus_message_unref            (DBusMessage   *message);
 151 DBUS_EXPORT
 152 int           dbus_message_get_type         (DBusMessage   *message);
 153 DBUS_EXPORT
 154 dbus_bool_t   dbus_message_set_path         (DBusMessage   *message,
 155                                              const char    *object_path);
 156 DBUS_EXPORT
 157 const char*   dbus_message_get_path         (DBusMessage   *message);
 158 DBUS_EXPORT
 159 dbus_bool_t   dbus_message_has_path         (DBusMessage   *message,
 160                                              const char    *object_path);
 161 DBUS_EXPORT
 162 dbus_bool_t   dbus_message_set_interface    (DBusMessage   *message,
 163                                              const char    *iface);
 164 DBUS_EXPORT
 165 const char*   dbus_message_get_interface    (DBusMessage   *message);
 166 DBUS_EXPORT
 167 dbus_bool_t   dbus_message_has_interface    (DBusMessage   *message,
 168                                              const char    *iface);
 169 DBUS_EXPORT
 170 dbus_bool_t   dbus_message_set_member       (DBusMessage   *message,
 171                                              const char    *member);
 172 DBUS_EXPORT
 173 const char*   dbus_message_get_member       (DBusMessage   *message);
 174 DBUS_EXPORT
 175 dbus_bool_t   dbus_message_has_member       (DBusMessage   *message,
 176                                              const char    *member);
 177 DBUS_EXPORT
 178 dbus_bool_t   dbus_message_set_error_name   (DBusMessage   *message,
 179                                              const char    *name);
 180 DBUS_EXPORT
 181 const char*   dbus_message_get_error_name   (DBusMessage   *message);
 182 DBUS_EXPORT
 183 dbus_bool_t   dbus_message_set_destination  (DBusMessage   *message,
 184                                              const char    *destination);
 185 DBUS_EXPORT
 186 const char*   dbus_message_get_destination  (DBusMessage   *message);
 187 DBUS_EXPORT
 188 dbus_bool_t   dbus_message_set_sender       (DBusMessage   *message,
 189                                              const char    *sender);
 190 DBUS_EXPORT
 191 const char*   dbus_message_get_sender       (DBusMessage   *message);
 192 DBUS_EXPORT
 193 const char*   dbus_message_get_signature    (DBusMessage   *message);
 194 DBUS_EXPORT
 195 void          dbus_message_set_no_reply     (DBusMessage   *message,
 196                                              dbus_bool_t    no_reply);
 197 DBUS_EXPORT
 198 dbus_bool_t   dbus_message_get_no_reply     (DBusMessage   *message);
 199 DBUS_EXPORT
 200 dbus_bool_t   dbus_message_is_method_call   (DBusMessage   *message,
 201                                              const char    *iface,
 202                                              const char    *method);
 203 DBUS_EXPORT
 204 dbus_bool_t   dbus_message_is_signal        (DBusMessage   *message,
 205                                              const char    *iface,
 206                                              const char    *signal_name);
 207 DBUS_EXPORT
 208 dbus_bool_t   dbus_message_is_error         (DBusMessage   *message,
 209                                              const char    *error_name);
 210 DBUS_EXPORT
 211 dbus_bool_t   dbus_message_has_destination  (DBusMessage   *message,
 212                                              const char    *bus_name);
 213 DBUS_EXPORT
 214 dbus_bool_t   dbus_message_has_sender       (DBusMessage   *message,
 215                                              const char    *unique_bus_name);
 216 DBUS_EXPORT
 217 dbus_bool_t   dbus_message_has_signature    (DBusMessage   *message,
 218                                              const char    *signature);
 219 DBUS_EXPORT
 220 dbus_uint32_t dbus_message_get_serial       (DBusMessage   *message);
 221 DBUS_EXPORT
 222 void          dbus_message_set_serial       (DBusMessage   *message,
 223                                              dbus_uint32_t  serial);
 224 DBUS_EXPORT
 225 dbus_bool_t   dbus_message_set_reply_serial (DBusMessage   *message,
 226                                              dbus_uint32_t  reply_serial);
 227 DBUS_EXPORT
 228 dbus_uint32_t dbus_message_get_reply_serial (DBusMessage   *message);
 229
 230 DBUS_EXPORT
 231 void          dbus_message_set_auto_start   (DBusMessage   *message,
 232                                              dbus_bool_t    auto_start);
 233 DBUS_EXPORT
 234 dbus_bool_t   dbus_message_get_auto_start   (DBusMessage   *message);
 235
 236 DBUS_EXPORT
 237 dbus_bool_t   dbus_message_get_path_decomposed (DBusMessage   *message,
 238                                                 char        ***path);
 239
 240 DBUS_EXPORT
 241 dbus_bool_t dbus_message_append_args          (DBusMessage     *message,
 242                                                int              first_arg_type,
 243                                                ...);
 244 DBUS_EXPORT
 245 dbus_bool_t dbus_message_append_args_valist   (DBusMessage     *message,
 246                                                int              first_arg_type,
 247                                                va_list          var_args);
 248 DBUS_EXPORT
 249 dbus_bool_t dbus_message_get_args             (DBusMessage     *message,
 250                                                DBusError       *error,
 251                                                int              first_arg_type,
 252                                                ...);
 253 DBUS_EXPORT
 254 dbus_bool_t dbus_message_get_args_valist      (DBusMessage     *message,
 255                                                DBusError       *error,
 256                                                int              first_arg_type,
 257                                                va_list          var_args);
 258
 259 DBUS_EXPORT
 260 dbus_bool_t dbus_message_contains_unix_fds    (DBusMessage *message);
 261
 262 DBUS_EXPORT
 263 dbus_bool_t dbus_message_iter_init             (DBusMessage     *message,
 264                                                 DBusMessageIter *iter);
 265 DBUS_EXPORT
 266 dbus_bool_t dbus_message_iter_has_next         (DBusMessageIter *iter);
 267 DBUS_EXPORT
 268 dbus_bool_t dbus_message_iter_next             (DBusMessageIter *iter);
 269 DBUS_EXPORT
 270 char*       dbus_message_iter_get_signature    (DBusMessageIter *iter);
 271 DBUS_EXPORT
 272 int         dbus_message_iter_get_arg_type     (DBusMessageIter *iter);
 273 DBUS_EXPORT
 274 int         dbus_message_iter_get_element_type (DBusMessageIter *iter);
 275 DBUS_EXPORT
 276 void        dbus_message_iter_recurse          (DBusMessageIter *iter,
 277                                                 DBusMessageIter *sub);
 278 DBUS_EXPORT
 279 void        dbus_message_iter_get_basic        (DBusMessageIter *iter,
 280                                                 void            *value);
 281 DBUS_EXPORT
 282 int         dbus_message_iter_get_element_count(DBusMessageIter *iter);
 283
 284 #ifndef DBUS_DISABLE_DEPRECATED
 285 /* This function returns the wire protocol size of the array in bytes,
 286  * you do not want to know that probably
 287  */
 288 DBUS_EXPORT
 289 DBUS_DEPRECATED int         dbus_message_iter_get_array_len    (DBusMessageIter *iter);
 290 #endif
 291 DBUS_EXPORT
 292 void        dbus_message_iter_get_fixed_array  (DBusMessageIter *iter,
 293                                                 void            *value,
 294                                                 int             *n_elements);
 295
 296
 297 DBUS_EXPORT
 298 void        dbus_message_iter_init_append        (DBusMessage     *message,
 299                                                   DBusMessageIter *iter);
 300 DBUS_EXPORT
 301 dbus_bool_t dbus_message_iter_append_basic       (DBusMessageIter *iter,
 302                                                   int              type,
 303                                                   const void      *value);
 304 DBUS_EXPORT
 305 dbus_bool_t dbus_message_iter_append_fixed_array (DBusMessageIter *iter,
 306                                                   int              element_type,
 307                                                   const void      *value,
 308                                                   int              n_elements);
 309 DBUS_EXPORT
 310 dbus_bool_t dbus_message_iter_open_container     (DBusMessageIter *iter,
 311                                                   int              type,
 312                                                   const char      *contained_signature,
 313                                                   DBusMessageIter *sub);
 314 DBUS_EXPORT
 315 dbus_bool_t dbus_message_iter_close_container    (DBusMessageIter *iter,
 316                                                   DBusMessageIter *sub);
 317 DBUS_EXPORT
 318 void        dbus_message_iter_abandon_container  (DBusMessageIter *iter,
 319                                                   DBusMessageIter *sub);
 320
 321 DBUS_EXPORT
 322 void dbus_message_lock    (DBusMessage  *message);
 323
 324 DBUS_EXPORT
 325 dbus_bool_t  dbus_set_error_from_message  (DBusError    *error,
 326                                            DBusMessage  *message);
 327
 328
 329 DBUS_EXPORT
 330 dbus_bool_t dbus_message_allocate_data_slot (dbus_int32_t     *slot_p);
 331 DBUS_EXPORT
 332 void        dbus_message_free_data_slot     (dbus_int32_t     *slot_p);
 333 DBUS_EXPORT
 334 dbus_bool_t dbus_message_set_data           (DBusMessage      *message,
 335                                              dbus_int32_t      slot,
 336                                              void             *data,
 337                                              DBusFreeFunction  free_data_func);
 338 DBUS_EXPORT
 339 void*       dbus_message_get_data           (DBusMessage      *message,
 340                                              dbus_int32_t      slot);
 341
 342 DBUS_EXPORT
 343 int         dbus_message_type_from_string (const char *type_str);
 344 DBUS_EXPORT
 345 const char* dbus_message_type_to_string   (int type);
 346
 347 DBUS_EXPORT
 348 dbus_bool_t  dbus_message_marshal   (DBusMessage  *msg,
 349                                      char        **marshalled_data_p,
 350                                      int          *len_p);
 351 DBUS_EXPORT
 352 DBusMessage* dbus_message_demarshal (const char *str,
 353                                      int         len,
 354                                      DBusError  *error);
 355
 356 DBUS_EXPORT
 357 int          dbus_message_demarshal_bytes_needed (const char *str,
 358                                                   int len);
 359
 360 DBUS_EXPORT
 361 void dbus_message_set_allow_interactive_authorization (DBusMessage *message,
 362     dbus_bool_t allow);
 363
 364 DBUS_EXPORT
 365 dbus_bool_t dbus_message_get_allow_interactive_authorization (
 366     DBusMessage *message);
 367
 368 DBUS_EXPORT
 369 void         dbus_set_protocol_version (unsigned char version);
 370
 371 /** @} */
 372
 373 DBUS_END_DECLS
 374
 375 #endif /* DBUS_MESSAGE_H */