« back to all changes in this revision
Viewing changes to src/ibusmessage.h
- browse files at revision 10
- compare with another revision
- download diff
- download tarball
- view history from revision 10
- Committer: Bazaar Package Importer
- Author(s): LI Daobing
- Date: 2009-07-23 20:22:09 UTC
- mfrom: (1.1.4 upstream) (6.1.7 sid)
- Revision ID: james.westby@ubuntu.com-20090723202209-bmgqa80g1umg8l2p
Tags: 1.2.0.20090723-1
new upstream release.
- files added:
- data/keymaps
- files removed:
- debian/libibus0.install
- files modified:
- AUTHORS
added
removed
src/ibusmessage.h
17
17
* Free Software Foundation, Inc., 59 Temple Place - Suite 330,
18
18
* Boston, MA 02111-1307, USA.
19
19
*/
20
/**
21
* SECTION: ibusmessage
22
* @short_description: A DBusMessage in IBus.
23
* @stability: Stable
24
*
25
* An IBusMessage is essentially a DBusMessage, which representing a message received from or to
26
* be sent to another application.
27
*
28
* Besides DBusMessage functions, An IBusMessage can be manipulated
29
* with its own specific functions, which are defined in this section.
30
*/
20
31
#ifndef __IBUS_MESSAGE_H_
21
32
#define __IBUS_MESSAGE_H_
22
33
25
36
#include <dbus/dbus.h>
26
37
#include "ibuserror.h"
27
38
39
/**
40
* IBUS_TYPE_OBJECT_PATH:
41
*
42
* Type of object path.
43
*/
28
44
#define IBUS_TYPE_OBJECT_PATH (ibus_type_get_object_path ())
45
46
/**
47
* IBUS_TYPE_ARRAY:
48
*
49
* Type of IBusArray.
50
*/
29
51
#define IBUS_TYPE_ARRAY (ibus_type_get_array ())
52
53
/**
54
* IBUS_TYPE_STRUCT:
55
*
56
* Type of IBusStruct.
57
*/
30
58
#define IBUS_TYPE_STRUCT (ibus_type_get_struct ())
59
60
/**
61
* IBUS_TYPE_DICT_ENTRY:
62
*
63
* Type of IBusDictEntry.
64
*/
31
65
#define IBUS_TYPE_DICT_ENTRY (ibus_type_get_dict_entry ())
66
67
/**
68
* IBUS_TYPE_VARIANT:
69
*
70
* Type of IBusVariant.
71
*/
32
72
#define IBUS_TYPE_VARIANT (ibus_type_get_variant ())
33
73
34
74
G_BEGIN_DECLS
35
75
76
/**
77
* IBusMessage:
78
*
79
* An opaque data structure that represents IBusMessage.
80
*/
36
81
typedef DBusMessage IBusMessage;
82
83
/**
84
* IBusMessageIter:
85
*
86
* An opaque data structure that represents IBusMessageIter.
87
*/
37
88
typedef DBusMessageIter IBusMessageIter;
38
89
90
/**
91
* ibus_type_get_object_path:
92
* @returns: Type of object path.
93
*
94
* Gets the type of object path.
95
*/
39
96
GType ibus_type_get_object_path (void);
97
98
/**
99
* ibus_type_get_array:
100
* @returns: Type of IBusArray.
101
*
102
* Gets the type of IBusArray.
103
*/
40
104
GType ibus_type_get_array (void);
105
106
/**
107
* ibus_type_get_struct:
108
* @returns: Type of IBusStruct.
109
*
110
* Gets the type of IBusStruct.
111
*/
41
112
GType ibus_type_get_struct (void);
113
114
/**
115
* ibus_type_get_dict_entry:
116
* @returns: Type of IBusDictEntry.
117
*
118
* Gets the type of IBusDictEntry.
119
*/
42
120
GType ibus_type_get_dict_entry (void);
121
122
/**
123
* ibus_type_get_variant:
124
* @returns: Type of IBusVariant.
125
*
126
* Gets the type of IBusVariant.
127
*/
43
128
GType ibus_type_get_variant (void);
44
129
130
/**
131
* ibus_message_new:
132
* @message_type: Type of the message.
133
* @returns: A newly allocated IBusMessage according to @message_type.
134
*
135
* New an IBusMessage.
136
* Valid D-Bus message types include:
137
* <itemizedlist>
138
* <listitem>
139
* <para>#DBUS_MESSAGE_TYPE_METHOD_CALL</para>
140
* </listitem>
141
* <listitem>
142
* <para>#DBUS_MESSAGE_TYPE_METHOD_RETURN</para>
143
* </listitem>
144
* <listitem>
145
* <para>#DBUS_MESSAGE_TYPE_METHOD_ERROR</para>
146
* </listitem>
147
* <listitem>
148
* <para>#DBUS_MESSAGE_TYPE_METHOD_SIGNAL</para>
149
* </listitem>
150
* </itemizedlist>
151
* These are defined in dbus-protocol.h in D-Bus.
152
*/
45
153
IBusMessage *ibus_message_new (gint message_type);
154
155
/**
156
* ibus_message_ref:
157
* @message: An IBusMessage.
158
* @returns: The IBusMessage.
159
*
160
* Increments the reference count of an IBusMessage.
161
*/
46
162
IBusMessage *ibus_message_ref (IBusMessage *message);
163
164
/**
165
* ibus_message_unref:
166
* @message: An IBusMessage.
167
*
168
* Decrements the reference count of a DBusMessage, freeing the message if the count reaches 0.
169
*/
47
170
void ibus_message_unref (IBusMessage *message);
171
172
/**
173
* ibus_message_new_method_call:
174
* @destination: Where this message to be sent to or %NULL for no destination.
175
* @path: Object path the message should be sent to.
176
* @interface: Interface to invoke method on, or %NULL.
177
* @method: The method to be invoked.
178
* @returns: A newly allocate IBusMessage; or %NULL if memory cannot be allocated.
179
*
180
* Constructs a new message to invoke a method on a remote object.
181
*
182
* The destination may be %NULL in which case no destination is set;
183
* this is appropriate when using IBus/D-Bus in a peer-to-peer context (no message bus).
184
* The interface may be %NULL, which means that if multiple methods with the given name
185
* exist it is undefined which one will be invoked.
186
*
187
* The path and method names may not be %NULL.
188
*
189
* Destination, path, interface, and method name can't contain any invalid characters
190
* (see the D-Bus specification).
191
*/
48
192
IBusMessage *ibus_message_new_method_call (const gchar *destination,
49
193
const gchar *path,
50
194
const gchar *interface,
51
195
const gchar *method);
196
197
/**
198
* ibus_message_new_method_return:
199
* @reply_to: The IBusMessage being replied to.
200
* @returns: A newly allocate IBusMessage; or %NULL if memory cannot be allocated.
201
*
202
* Constructs a message that is a reply to a method call.
203
*/
52
204
IBusMessage *ibus_message_new_method_return (IBusMessage *reply_to);
205
206
/**
207
* ibus_message_new_error:
208
* @reply_to: The IBusMessage being replied to.
209
* @error_name: Name of the error.
210
* @error_message: Detailed error message string (or %NULL for none, but please give a message).
211
* @returns: A newly allocate IBusMessage with the error information; or %NULL if memory cannot be allocated.
212
*
213
* Creates a new message that is an error reply to another message.
214
* Error replies are most common in response to method calls, but can be returned in reply to any message.
215
* The error name must be a valid error name according to the syntax given in the D-Bus specification.
216
* If you don't want to make up an error name just use %DBUS_ERROR_FAILED.
217
*
218
* Use ibus_message_unref() to free the produced IBusMessage.
219
*/
53
220
IBusMessage *ibus_message_new_error (IBusMessage *reply_to,
54
221
const gchar *error_name,
55
222
const gchar *error_message);
223
224
/**
225
* ibus_message_new_error_printf:
226
* @reply_to: The IBusMessage being replied to.
227
* @error_name: Name of the error.
228
* @error_format: Error format string as in printf() format.
229
* @...: Format arguments, as in printf().
230
* @returns: A newly allocate IBusMessage with the error information; or %NULL if memory cannot be allocated.
231
*
232
* Creates a new message that is an error reply to another message.
233
* Error replies are most common in response to method calls, but can be returned in reply to any message.
234
* The error name must be a valid error name according to the syntax given in the D-Bus specification.
235
* If you don't want to make up an error name just use %DBUS_ERROR_FAILED.
236
*/
56
237
IBusMessage *ibus_message_new_error_printf (IBusMessage *reply_to,
57
238
const gchar *error_name,
58
239
const gchar *error_format,
59
240
...);
241
242
/**
243
* ibus_message_new_signal:
244
* @path: Object path the message should be sent to.
245
* @interface: Interface to invoke method on, or %NULL.
246
* @method: The method to invoke.
247
* @returns: A newly allocate IBusMessage with the error information; or %NULL if memory cannot be allocated.
248
*
249
* Constructs a new message representing a signal emission.
250
* Returns NULL if memory can't be allocated for the message.
251
* A signal is identified by its originating object path, interface, and the name of the signal.
252
* Path, interface, and signal name must all be valid (the D-Bus specification defines the syntax of these fields).
253
*/
60
254
IBusMessage *ibus_message_new_signal (const gchar *path,
61
255
const gchar *interface,
62
256
const gchar *method);
257
258
/**
259
* ibus_message_is_method_call:
260
* @message: An IBusMessage.
261
* @interface: The interface to check. Cannot be %NULL.
262
* @method: The method to check. Cannot be %NULL.
263
* @returns: %TRUE if @message is DBUS_MESSAGE_TYPE_METHOD_CALL and the invoked method is matched with @method;
264
* %FALSE otherwise.
265
*
266
* Checks whether the message is a method call with the given interface and member fields.
267
*
268
* If the message is not DBUS_MESSAGE_TYPE_METHOD_CALL,
269
* or has a different interface or member field, returns FALSE.
270
* If the interface field is missing, then it will be assumed equal to the provided interface.
271
* The D-Bus protocol allows method callers to leave out the interface name.
272
*/
63
273
gboolean ibus_message_is_method_call (IBusMessage *message,
64
274
const gchar *interface,
65
275
const gchar *method);
276
/**
277
* ibus_message_is_error:
278
* @message: An IBusMessage.
279
* @error_name: Name of the error to check.
280
* @returns: %TRUE if @message is DBUS_MESSAGE_TYPE_ERROR and the error name is matched with @error_name;
281
* %FALSE otherwise.
282
*
283
* Checks whether the message is an error reply with the given error name.
284
* If the message is not DBUS_MESSAGE_TYPE_ERROR, or has a different name, returns FALSE.
285
*/
66
286
gboolean ibus_message_is_error (IBusMessage *message,
67
287
const gchar *error_name);
288
289
/**
290
* ibus_message_is_signal:
291
* @message: An IBusMessage.
292
* @interface: The interface to checked. Cannot be %NULL.
293
* @signal_name: The signal name to check.
294
* @returns: %TRUE if @message is %DBUS_MESSAGE_SIGNAL and the signal name is matched with @signal_name;
295
* %FALSE otherwise.
296
*
297
* Checks whether the message is a signal with the given interface and member fields.
298
* If the message is not %DBUS_MESSAGE_TYPE_SIGNAL, or has a different interface or member field, returns %FALSE.
299
*/
68
300
gboolean ibus_message_is_signal (IBusMessage *message,
69
301
const gchar *interface,
70
302
const gchar *signal_name);
303
304
/**
305
* ibus_message_set_destination:
306
* @message: An IBusMessage.
307
* @destination: Destination to set; or %NULL to unset.
308
* @returns: %TRUE if succeed; %FALSE if insufficient memory.
309
*
310
* Sets the message's destination.
311
*
312
* The destination is the name of another connection on the bus
313
* and may be either the unique name assigned by the bus to each connection,
314
* or a well-known name specified in advance.
315
*
316
* The destination name must contain only valid characters as defined in the D-Bus specification.
317
*/
71
318
gboolean ibus_message_set_destination (IBusMessage *message,
72
319
const gchar *destination);
320
/**
321
* ibus_message_set_sender:
322
* @message: An IBusMessage.
323
* @sender: Sender to set; or %NULL to unset.
324
* @returns: %TRUE if succeed; %FALSE if insufficient memory.
325
*
326
* Sets the message sender.
327
*
328
* The sender must be a valid bus name as defined in the D-Bus specification.
329
*
330
* Usually you don't want to call this. The message bus daemon will call it to set the origin of each message.
331
* If you aren't implementing a message bus daemon you shouldn't need to set the sender.
332
*/
73
333
gboolean ibus_message_set_sender (IBusMessage *message,
74
334
const gchar *sender);
335
336
/**
337
* ibus_message_set_error_name:
338
* @message: An IBusMessage.
339
* @error_name: Error name to set; or %NULL to unset.
340
* @returns: %TRUE if succeed; %FALSE if insufficient memory.
341
*
342
* Sets the name of the error (%DBUS_MESSAGE_TYPE_ERROR).
343
*
344
* The name is fully-qualified (namespaced).
345
*
346
* The error name must contain only valid characters as defined in the D-Bus specification.
347
*/
75
348
gboolean ibus_message_set_error_name (IBusMessage *message,
76
349
const gchar *error_name);
350
351
/**
352
* ibus_message_set_interface:
353
* @message: An IBusMessage.
354
* @interface: Interface to set; or %NULL to unset.
355
* @returns: %TRUE if succeed; %FALSE if insufficient memory.
356
*
357
* Sets the interface this message is being sent to
358
* (for %DBUS_MESSAGE_TYPE_METHOD_CALL) or the interface
359
* a signal is being emitted from (for %DBUS_MESSAGE_TYPE_SIGNAL).
360
*
361
* The interface name must contain only valid characters as defined in the D-Bus specification.
362
*/
77
363
gboolean ibus_message_set_interface (IBusMessage *message,
78
364
const gchar *interface);
365
366
/**
367
* ibus_message_set_member:
368
* @message: An IBusMessage.
369
* @member: Member to set; or %NULL to unset.
370
* @returns: %TRUE if succeed; %FALSE if insufficient memory.
371
*
372
* Sets the interface member being invoked (%DBUS_MESSAGE_TYPE_METHOD_CALL)
373
* or emitted (%DBUS_MESSAGE_TYPE_SIGNAL).
374
*
375
* The member name must contain only valid characters as defined in the D-Bus specification.
376
*/
79
377
gboolean ibus_message_set_member (IBusMessage *message,
80
378
const gchar *member);
379
380
/**
381
* ibus_message_set_path:
382
* @message: An IBusMessage.
383
* @path: Path to set; or %NULL to unset.
384
* @returns: %TRUE if succeed; %FALSE if insufficient memory.
385
*
386
* Sets the object path this message is being sent to (for $DBUS_MESSAGE_TYPE_METHOD_CALL)
387
* or the one a signal is being emitted from (for %DBUS_MESSAGE_TYPE_SIGNAL).
388
*
389
* The path must contain only valid characters as defined in the D-Bus specification.
390
*/
81
391
gboolean ibus_message_set_path (IBusMessage *message,
82
392
const gchar *path);
393
394
/**
395
* ibus_message_set_no_reply:
396
* @message: An IBusMessage.
397
* @no_reply: %TRUE if no reply is desired.
398
*
399
* Sets a flag indicating that the message does not want a reply;
400
* if this flag is set, the other end of the connection may (but is not required to)
401
* optimize by not sending method return or error replies.
402
*
403
* If this flag is set, there is no way to know whether the message successfully arrived
404
* at the remote end.
405
* Normally you know a message was received when you receive the reply to it.
406
*
407
* The flag is FALSE by default, that is by default the other end is required to reply.
408
*
409
* On the protocol level this toggles %DBUS_HEADER_FLAG_NO_REPLY_EXPECTED.
410
*/
83
411
void ibus_message_set_no_reply (IBusMessage *message,
84
412
gboolean no_reply);
413
414
/**
415
* ibus_message_set_reply_serial:
416
* @message: An IBusMessage.
417
* @reply_serial: The serial to be replied.
418
* @returns: %TRUE if succeed; %FALSE if insufficient memory.
419
*
420
* Sets the reply serial of a message (the serial of the message this is a reply to).
421
*/
85
422
gboolean ibus_message_set_reply_serial (IBusMessage *message,
86
423
guint32 reply_serial);
424
425
/**
426
* ibus_message_get_type:
427
* @message: An IBusMessage.
428
* @returns: Type of the IBusMessage.
429
*
430
* Gets the type of an IBusMessage.
431
*/
87
432
gint ibus_message_get_type (IBusMessage *message);
433
434
/**
435
* ibus_message_get_destination:
436
* @message: An IBusMessage.
437
* @returns: Destination of the IBusMessage; NULL if there is none set.
438
*
439
* Gets the destination of a message or %NULL if there is none set.
440
*
441
* The returned string becomes invalid if the message is modified,
442
* since it points into the wire-marshaled message data.
443
*/
88
444
const gchar *ibus_message_get_destination (IBusMessage *message);
445
446
/**
447
* ibus_message_get_sender:
448
* @message: An IBusMessage.
449
* @returns: Sender of the IBusMessage; %NULL if unknown or inapplicable.
450
*
451
* Gets the unique name of the connection which originated this message,
452
* or %NULL if unknown or inapplicable.
453
*
454
* The sender is filled in by the message bus.
455
*
456
* Note, the returned sender is always the unique bus name.
457
* Connections may own multiple other bus names, but those are not found in the sender field.
458
*
459
* The returned string becomes invalid if the message is modified,
460
* since it points into the wire-marshaled message data.
461
*/
89
462
const gchar *ibus_message_get_sender (IBusMessage *message);
463
464
/**
465
* ibus_message_get_error_name:
466
* @message: An IBusMessage.
467
* @returns: Error name of the IBusMessage; %NULL if none.
468
*
469
* Gets the error name (%DBUS_MESSAGE_TYPE_ERROR only) or %NULL if none.
470
*
471
* The returned string becomes invalid if the message is modified,
472
* since it points into the wire-marshaled message data.
473
*/
90
474
const gchar *ibus_message_get_error_name (IBusMessage *message);
475
476
/**
477
* ibus_message_get_error_message:
478
* @message: An IBusMessage.
479
* @returns: Error message of the IBusMessage; %NULL if none.
480
*
481
* Gets the error message (%DBUS_MESSAGE_TYPE_ERROR only) or %NULL if none.
482
*
483
* The returned string becomes invalid if the message is modified,
484
* since it points into the wire-marshaled message data.
485
*/
91
486
const gchar *ibus_message_get_error_message (IBusMessage *message);
487
488
/**
489
* ibus_message_get_interface:
490
* @message: An IBusMessage.
491
* @returns: Interface name of the IBusMessage; %NULL if none.
492
*
493
* Gets the interface this message is being sent to (for %DBUS_MESSAGE_TYPE_METHOD_CALL)
494
* or being emitted from (for %DBUS_MESSAGE_TYPE_SIGNAL).
495
*
496
* The interface name is fully-qualified (namespaced). Returns %NULL if none.
497
*
498
* The returned string becomes invalid if the message is modified,
499
* since it points into the wire-marshaled message data.
500
*/
92
501
const gchar *ibus_message_get_interface (IBusMessage *message);
502
503
/**
504
* ibus_message_get_member:
505
* @message: An IBusMessage.
506
* @returns: Member name of the IBusMessage; %NULL if none.
507
*
508
* Gets the interface member being invoked (%DBUS_MESSAGE_TYPE_METHOD_CALL)
509
* or emitted (%DBUS_MESSAGE_TYPE_SIGNAL).
510
*
511
* Returns %NULL if none.
512
*
513
* The returned string becomes invalid if the message is modified,
514
* since it points into the wire-marshaled message data.
515
*/
93
516
const gchar *ibus_message_get_member (IBusMessage *message);
517
518
/**
519
* ibus_message_get_path:
520
* @message: An IBusMessage.
521
* @returns: Object path of the IBusMessage; %NULL if none.
522
*
523
* Gets the object path this message is being sent to (for %DBUS_MESSAGE_TYPE_METHOD_CALL)
524
* or being emitted from (for %DBUS_MESSAGE_TYPE_SIGNAL).
525
*
526
* Returns %NULL if none.
527
*
528
* See also dbus_message_get_path_decomposed().
529
*
530
* The returned string becomes invalid if the message is modified,
531
* since it points into the wire-marshaled message data.
532
*/
94
533
const gchar *ibus_message_get_path (IBusMessage *message);
534
535
/**
536
* ibus_message_get_no_reply:
537
* @message: An IBusMessage.
538
* @returns: %TRUE if the message does not expect a reply; %FALSE otherwise.
539
*
540
* Returns TRUE if the message does not expect a reply.
541
*/
95
542
gboolean ibus_message_get_no_reply (IBusMessage *message);
543
544
/**
545
* ibus_message_get_reply_serial:
546
* @message: An IBusMessage.
547
* @returns: The serial that the message is a reply to or 0 if none.
548
*
549
* Returns the serial that the message is a reply to or 0 if none.
550
*/
96
551
guint32 ibus_message_get_reply_serial (IBusMessage *message);
552
553
/**
554
* ibus_message_get_reply_serial:
555
* @message: An IBusMessage.
556
* @returns: The serial of a message or 0 if none has been specified.
557
*
558
* Returns the serial of a message or 0 if none has been specified.
559
*
560
* The message's serial number is provided by the application sending the message
561
* and is used to identify replies to this message.
562
*
563
* All messages received on a connection will have a serial provided by the remote application.
564
*
565
* For messages you're sending, dbus_connection_send() will assign a serial and return it to you.
566
*/
97
567
guint32 ibus_message_get_serial (IBusMessage *message);
568
569
/**
570
* ibus_message_append_args:
571
* @message: An IBusMessage.
572
* @first_arg_type: Type of the first argument.
573
* @...: Rest of arguments.
574
* @returns: %TRUE if succeed; %FALSE otherwise.
575
*
576
* Appends fields to a message given a variable argument list.
577
*
578
* The variable argument list should contain the type of each argument followed by the value to append.
579
* Appendable types are basic types, and arrays of fixed-length basic types.
580
* To append variable-length basic types, or any more complex value,
581
* you have to use an iterator rather than this function.
582
*
583
* To append a basic type, specify its type code followed by the address of the value. For example:
584
* <informalexample>
585
* <programlisting>
586
* dbus_int32_t v_INT32 = 42;
587
* const char *v_STRING = "Hello World";
588
* dbus_message_append_args (message,
589
* DBUS_TYPE_INT32, &v_INT32,
590
* DBUS_TYPE_STRING, &v_STRING,
591
* DBUS_TYPE_INVALID);
592
* </programlisting>
593
* </informalexample>
594
*
595
* To append an array of fixed-length basic types, pass in the %DBUS_TYPE_ARRAY typecode,
596
* the element typecode, the address of the array pointer,
597
* and a 32-bit integer giving the number of elements in the array. So for example:
598
* <informalexample>
599
* <programlisting>
600
* const dbus_int32_t array[] = { 1, 2, 3 };
601
* const dbus_int32_t *v_ARRAY = array;
602
* dbus_message_append_args (message,
603
* DBUS_TYPE_ARRAY, DBUS_TYPE_INT32, &v_ARRAY, 3,
604
* DBUS_TYPE_INVALID);
605
* </programlisting>
606
* </informalexample>
607
*
608
*
609
* <note><para>
610
* in C, given "int array[]", "&array == array" (the comp.lang.c FAQ says otherwise, but gcc and the FAQ don't agree).
611
* So if you're using an array instead of a pointer you have to create a pointer variable,
612
* assign the array to it, then take the address of the pointer variable.
613
* For strings it works to write const char *array = "Hello" and then use &array though.
614
* </para></note>
615
*
616
* The last argument to this function must be %DBUS_TYPE_INVALID, marking the end of the argument list.
617
* If you don't do this then libdbus won't know to stop and will read invalid memory.
618
*
619
* String/signature/path arrays should be passed in as "const char*** address_of_array" and "int n_elements"
620
*
621
* @see_also: ibus_message_append_args_valist().
622
*/
98
623
gboolean ibus_message_append_args (IBusMessage *message,
99
624
GType first_arg_type,
100
625
...);
626
627
/**
628
* ibus_message_append_args_valist:
629
* @message: An IBusMessage.
630
* @first_arg_type: Type of the first argument.
631
* @va_args: Rest of arguments.
632
* @returns: %TRUE if succeed; %FALSE otherwise.
633
* @see_also: ibus_message_append_args().
634
*
635
* Like ibus_message_append_args() but takes a va_list for use by language bindings.
636
*/
101
637
gboolean ibus_message_append_args_valist(IBusMessage *message,
102
638
GType first_arg_type,
103
639
va_list va_args);
640
641
/**
642
* ibus_message_get_args:
643
* @message: An IBusMessage.
644
* @error: Error to be filled in on failure.
645
* @first_arg_type: Type of the first argument.
646
* @...: Rest of arguments.
647
* @returns: %TRUE if succeed; F%ALSE otherwise.
648
*
649
* Gets arguments from a message given a variable argument list.
650
*
651
* The supported types include those supported by ibus_message_append_args();
652
* that is, basic types and arrays of fixed-length basic types.
653
* The arguments are the same as they would be for ibus_message_iter_get_basic()
654
* or ibus_message_iter_get_fixed_array().
655
*
656
* In addition to those types, arrays of string, object path, and signature are supported;
657
* but these are returned as allocated memory and must be freed with dbus_free_string_array(),
658
* while the other types are returned as const references.
659
* To get a string array pass in "char ***array_location" and "int *n_elements".
660
*
661
* The variable argument list should contain the type of the argument followed by a pointer to
662
* where the value should be stored. The list is terminated with %DBUS_TYPE_INVALID.
663
*
664
* Except for string arrays, the returned values are constant; do not free them.
665
* They point into the IBusMessage.
666
*
667
* If the requested arguments are not present, or do not have the requested types, then an error will be set.
668
*
669
* If more arguments than requested are present,
670
* the requested arguments are returned and the extra arguments are ignored.
671
*
672
* @see_also: ibus_message_append_args(), ibus_message_get_args_valist().
673
*/
104
674
gboolean ibus_message_get_args (IBusMessage *message,
105
675
IBusError **error,
106
676
GType first_arg_type,
107
677
...);
678
679
/**
680
* ibus_message_append_args_valist:
681
* @message: An IBusMessage.
682
* @first_arg_type: Type of the first argument.
683
* @va_args: Rest of arguments.
684
* @returns: %TRUE if succeed; %FALSE otherwise.
685
*
686
* Like ibus_message_get_args but takes a va_list for use by language bindings.
687
*
688
* @see_also: ibus_message_append_args_valist(), ibus_message_get_args().
689
*/
108
690
gboolean ibus_message_get_args_valist (IBusMessage *message,
109
691
IBusError **error,
110
692
GType first_arg_type,
111
693
va_list va_args);
694
695
/**
696
* ibus_message_iter_init_append:
697
* @message: An IBusMessage.
698
* @iter: An IBusMessageIter to to initialize.
699
*
700
* Initializes a #IBusMessageIter for appending arguments to the end of a message.
701
*/
112
702
void ibus_message_iter_init_append (IBusMessage *message,
113
703
IBusMessageIter *iter);
704
/**
705
* ibus_message_iter_append:
706
* @iter: An IBusMessageIter.
707
* @type: The type of the value.
708
* @value: The pointer to the value.
709
* @returns: %TRUE if succeed; %FALSE if insufficient memory.
710
*
711
* Appends a basic-typed value to the message.
712
*
713
* The basic types are the non-container types such as integer and string.
714
*
715
* The "value" argument should be the address of a basic-typed value.
716
* So for string, const char**. For integer, dbus_int32_t*.
717
*/
114
718
gboolean ibus_message_iter_append (IBusMessageIter *iter,
115
719
GType type,
116
720
gconstpointer value);
721
722
gboolean ibus_message_iter_copy_data (IBusMessageIter *dst,
723
IBusMessageIter *src);
724
725
/**
726
* ibus_message_iter_init:
727
* @message: An IBusMessage.
728
* @iter: An IBusMessageIter.
729
* @returns: %TRUE if succeed; %FALSE if the message has no arguments.
730
*
731
* Initializes an #IBusMessageIter for reading the arguments of the message passed in.
732
*
733
* When possible, ibus_message_get_args() is much more convenient.
734
* Some types of argument can only be read with IBusMessageIter however.
735
*
736
* The easiest way to iterate is like this:
737
* <informalexample>
738
* <programlisting>
739
* dbus_message_iter_init (&iter);
740
* while ((current_type = dbus_message_iter_get_arg_type (&iter)) != DBUS_TYPE_INVALID)
741
* dbus_message_iter_next (&iter);
742
* </programlisting>
743
* </informalexample>
744
*
745
* IBusMessageIter contains no allocated memory;
746
* it need not be freed, and can be copied by assignment or memcpy().
747
*/
117
748
gboolean ibus_message_iter_init (IBusMessage *message,
118
749
IBusMessageIter *iter);
119
gboolean ibus_message_iter_peek (IBusMessageIter *iter,
120
GType type,
121
gpointer value);
750
751
/**
752
* ibus_message_iter_get_basic:
753
* @iter: An IBusMessageIter.
754
* @value: Result value stores here. Cannot be %NULL.
755
*
756
* Reads a basic-typed value from the message iterator.
757
*
758
* Basic types are the non-containers such as integer and string.
759
*
760
* The value argument should be the address of a location to store the returned value.
761
* So for int32 it should be a "dbus_int32_t*" and for string a "const char**".
762
* The returned value is by reference and should not be freed.
763
*
764
* Be sure you have somehow checked that dbus_message_iter_get_arg_type() matches the type you are expecting,
765
* or you'll crash when you try to use an integer as a string or something.
766
*
767
* To read any container type (array, struct, dict) you will need to recurse into the container with
768
* dbus_message_iter_recurse().
769
* If the container is an array of fixed-length values,
770
* you can get all the array elements at once with dbus_message_iter_get_fixed_array().
771
* Otherwise, you have to iterate over the container's contents one value at a time.
772
*
773
* All basic-typed values are guaranteed to fit in 8 bytes. So you can write code like this:
774
* <informalexample>
775
* <programlisting>
776
* dbus_uint64_t value;
777
* int type;
778
* dbus_message_iter_get_basic (&read_iter, &value);
779
* type = dbus_message_iter_get_arg_type (&read_iter);
780
* dbus_message_iter_append_basic (&write_iter, type, &value);
781
* </programlisting>
782
* </informalexample>
783
*
784
* On some really obscure platforms dbus_uint64_t might not exist,
785
* if you need to worry about this you will know.
786
* dbus_uint64_t is just one example of a type that's large enough to hold any possible value,
787
* you could use a struct or char[8] instead if you like.
788
*/
122
789
void ibus_message_iter_get_basic (IBusMessageIter *iter,
123
790
gpointer value);
791
792
/**
793
* ibus_message_iter_get:
794
* @iter: An IBusMessageIter.
795
* @type: The type of the value. Cannot be %NULL.
796
* @value: Result value stores here. Cannot be %NULL.
797
* @returns: %TRUE if succeed; %FALSE if insufficient memory.
798
*
799
* Gets an value from an IBusMessageIter, then move on to the next element.
800
*
801
*/
124
802
gboolean ibus_message_iter_get (IBusMessageIter *iter,
125
803
GType type,
126
804
gpointer value);
805
806
/**
807
* ibus_message_iter_next:
808
* @iter: An IBusMessageIter.
809
* @returns: %TRUE if the iterator moves forward successfully; %FALSE if next element does not exist.
810
*
811
* Moves the iterator to the next field, if any.
812
*
813
* If there's no next field, returns %FALSE. If the iterator moves forward, returns %TRUE.
814
*/
127
815
gboolean ibus_message_iter_next (IBusMessageIter *iter);
816
817
/**
818
* ibus_message_iter_has_next:
819
* @iter: An IBusMessageIter.
820
* @returns: %TRUE if next element exists; %FALSE otherwise.
821
*
822
* Checks if an iterator has any more fields.
823
*/
128
824
gboolean ibus_message_iter_has_next (IBusMessageIter *iter);
825
826
/**
827
* ibus_message_iter_open_container:
828
* @iter: An IBusMessageIter.
829
* @type: The type of the value.
830
* @contained_signature: The type of container contents.
831
* @sub: Sub-iterator to initialize.
832
* @returns: %TRUE if succeed; %FALSE if insufficient memory.
833
*
834
* Appends a container-typed value to the message;
835
* you are required to append the contents of the container using the returned sub-iterator,
836
* and then call dbus_message_iter_close_container().
837
*
838
* Container types are for example struct, variant, and array.
839
* For variants, the contained_signature should be the type of the single value inside the variant.
840
* For structs and dict entries, contained_signature should be %NULL;
841
* it will be set to whatever types you write into the struct.
842
* For arrays, contained_signature should be the type of the array elements.
843
*/
129
844
gboolean ibus_message_iter_open_container
130
845
(IBusMessageIter *iter,
131
846
GType type,
132
847
const gchar *contained_signature,
133
848
IBusMessageIter *sub);
849
850
/**
851
* ibus_message_iter_close_container:
852
* @iter: An IBusMessageIter.
853
* @sub: Sub-iterator to close.
854
* @returns: %TRUE if succeed; %FALSE if insufficient memory.
855
*
856
* Closes a container-typed value appended to the message;
857
* may write out more information to the message known only after the entire container is written,
858
* and may free resources created by dbus_message_iter_open_container().
859
*/
134
860
gboolean ibus_message_iter_close_container
135
861
(IBusMessageIter *iter,
136
862
IBusMessageIter *sub);
863
864
/**
865
* ibus_message_iter_recurse:
866
* @iter: An IBusMessageIter.
867
* @type: The type of the value.
868
* @sub: Sub-iterator to initialize.
869
* @returns: %TRUE if succeed; %FALSE if insufficient memory.
870
*
871
* Recurses into a container value when reading values from a message,
872
* initializing a sub-iterator to use for traversing the child values of the container.
873
*
874
* Note that this recurses into a value, not a type, so you can only recurse if the value exists.
875
* The main implication of this is that if you have for example an empty array of array of int32,
876
* you can recurse into the outermost array, but it will have no values, so you won't be able to recurse further.
877
* There's no array of int32 to recurse into.
878
*
879
* If a container is an array of fixed-length types, it is much more efficient to use
880
* dbus_message_iter_get_fixed_array() to get the whole array in one shot,
881
* rather than individually walking over the array elements.
882
*
883
* Be sure you have somehow checked that dbus_message_iter_get_arg_type()
884
* matches the type you are expecting to recurse into.
885
* Results of this function are undefined if there is no container to recurse into at the current iterator position.
886
*/
137
887
gboolean ibus_message_iter_recurse (IBusMessageIter *iter,
138
888
GType type,
139
889
IBusMessageIter *sub);
890
891
/**
892
* ibus_message_iter_get_arg_type:
893
* @iter: An IBusMessageIter.
894
* @returns: The argument type.
895
*
896
* Returns the argument type of the argument that the message iterator points to.
897
*
898
* If the iterator is at the end of the message, returns %DBUS_TYPE_INVALID.
899
* You can thus write a loop as follows:
900
* <informalexample>
901
* <programlisting>
902
* dbus_message_iter_init (&iter);
903
* while ((current_type = dbus_message_iter_get_arg_type (&iter)) != DBUS_TYPE_INVALID)
904
* dbus_message_iter_next (&iter);
905
* </programlisting>
906
* </informalexample>
907
*/
140
908
GType ibus_message_iter_get_arg_type (IBusMessageIter *iter);
909
910
/**
911
* ibus_message_iter_get_element_type:
912
* @iter: An IBusMessageIter.
913
* @returns: The argument type.
914
*
915
* Returns the element type of the array that the message iterator points to.
916
* Note that you need to check that the iterator points to an array prior to using this function.
917
*/
141
918
GType ibus_message_iter_get_element_type
142
919
(IBusMessageIter *iter);
920
921
/**
922
* ibus_message_to_string:
923
* @message: An IBusMessage.
924
* @returns: A string which shows the information of the message.
925
*
926
* Produces a pretty formatted string which show the information of the IBusMessage.
927
* This string is suitable for debugging information print out.
928
*
929
* Free the string by g_free() after use.
930
*/
143
931
gchar *ibus_message_to_string (IBusMessage *message);
144
932
145
933
G_END_DECLS
Loggerhead is a web-based interface for Breezy
Version: 2.0.1