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 /**
  47  * Opaque type representing a message iterator. Can be copied by value and
  48  * allocated on the stack.
  49  *
  50  * A DBusMessageIter usually contains no allocated memory. However, there
  51  * is one special case: after a successful call to
  52  * dbus_message_iter_open_container(), the caller is responsible for calling
  53  * either dbus_message_iter_close_container() or
  54  * dbus_message_iter_abandon_container() exactly once, with the same pair
  55  * of iterators.
  56  */
  57 typedef struct DBusMessageIter DBusMessageIter;
  58
  59 /**
  60  * DBusMessageIter struct; contains no public fields.
  61  */
  62 struct DBusMessageIter
  63 {
  64   void *dummy1;         /**< Don't use this */
  65   void *dummy2;         /**< Don't use this */
  66   dbus_uint32_t dummy3; /**< Don't use this */
  67   int dummy4;           /**< Don't use this */
  68   int dummy5;           /**< Don't use this */
  69   int dummy6;           /**< Don't use this */
  70   void *dummy7;           /**< Don't use this */
  71   void *dummy8;           /**< Don't use this */
  72   void *dummy9;           /**< Don't use this */
  73   void *dummy10;          /**< Don't use this */
  74   void *dummy11;          /**< Don't use this */
  75   void *pad1;             /**< Don't use this */
  76   void *pad2;           /**< Don't use this */
  77   void *pad3;           /**< Don't use this */
  78 };
  79
  80 /**
  81  * A message iterator for which dbus_message_iter_abandon_container_if_open()
  82  * is the only valid operation.
  83  */
  84 #define DBUS_MESSAGE_ITER_INIT_CLOSED \
  85 { \
  86   NULL, /* dummy1 */ \
  87   NULL, /* dummy2 */ \
  88   0, /* dummy3 */ \
  89   0, /* dummy4 */ \
  90   0, /* dummy5 */ \
  91   0, /* dummy6 */ \
  92   NULL, /* dummy7 */ \
  93   NULL, /* dummy8 */ \
  94   NULL, /* dummy9 */ \
  95   NULL, /* dummy10 */ \
  96   NULL, /* dummy11 */ \
  97   NULL, /* pad1 */ \
  98   NULL, /* pad2 */ \
  99   NULL /* pad3 */ \
 100 }
 101
 102 DBUS_EXPORT
 103 DBusMessage* dbus_message_new               (int          message_type);
 104 DBUS_EXPORT
 105 DBusMessage* dbus_message_new_method_call   (const char  *bus_name,
 106                                              const char  *path,
 107                                              const char  *iface,
 108                                              const char  *method);
 109 DBUS_EXPORT
 110 DBusMessage* dbus_message_new_method_return (DBusMessage *method_call);
 111 DBUS_EXPORT
 112 DBusMessage* dbus_message_new_signal        (const char  *path,
 113                                              const char  *iface,
 114                                              const char  *name);
 115 DBUS_EXPORT
 116 DBusMessage* dbus_message_new_error         (DBusMessage *reply_to,
 117                                              const char  *error_name,
 118                                              const char  *error_message);
 119 DBUS_EXPORT
 120 DBusMessage* dbus_message_new_error_printf  (DBusMessage *reply_to,
 121                                              const char  *error_name,
 122                                              const char  *error_format,
 123                                              ...) _DBUS_GNUC_PRINTF (3, 4);
 124
 125 DBUS_EXPORT
 126 DBusMessage* dbus_message_copy              (const DBusMessage *message);
 127
 128 DBUS_EXPORT
 129 DBusMessage*  dbus_message_ref              (DBusMessage   *message);
 130 DBUS_EXPORT
 131 void          dbus_message_unref            (DBusMessage   *message);
 132 DBUS_EXPORT
 133 int           dbus_message_get_type         (DBusMessage   *message);
 134 DBUS_EXPORT
 135 dbus_bool_t   dbus_message_set_path         (DBusMessage   *message,
 136                                              const char    *object_path);
 137 DBUS_EXPORT
 138 const char*   dbus_message_get_path         (DBusMessage   *message);
 139 DBUS_EXPORT
 140 dbus_bool_t   dbus_message_has_path         (DBusMessage   *message,
 141                                              const char    *object_path);
 142 DBUS_EXPORT
 143 dbus_bool_t   dbus_message_set_interface    (DBusMessage   *message,
 144                                              const char    *iface);
 145 DBUS_EXPORT
 146 const char*   dbus_message_get_interface    (DBusMessage   *message);
 147 DBUS_EXPORT
 148 dbus_bool_t   dbus_message_has_interface    (DBusMessage   *message,
 149                                              const char    *iface);
 150 DBUS_EXPORT
 151 dbus_bool_t   dbus_message_set_member       (DBusMessage   *message,
 152                                              const char    *member);
 153 DBUS_EXPORT
 154 const char*   dbus_message_get_member       (DBusMessage   *message);
 155 DBUS_EXPORT
 156 dbus_bool_t   dbus_message_has_member       (DBusMessage   *message,
 157                                              const char    *member);
 158 DBUS_EXPORT
 159 dbus_bool_t   dbus_message_set_error_name   (DBusMessage   *message,
 160                                              const char    *name);
 161 DBUS_EXPORT
 162 const char*   dbus_message_get_error_name   (DBusMessage   *message);
 163 DBUS_EXPORT
 164 dbus_bool_t   dbus_message_set_destination  (DBusMessage   *message,
 165                                              const char    *destination);
 166 DBUS_EXPORT
 167 const char*   dbus_message_get_destination  (DBusMessage   *message);
 168 DBUS_EXPORT
 169 dbus_bool_t   dbus_message_set_sender       (DBusMessage   *message,
 170                                              const char    *sender);
 171 DBUS_EXPORT
 172 const char*   dbus_message_get_sender       (DBusMessage   *message);
 173 DBUS_EXPORT
 174 const char*   dbus_message_get_signature    (DBusMessage   *message);
 175 DBUS_EXPORT
 176 void          dbus_message_set_no_reply     (DBusMessage   *message,
 177                                              dbus_bool_t    no_reply);
 178 DBUS_EXPORT
 179 dbus_bool_t   dbus_message_get_no_reply     (DBusMessage   *message);
 180 DBUS_EXPORT
 181 dbus_bool_t   dbus_message_is_method_call   (DBusMessage   *message,
 182                                              const char    *iface,
 183                                              const char    *method);
 184 DBUS_EXPORT
 185 dbus_bool_t   dbus_message_is_signal        (DBusMessage   *message,
 186                                              const char    *iface,
 187                                              const char    *signal_name);
 188 DBUS_EXPORT
 189 dbus_bool_t   dbus_message_is_error         (DBusMessage   *message,
 190                                              const char    *error_name);
 191 DBUS_EXPORT
 192 dbus_bool_t   dbus_message_has_destination  (DBusMessage   *message,
 193                                              const char    *bus_name);
 194 DBUS_EXPORT
 195 dbus_bool_t   dbus_message_has_sender       (DBusMessage   *message,
 196                                              const char    *unique_bus_name);
 197 DBUS_EXPORT
 198 dbus_bool_t   dbus_message_has_signature    (DBusMessage   *message,
 199                                              const char    *signature);
 200 DBUS_EXPORT
 201 dbus_uint32_t dbus_message_get_serial       (DBusMessage   *message);
 202 DBUS_EXPORT
 203 void          dbus_message_set_serial       (DBusMessage   *message,
 204                                              dbus_uint32_t  serial);
 205 DBUS_EXPORT
 206 dbus_bool_t   dbus_message_set_reply_serial (DBusMessage   *message,
 207                                              dbus_uint32_t  reply_serial);
 208 DBUS_EXPORT
 209 dbus_uint32_t dbus_message_get_reply_serial (DBusMessage   *message);
 210
 211 DBUS_EXPORT
 212 void          dbus_message_set_auto_start   (DBusMessage   *message,
 213                                              dbus_bool_t    auto_start);
 214 DBUS_EXPORT
 215 dbus_bool_t   dbus_message_get_auto_start   (DBusMessage   *message);
 216
 217 DBUS_EXPORT
 218 dbus_bool_t   dbus_message_get_path_decomposed (DBusMessage   *message,
 219                                                 char        ***path);
 220
 221 DBUS_EXPORT
 222 dbus_bool_t dbus_message_append_args          (DBusMessage     *message,
 223                                                int              first_arg_type,
 224                                                ...);
 225 DBUS_EXPORT
 226 dbus_bool_t dbus_message_append_args_valist   (DBusMessage     *message,
 227                                                int              first_arg_type,
 228                                                va_list          var_args);
 229 DBUS_EXPORT
 230 dbus_bool_t dbus_message_get_args             (DBusMessage     *message,
 231                                                DBusError       *error,
 232                                                int              first_arg_type,
 233                                                ...);
 234 DBUS_EXPORT
 235 dbus_bool_t dbus_message_get_args_valist      (DBusMessage     *message,
 236                                                DBusError       *error,
 237                                                int              first_arg_type,
 238                                                va_list          var_args);
 239
 240 DBUS_EXPORT
 241 dbus_bool_t dbus_message_contains_unix_fds    (DBusMessage *message);
 242
 243 DBUS_EXPORT
 244 void        dbus_message_iter_init_closed        (DBusMessageIter *iter);
 245 DBUS_EXPORT
 246 dbus_bool_t dbus_message_iter_init             (DBusMessage     *message,
 247                                                 DBusMessageIter *iter);
 248 DBUS_EXPORT
 249 dbus_bool_t dbus_message_iter_has_next         (DBusMessageIter *iter);
 250 DBUS_EXPORT
 251 dbus_bool_t dbus_message_iter_next             (DBusMessageIter *iter);
 252 DBUS_EXPORT
 253 char*       dbus_message_iter_get_signature    (DBusMessageIter *iter);
 254 DBUS_EXPORT
 255 int         dbus_message_iter_get_arg_type     (DBusMessageIter *iter);
 256 DBUS_EXPORT
 257 int         dbus_message_iter_get_element_type (DBusMessageIter *iter);
 258 DBUS_EXPORT
 259 void        dbus_message_iter_recurse          (DBusMessageIter *iter,
 260                                                 DBusMessageIter *sub);
 261 DBUS_EXPORT
 262 void        dbus_message_iter_get_basic        (DBusMessageIter *iter,
 263                                                 void            *value);
 264 DBUS_EXPORT
 265 int         dbus_message_iter_get_element_count(DBusMessageIter *iter);
 266
 267 #ifndef DBUS_DISABLE_DEPRECATED
 268 /* This function returns the wire protocol size of the array in bytes,
 269  * you do not want to know that probably
 270  */
 271 DBUS_EXPORT
 272 DBUS_DEPRECATED int         dbus_message_iter_get_array_len    (DBusMessageIter *iter);
 273 #endif
 274 DBUS_EXPORT
 275 void        dbus_message_iter_get_fixed_array  (DBusMessageIter *iter,
 276                                                 void            *value,
 277                                                 int             *n_elements);
 278
 279
 280 DBUS_EXPORT
 281 void        dbus_message_iter_init_append        (DBusMessage     *message,
 282                                                   DBusMessageIter *iter);
 283 DBUS_EXPORT
 284 dbus_bool_t dbus_message_iter_append_basic       (DBusMessageIter *iter,
 285                                                   int              type,
 286                                                   const void      *value);
 287 DBUS_EXPORT
 288 dbus_bool_t dbus_message_iter_append_fixed_array (DBusMessageIter *iter,
 289                                                   int              element_type,
 290                                                   const void      *value,
 291                                                   int              n_elements);
 292 DBUS_EXPORT
 293 dbus_bool_t dbus_message_iter_open_container     (DBusMessageIter *iter,
 294                                                   int              type,
 295                                                   const char      *contained_signature,
 296                                                   DBusMessageIter *sub);
 297 DBUS_EXPORT
 298 dbus_bool_t dbus_message_iter_close_container    (DBusMessageIter *iter,
 299                                                   DBusMessageIter *sub);
 300 DBUS_EXPORT
 301 void        dbus_message_iter_abandon_container  (DBusMessageIter *iter,
 302                                                   DBusMessageIter *sub);
 303
 304 DBUS_EXPORT
 305 void        dbus_message_iter_abandon_container_if_open (DBusMessageIter *iter,
 306                                                          DBusMessageIter *sub);
 307
 308 DBUS_EXPORT
 309 void dbus_message_lock    (DBusMessage  *message);
 310
 311 DBUS_EXPORT
 312 dbus_bool_t  dbus_set_error_from_message  (DBusError    *error,
 313                                            DBusMessage  *message);
 314
 315
 316 DBUS_EXPORT
 317 dbus_bool_t dbus_message_allocate_data_slot (dbus_int32_t     *slot_p);
 318 DBUS_EXPORT
 319 void        dbus_message_free_data_slot     (dbus_int32_t     *slot_p);
 320 DBUS_EXPORT
 321 dbus_bool_t dbus_message_set_data           (DBusMessage      *message,
 322                                              dbus_int32_t      slot,
 323                                              void             *data,
 324                                              DBusFreeFunction  free_data_func);
 325 DBUS_EXPORT
 326 void*       dbus_message_get_data           (DBusMessage      *message,
 327                                              dbus_int32_t      slot);
 328
 329 DBUS_EXPORT
 330 int         dbus_message_type_from_string (const char *type_str);
 331 DBUS_EXPORT
 332 const char* dbus_message_type_to_string   (int type);
 333
 334 DBUS_EXPORT
 335 dbus_bool_t  dbus_message_marshal   (DBusMessage  *msg,
 336                                      char        **marshalled_data_p,
 337                                      int          *len_p);
 338 DBUS_EXPORT
 339 DBusMessage* dbus_message_demarshal (const char *str,
 340                                      int         len,
 341                                      DBusError  *error);
 342
 343 DBUS_EXPORT
 344 int          dbus_message_demarshal_bytes_needed (const char *str,
 345                                                   int len);
 346
 347 DBUS_EXPORT
 348 void dbus_message_set_allow_interactive_authorization (DBusMessage *message,
 349     dbus_bool_t allow);
 350
 351 DBUS_EXPORT
 352 dbus_bool_t dbus_message_get_allow_interactive_authorization (
 353     DBusMessage *message);
 354
 355 DBUS_EXPORT
 356 void        dbus_set_protocol_version (unsigned char version);
 357 DBUS_EXPORT
 358 void        dbus_set_default_protocol_strategy (const char *strategy_name);
 359 /**
 360  * Clear a variable or struct member that contains a #DBusMessage.
 361  * If it does not contain #NULL, the message that was previously
 362  * there is unreferenced with dbus_message_unref().
 363  *
 364  * This is very similar to dbus_clear_connection(): see that function
 365  * for more details.
 366  *
 367  * @param pointer_to_message A pointer to a variable or struct member.
 368  * pointer_to_message must not be #NULL, but *pointer_to_message
 369  * may be #NULL.
 370  */
 371 static inline void
 372 dbus_clear_message (DBusMessage **pointer_to_message)
 373 {
 374   _dbus_clear_pointer_impl (DBusMessage, pointer_to_message,
 375                             dbus_message_unref);
 376 }
 377
 378 /** @} */
 379
 380 DBUS_END_DECLS
 381
 382 #endif /* DBUS_MESSAGE_H */