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