1
/* -*- mode: C; c-basic-offset: 4; indent-tabs-mode: nil; -*- */
2
/* vim:set et sts=4: */
3
/* ibus - The Input Bus
4
* Copyright (C) 2008-2010 Peng Huang <shawn.p.huang@gmail.com>
5
* Copyright (C) 2008-2010 Red Hat, Inc.
7
* This library is free software; you can redistribute it and/or
8
* modify it under the terms of the GNU Lesser General Public
9
* License as published by the Free Software Foundation; either
10
* version 2 of the License, or (at your option) any later version.
12
* This library is distributed in the hope that it will be useful,
13
* but WITHOUT ANY WARRANTY; without even the implied warranty of
14
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15
* Lesser General Public License for more details.
17
* You should have received a copy of the GNU Lesser General Public
18
* License along with this library; if not, write to the
19
* Free Software Foundation, Inc., 59 Temple Place - Suite 330,
20
* Boston, MA 02111-1307, USA.
23
* SECTION: ibusmessage
25
* @Short_description: A DBusMessage in IBus.
28
* An IBusMessage is essentially a DBusMessage, which representing a message received from or to
29
* be sent to another application.
31
* Besides DBusMessage functions, An IBusMessage can be manipulated
32
* with its own specific functions, which are defined in this section.
34
#ifndef __IBUS_MESSAGE_H_
35
#define __IBUS_MESSAGE_H_
38
#include <glib-object.h>
40
#include "ibuserror.h"
43
* IBUS_TYPE_OBJECT_PATH:
45
* Type of object path.
47
#define IBUS_TYPE_OBJECT_PATH (ibus_type_get_object_path ())
54
#define IBUS_TYPE_ARRAY (ibus_type_get_array ())
61
#define IBUS_TYPE_STRUCT (ibus_type_get_struct ())
64
* IBUS_TYPE_DICT_ENTRY:
66
* Type of IBusDictEntry.
68
#define IBUS_TYPE_DICT_ENTRY (ibus_type_get_dict_entry ())
73
* Type of IBusVariant.
75
#define IBUS_TYPE_VARIANT (ibus_type_get_variant ())
80
* ibus_type_get_object_path:
81
* @returns: Type of object path.
83
* Gets the type of object path.
85
GType ibus_type_get_object_path (void);
88
* ibus_type_get_array:
89
* @returns: Type of IBusArray.
91
* Gets the type of IBusArray.
93
GType ibus_type_get_array (void);
96
* ibus_type_get_struct:
97
* @returns: Type of IBusStruct.
99
* Gets the type of IBusStruct.
101
GType ibus_type_get_struct (void);
104
* ibus_type_get_dict_entry:
105
* @returns: Type of IBusDictEntry.
107
* Gets the type of IBusDictEntry.
109
GType ibus_type_get_dict_entry (void);
112
* ibus_type_get_variant:
113
* @returns: Type of IBusVariant.
115
* Gets the type of IBusVariant.
117
GType ibus_type_get_variant (void);
121
* @message_type: Type of the message.
122
* @returns: A newly allocated IBusMessage according to @message_type.
124
* New an IBusMessage.
125
* Valid D-Bus message types include:
128
* <para>#DBUS_MESSAGE_TYPE_METHOD_CALL</para>
131
* <para>#DBUS_MESSAGE_TYPE_METHOD_RETURN</para>
134
* <para>#DBUS_MESSAGE_TYPE_ERROR</para>
137
* <para>#DBUS_MESSAGE_TYPE_SIGNAL</para>
140
* These are defined in dbus-protocol.h in D-Bus.
142
IBusMessage *ibus_message_new (gint message_type);
146
* @message: An IBusMessage.
147
* @returns: The IBusMessage.
149
* Increments the reference count of an IBusMessage.
151
IBusMessage *ibus_message_ref (IBusMessage *message);
154
* ibus_message_unref:
155
* @message: An IBusMessage.
157
* Decrements the reference count of a DBusMessage, freeing the message if the count reaches 0.
159
void ibus_message_unref (IBusMessage *message);
162
* ibus_message_new_method_call:
163
* @destination: Where this message to be sent to or %NULL for no destination.
164
* @path: Object path the message should be sent to.
165
* @interface: Interface to invoke method on, or %NULL.
166
* @method: The method to be invoked.
167
* @returns: A newly allocate IBusMessage; or %NULL if memory cannot be allocated.
169
* Constructs a new message to invoke a method on a remote object.
171
* The destination may be %NULL in which case no destination is set;
172
* this is appropriate when using IBus/D-Bus in a peer-to-peer context (no message bus).
173
* The interface may be %NULL, which means that if multiple methods with the given name
174
* exist it is undefined which one will be invoked.
176
* The path and method names may not be %NULL.
178
* Destination, path, interface, and method name can't contain any invalid characters
179
* (see the D-Bus specification).
181
IBusMessage *ibus_message_new_method_call (const gchar *destination,
183
const gchar *interface,
184
const gchar *method);
187
* ibus_message_new_method_return:
188
* @reply_to: The IBusMessage being replied to.
189
* @returns: A newly allocate IBusMessage; or %NULL if memory cannot be allocated.
191
* Constructs a message that is a reply to a method call.
193
IBusMessage *ibus_message_new_method_return (IBusMessage *reply_to);
196
* ibus_message_new_error:
197
* @reply_to: The IBusMessage being replied to.
198
* @error_name: Name of the error.
199
* @error_message: Detailed error message string (or %NULL for none, but please give a message).
200
* @returns: A newly allocate IBusMessage with the error information; or %NULL if memory cannot be allocated.
202
* Creates a new message that is an error reply to another message.
203
* Error replies are most common in response to method calls, but can be returned in reply to any message.
204
* The error name must be a valid error name according to the syntax given in the D-Bus specification.
205
* If you don't want to make up an error name just use %DBUS_ERROR_FAILED.
207
* Use ibus_message_unref() to free the produced IBusMessage.
209
IBusMessage *ibus_message_new_error (IBusMessage *reply_to,
210
const gchar *error_name,
211
const gchar *error_message);
214
* ibus_message_new_error_printf:
215
* @reply_to: The IBusMessage being replied to.
216
* @error_name: Name of the error.
217
* @error_format: Error format string as in printf() format.
218
* @...: Format arguments, as in printf().
219
* @returns: A newly allocate IBusMessage with the error information; or %NULL if memory cannot be allocated.
221
* Creates a new message that is an error reply to another message.
222
* Error replies are most common in response to method calls, but can be returned in reply to any message.
223
* The error name must be a valid error name according to the syntax given in the D-Bus specification.
224
* If you don't want to make up an error name just use %DBUS_ERROR_FAILED.
226
IBusMessage *ibus_message_new_error_printf (IBusMessage *reply_to,
227
const gchar *error_name,
228
const gchar *error_format,
232
* ibus_message_new_signal:
233
* @path: Object path the message should be sent to.
234
* @interface: Interface to invoke method on, or %NULL.
235
* @method: The method to invoke.
236
* @returns: A newly allocate IBusMessage with the error information; or %NULL if memory cannot be allocated.
238
* Constructs a new message representing a signal emission.
239
* Returns NULL if memory can't be allocated for the message.
240
* A signal is identified by its originating object path, interface, and the name of the signal.
241
* Path, interface, and signal name must all be valid (the D-Bus specification defines the syntax of these fields).
243
IBusMessage *ibus_message_new_signal (const gchar *path,
244
const gchar *interface,
245
const gchar *method);
248
* ibus_message_is_method_call:
249
* @message: An IBusMessage.
250
* @interface: The interface to check. Cannot be %NULL.
251
* @method: The method to check. Cannot be %NULL.
252
* @returns: %TRUE if @message is DBUS_MESSAGE_TYPE_METHOD_CALL and the invoked method is matched with @method;
255
* Checks whether the message is a method call with the given interface and member fields.
257
* If the message is not DBUS_MESSAGE_TYPE_METHOD_CALL,
258
* or has a different interface or member field, returns FALSE.
259
* If the interface field is missing, then it will be assumed equal to the provided interface.
260
* The D-Bus protocol allows method callers to leave out the interface name.
262
gboolean ibus_message_is_method_call (IBusMessage *message,
263
const gchar *interface,
264
const gchar *method);
266
* ibus_message_is_error:
267
* @message: An IBusMessage.
268
* @error_name: Name of the error to check.
269
* @returns: %TRUE if @message is DBUS_MESSAGE_TYPE_ERROR and the error name is matched with @error_name;
272
* Checks whether the message is an error reply with the given error name.
273
* If the message is not DBUS_MESSAGE_TYPE_ERROR, or has a different name, returns FALSE.
275
gboolean ibus_message_is_error (IBusMessage *message,
276
const gchar *error_name);
279
* ibus_message_is_signal:
280
* @message: An IBusMessage.
281
* @interface: The interface to checked. Cannot be %NULL.
282
* @signal_name: The signal name to check.
283
* @returns: %TRUE if @message is %DBUS_MESSAGE_SIGNAL and the signal name is matched with @signal_name;
286
* Checks whether the message is a signal with the given interface and member fields.
287
* If the message is not %DBUS_MESSAGE_TYPE_SIGNAL, or has a different interface or member field, returns %FALSE.
289
gboolean ibus_message_is_signal (IBusMessage *message,
290
const gchar *interface,
291
const gchar *signal_name);
294
* ibus_message_set_destination:
295
* @message: An IBusMessage.
296
* @destination: Destination to set; or %NULL to unset.
297
* @returns: %TRUE if succeed; %FALSE if insufficient memory.
299
* Sets the message's destination.
301
* The destination is the name of another connection on the bus
302
* and may be either the unique name assigned by the bus to each connection,
303
* or a well-known name specified in advance.
305
* The destination name must contain only valid characters as defined in the D-Bus specification.
307
gboolean ibus_message_set_destination (IBusMessage *message,
308
const gchar *destination);
310
* ibus_message_set_sender:
311
* @message: An IBusMessage.
312
* @sender: Sender to set; or %NULL to unset.
313
* @returns: %TRUE if succeed; %FALSE if insufficient memory.
315
* Sets the message sender.
317
* The sender must be a valid bus name as defined in the D-Bus specification.
319
* Usually you don't want to call this. The message bus daemon will call it to set the origin of each message.
320
* If you aren't implementing a message bus daemon you shouldn't need to set the sender.
322
gboolean ibus_message_set_sender (IBusMessage *message,
323
const gchar *sender);
326
* ibus_message_set_error_name:
327
* @message: An IBusMessage.
328
* @error_name: Error name to set; or %NULL to unset.
329
* @returns: %TRUE if succeed; %FALSE if insufficient memory.
331
* Sets the name of the error (%DBUS_MESSAGE_TYPE_ERROR).
333
* The name is fully-qualified (namespaced).
335
* The error name must contain only valid characters as defined in the D-Bus specification.
337
gboolean ibus_message_set_error_name (IBusMessage *message,
338
const gchar *error_name);
341
* ibus_message_set_interface:
342
* @message: An IBusMessage.
343
* @interface: Interface to set; or %NULL to unset.
344
* @returns: %TRUE if succeed; %FALSE if insufficient memory.
346
* Sets the interface this message is being sent to
347
* (for %DBUS_MESSAGE_TYPE_METHOD_CALL) or the interface
348
* a signal is being emitted from (for %DBUS_MESSAGE_TYPE_SIGNAL).
350
* The interface name must contain only valid characters as defined in the D-Bus specification.
352
gboolean ibus_message_set_interface (IBusMessage *message,
353
const gchar *interface);
356
* ibus_message_set_member:
357
* @message: An IBusMessage.
358
* @member: Member to set; or %NULL to unset.
359
* @returns: %TRUE if succeed; %FALSE if insufficient memory.
361
* Sets the interface member being invoked (%DBUS_MESSAGE_TYPE_METHOD_CALL)
362
* or emitted (%DBUS_MESSAGE_TYPE_SIGNAL).
364
* The member name must contain only valid characters as defined in the D-Bus specification.
366
gboolean ibus_message_set_member (IBusMessage *message,
367
const gchar *member);
370
* ibus_message_set_path:
371
* @message: An IBusMessage.
372
* @path: Path to set; or %NULL to unset.
373
* @returns: %TRUE if succeed; %FALSE if insufficient memory.
375
* Sets the object path this message is being sent to (for $DBUS_MESSAGE_TYPE_METHOD_CALL)
376
* or the one a signal is being emitted from (for %DBUS_MESSAGE_TYPE_SIGNAL).
378
* The path must contain only valid characters as defined in the D-Bus specification.
380
gboolean ibus_message_set_path (IBusMessage *message,
384
* ibus_message_set_no_reply:
385
* @message: An IBusMessage.
386
* @no_reply: %TRUE if no reply is desired.
388
* Sets a flag indicating that the message does not want a reply;
389
* if this flag is set, the other end of the connection may (but is not required to)
390
* optimize by not sending method return or error replies.
392
* If this flag is set, there is no way to know whether the message successfully arrived
394
* Normally you know a message was received when you receive the reply to it.
396
* The flag is FALSE by default, that is by default the other end is required to reply.
398
* On the protocol level this toggles %DBUS_HEADER_FLAG_NO_REPLY_EXPECTED.
400
void ibus_message_set_no_reply (IBusMessage *message,
404
* ibus_message_set_reply_serial:
405
* @message: An IBusMessage.
406
* @reply_serial: The serial to be replied.
407
* @returns: %TRUE if succeed; %FALSE if insufficient memory.
409
* Sets the reply serial of a message (the serial of the message this is a reply to).
411
gboolean ibus_message_set_reply_serial (IBusMessage *message,
412
guint32 reply_serial);
415
* ibus_message_get_type:
416
* @message: An IBusMessage.
417
* @returns: Type of the IBusMessage.
419
* Gets the type of an IBusMessage.
421
gint ibus_message_get_type (IBusMessage *message);
424
* ibus_message_get_destination:
425
* @message: An IBusMessage.
426
* @returns: Destination of the IBusMessage; NULL if there is none set.
428
* Gets the destination of a message or %NULL if there is none set.
430
* The returned string becomes invalid if the message is modified,
431
* since it points into the wire-marshaled message data.
433
const gchar *ibus_message_get_destination (IBusMessage *message);
436
* ibus_message_get_sender:
437
* @message: An IBusMessage.
438
* @returns: Sender of the IBusMessage; %NULL if unknown or inapplicable.
440
* Gets the unique name of the connection which originated this message,
441
* or %NULL if unknown or inapplicable.
443
* The sender is filled in by the message bus.
445
* Note, the returned sender is always the unique bus name.
446
* Connections may own multiple other bus names, but those are not found in the sender field.
448
* The returned string becomes invalid if the message is modified,
449
* since it points into the wire-marshaled message data.
451
const gchar *ibus_message_get_sender (IBusMessage *message);
454
* ibus_message_get_error_name:
455
* @message: An IBusMessage.
456
* @returns: Error name of the IBusMessage; %NULL if none.
458
* Gets the error name (%DBUS_MESSAGE_TYPE_ERROR only) or %NULL if none.
460
* The returned string becomes invalid if the message is modified,
461
* since it points into the wire-marshaled message data.
463
const gchar *ibus_message_get_error_name (IBusMessage *message);
466
* ibus_message_get_error_message:
467
* @message: An IBusMessage.
468
* @returns: Error message of the IBusMessage; %NULL if none.
470
* Gets the error message (%DBUS_MESSAGE_TYPE_ERROR only) or %NULL if none.
472
* The returned string becomes invalid if the message is modified,
473
* since it points into the wire-marshaled message data.
475
const gchar *ibus_message_get_error_message (IBusMessage *message);
478
* ibus_message_get_interface:
479
* @message: An IBusMessage.
480
* @returns: Interface name of the IBusMessage; %NULL if none.
482
* Gets the interface this message is being sent to (for %DBUS_MESSAGE_TYPE_METHOD_CALL)
483
* or being emitted from (for %DBUS_MESSAGE_TYPE_SIGNAL).
485
* The interface name is fully-qualified (namespaced). Returns %NULL if none.
487
* The returned string becomes invalid if the message is modified,
488
* since it points into the wire-marshaled message data.
490
const gchar *ibus_message_get_interface (IBusMessage *message);
493
* ibus_message_get_member:
494
* @message: An IBusMessage.
495
* @returns: Member name of the IBusMessage; %NULL if none.
497
* Gets the interface member being invoked (%DBUS_MESSAGE_TYPE_METHOD_CALL)
498
* or emitted (%DBUS_MESSAGE_TYPE_SIGNAL).
500
* Returns %NULL if none.
502
* The returned string becomes invalid if the message is modified,
503
* since it points into the wire-marshaled message data.
505
const gchar *ibus_message_get_member (IBusMessage *message);
508
* ibus_message_get_path:
509
* @message: An IBusMessage.
510
* @returns: Object path of the IBusMessage; %NULL if none.
512
* Gets the object path this message is being sent to (for %DBUS_MESSAGE_TYPE_METHOD_CALL)
513
* or being emitted from (for %DBUS_MESSAGE_TYPE_SIGNAL).
515
* Returns %NULL if none.
517
* See also dbus_message_get_path_decomposed().
519
* The returned string becomes invalid if the message is modified,
520
* since it points into the wire-marshaled message data.
522
const gchar *ibus_message_get_path (IBusMessage *message);
525
* ibus_message_get_no_reply:
526
* @message: An IBusMessage.
527
* @returns: %TRUE if the message does not expect a reply; %FALSE otherwise.
529
* Returns TRUE if the message does not expect a reply.
531
gboolean ibus_message_get_no_reply (IBusMessage *message);
534
* ibus_message_get_reply_serial:
535
* @message: An IBusMessage.
536
* @returns: The serial that the message is a reply to or 0 if none.
538
* Returns the serial that the message is a reply to or 0 if none.
540
guint32 ibus_message_get_reply_serial (IBusMessage *message);
543
* ibus_message_get_serial:
544
* @message: An IBusMessage.
545
* @returns: The serial of a message or 0 if none has been specified.
547
* Returns the serial of a message or 0 if none has been specified.
549
* The message's serial number is provided by the application sending the message
550
* and is used to identify replies to this message.
552
* All messages received on a connection will have a serial provided by the remote application.
554
* For messages you're sending, dbus_connection_send() will assign a serial and return it to you.
556
guint32 ibus_message_get_serial (IBusMessage *message);
559
* ibus_message_append_args:
560
* @message: An IBusMessage.
561
* @first_arg_type: Type of the first argument.
562
* @...: Rest of arguments.
563
* @returns: %TRUE if succeed; %FALSE otherwise.
565
* Appends fields to a message given a variable argument list.
567
* The variable argument list should contain the type of each argument followed by the value to append.
568
* Appendable types are basic types, and arrays of fixed-length basic types.
569
* To append variable-length basic types, or any more complex value,
570
* you have to use an iterator rather than this function.
572
* To append a basic type, specify its type code followed by the address of the value. For example:
575
* dbus_int32_t v_INT32 = 42;
576
* const char *v_STRING = "Hello World";
577
* dbus_message_append_args (message,
578
* DBUS_TYPE_INT32, &v_INT32,
579
* DBUS_TYPE_STRING, &v_STRING,
580
* DBUS_TYPE_INVALID);
584
* To append an array of fixed-length basic types, pass in the %DBUS_TYPE_ARRAY typecode,
585
* the element typecode, the address of the array pointer,
586
* and a 32-bit integer giving the number of elements in the array. So for example:
589
* const dbus_int32_t array[] = { 1, 2, 3 };
590
* const dbus_int32_t *v_ARRAY = array;
591
* dbus_message_append_args (message,
592
* DBUS_TYPE_ARRAY, DBUS_TYPE_INT32, &v_ARRAY, 3,
593
* DBUS_TYPE_INVALID);
599
* in C, given "int array[]", "&array == array" (the comp.lang.c FAQ says otherwise, but gcc and the FAQ don't agree).
600
* So if you're using an array instead of a pointer you have to create a pointer variable,
601
* assign the array to it, then take the address of the pointer variable.
602
* For strings it works to write const char *array = "Hello" and then use &array though.
605
* The last argument to this function must be %DBUS_TYPE_INVALID, marking the end of the argument list.
606
* If you don't do this then libdbus won't know to stop and will read invalid memory.
608
* String/signature/path arrays should be passed in as "const char*** address_of_array" and "int n_elements"
610
* @see_also: ibus_message_append_args_valist().
612
gboolean ibus_message_append_args (IBusMessage *message,
613
GType first_arg_type,
617
* ibus_message_append_args_valist:
618
* @message: An IBusMessage.
619
* @first_arg_type: Type of the first argument.
620
* @va_args: Rest of arguments.
621
* @returns: %TRUE if succeed; %FALSE otherwise.
623
* Like ibus_message_append_args() but takes a va_list for use by language bindings.
625
* @see_also: ibus_message_append_args().
627
gboolean ibus_message_append_args_valist(IBusMessage *message,
628
GType first_arg_type,
632
* ibus_message_get_args:
633
* @message: An IBusMessage.
634
* @error: Error to be filled in on failure.
635
* @first_arg_type: Type of the first argument.
636
* @...: Rest of arguments.
637
* @returns: %TRUE if succeed; F%ALSE otherwise.
639
* Gets arguments from a message given a variable argument list.
641
* The supported types include those supported by ibus_message_append_args();
642
* that is, basic types and arrays of fixed-length basic types.
643
* The arguments are the same as they would be for ibus_message_iter_get_basic()
644
* or ibus_message_iter_get_fixed_array().
646
* In addition to those types, arrays of string, object path, and signature are supported;
647
* but these are returned as allocated memory and must be freed with dbus_free_string_array(),
648
* while the other types are returned as const references.
649
* To get a string array pass in "char ***array_location" and "int *n_elements".
651
* The variable argument list should contain the type of the argument followed by a pointer to
652
* where the value should be stored. The list is terminated with %DBUS_TYPE_INVALID.
654
* Except for string arrays, the returned values are constant; do not free them.
655
* They point into the IBusMessage.
657
* If the requested arguments are not present, or do not have the requested types, then an error will be set.
659
* If more arguments than requested are present,
660
* the requested arguments are returned and the extra arguments are ignored.
662
* @see_also: ibus_message_append_args(), ibus_message_get_args_valist().
664
gboolean ibus_message_get_args (IBusMessage *message,
666
GType first_arg_type,
670
* ibus_message_get_args_valist:
671
* @message: An IBusMessage.
672
* @error: Error message is outputted here; or %NULL to suppress error.
673
* @first_arg_type: Type of the first argument.
674
* @va_args: Rest of arguments.
675
* @returns: %TRUE if succeed; %FALSE otherwise.
677
* Like ibus_message_get_args but takes a va_list for use by language bindings.
679
* @see_also: ibus_message_append_args_valist(), ibus_message_get_args().
681
gboolean ibus_message_get_args_valist (IBusMessage *message,
683
GType first_arg_type,
687
* ibus_message_iter_init_append:
688
* @message: An IBusMessage.
689
* @iter: An IBusMessageIter to to initialize.
691
* Initializes a #IBusMessageIter for appending arguments to the end of a message.
693
void ibus_message_iter_init_append (IBusMessage *message,
694
IBusMessageIter *iter);
696
* ibus_message_iter_append:
697
* @iter: An IBusMessageIter.
698
* @type: The type of the value.
699
* @value: The pointer to the value.
700
* @returns: %TRUE if succeed; %FALSE if insufficient memory.
702
* Appends a basic-typed value to the message.
704
* The basic types are the non-container types such as integer and string.
706
* The "value" argument should be the address of a basic-typed value.
707
* So for string, const char**. For integer, dbus_int32_t*.
709
gboolean ibus_message_iter_append (IBusMessageIter *iter,
711
gconstpointer value);
714
* ibus_message_iter_copy_data:
715
* @dst: Destination to be copy to.
716
* @src: Source to be copy from.
717
* @returns: %TRUE if succeed; %FALSE if failed.
719
* Deep copy an IBusMessageIter to another IBusMessageIter.
721
* Since: 1.2.0.20090719
723
gboolean ibus_message_iter_copy_data (IBusMessageIter *dst,
724
IBusMessageIter *src);
727
* ibus_message_iter_init:
728
* @message: An IBusMessage.
729
* @iter: An IBusMessageIter.
730
* @returns: %TRUE if succeed; %FALSE if the message has no arguments.
732
* Initializes an #IBusMessageIter for reading the arguments of the message passed in.
734
* When possible, ibus_message_get_args() is much more convenient.
735
* Some types of argument can only be read with IBusMessageIter however.
737
* The easiest way to iterate is like this:
740
* dbus_message_iter_init (&iter);
741
* while ((current_type = dbus_message_iter_get_arg_type (&iter)) != DBUS_TYPE_INVALID)
742
* dbus_message_iter_next (&iter);
746
* IBusMessageIter contains no allocated memory;
747
* it need not be freed, and can be copied by assignment or memcpy().
749
gboolean ibus_message_iter_init (IBusMessage *message,
750
IBusMessageIter *iter);
753
* ibus_message_iter_get_basic:
754
* @iter: An IBusMessageIter.
755
* @value: Result value stores here. Cannot be %NULL.
757
* Reads a basic-typed value from the message iterator.
759
* Basic types are the non-containers such as integer and string.
761
* The value argument should be the address of a location to store the returned value.
762
* So for int32 it should be a "dbus_int32_t*" and for string a "const char**".
763
* The returned value is by reference and should not be freed.
765
* Be sure you have somehow checked that dbus_message_iter_get_arg_type() matches the type you are expecting,
766
* or you'll crash when you try to use an integer as a string or something.
768
* To read any container type (array, struct, dict) you will need to recurse into the container with
769
* dbus_message_iter_recurse().
770
* If the container is an array of fixed-length values,
771
* you can get all the array elements at once with dbus_message_iter_get_fixed_array().
772
* Otherwise, you have to iterate over the container's contents one value at a time.
774
* All basic-typed values are guaranteed to fit in 8 bytes. So you can write code like this:
777
* dbus_uint64_t value;
779
* dbus_message_iter_get_basic (&read_iter, &value);
780
* type = dbus_message_iter_get_arg_type (&read_iter);
781
* dbus_message_iter_append_basic (&write_iter, type, &value);
785
* On some really obscure platforms dbus_uint64_t might not exist,
786
* if you need to worry about this you will know.
787
* dbus_uint64_t is just one example of a type that's large enough to hold any possible value,
788
* you could use a struct or char[8] instead if you like.
790
void ibus_message_iter_get_basic (IBusMessageIter *iter,
794
* ibus_message_iter_get:
795
* @iter: An IBusMessageIter.
796
* @type: The type of the value. Cannot be %NULL.
797
* @value: Result value stores here. Cannot be %NULL.
798
* @returns: %TRUE if succeed; %FALSE if insufficient memory.
800
* Gets an value from an IBusMessageIter, then move on to the next element.
803
gboolean ibus_message_iter_get (IBusMessageIter *iter,
808
* ibus_message_iter_next:
809
* @iter: An IBusMessageIter.
810
* @returns: %TRUE if the iterator moves forward successfully; %FALSE if next element does not exist.
812
* Moves the iterator to the next field, if any.
814
* If there's no next field, returns %FALSE. If the iterator moves forward, returns %TRUE.
816
gboolean ibus_message_iter_next (IBusMessageIter *iter);
819
* ibus_message_iter_has_next:
820
* @iter: An IBusMessageIter.
821
* @returns: %TRUE if next element exists; %FALSE otherwise.
823
* Checks if an iterator has any more fields.
825
gboolean ibus_message_iter_has_next (IBusMessageIter *iter);
828
* ibus_message_iter_open_container:
829
* @iter: An IBusMessageIter.
830
* @type: The type of the value.
831
* @contained_signature: The type of container contents.
832
* @sub: Sub-iterator to initialize.
833
* @returns: %TRUE if succeed; %FALSE if insufficient memory.
835
* Appends a container-typed value to the message;
836
* you are required to append the contents of the container using the returned sub-iterator,
837
* and then call dbus_message_iter_close_container().
839
* Container types are for example struct, variant, and array.
840
* For variants, the contained_signature should be the type of the single value inside the variant.
841
* For structs and dict entries, contained_signature should be %NULL;
842
* it will be set to whatever types you write into the struct.
843
* For arrays, contained_signature should be the type of the array elements.
845
gboolean ibus_message_iter_open_container
846
(IBusMessageIter *iter,
848
const gchar *contained_signature,
849
IBusMessageIter *sub);
852
* ibus_message_iter_close_container:
853
* @iter: An IBusMessageIter.
854
* @sub: Sub-iterator to close.
855
* @returns: %TRUE if succeed; %FALSE if insufficient memory.
857
* Closes a container-typed value appended to the message;
858
* may write out more information to the message known only after the entire container is written,
859
* and may free resources created by dbus_message_iter_open_container().
861
gboolean ibus_message_iter_close_container
862
(IBusMessageIter *iter,
863
IBusMessageIter *sub);
866
* ibus_message_iter_recurse:
867
* @iter: An IBusMessageIter.
868
* @type: The type of the value.
869
* @sub: Sub-iterator to initialize.
870
* @returns: %TRUE if succeed; %FALSE if insufficient memory.
872
* Recurses into a container value when reading values from a message,
873
* initializing a sub-iterator to use for traversing the child values of the container.
875
* Note that this recurses into a value, not a type, so you can only recurse if the value exists.
876
* The main implication of this is that if you have for example an empty array of array of int32,
877
* you can recurse into the outermost array, but it will have no values, so you won't be able to recurse further.
878
* There's no array of int32 to recurse into.
880
* If a container is an array of fixed-length types, it is much more efficient to use
881
* dbus_message_iter_get_fixed_array() to get the whole array in one shot,
882
* rather than individually walking over the array elements.
884
* Be sure you have somehow checked that dbus_message_iter_get_arg_type()
885
* matches the type you are expecting to recurse into.
886
* Results of this function are undefined if there is no container to recurse into at the current iterator position.
888
gboolean ibus_message_iter_recurse (IBusMessageIter *iter,
890
IBusMessageIter *sub);
893
* ibus_message_iter_get_arg_type:
894
* @iter: An IBusMessageIter.
895
* @returns: The argument type.
897
* Returns the argument type of the argument that the message iterator points to.
899
* If the iterator is at the end of the message, returns %DBUS_TYPE_INVALID.
900
* You can thus write a loop as follows:
903
* dbus_message_iter_init (&iter);
904
* while ((current_type = dbus_message_iter_get_arg_type (&iter)) != DBUS_TYPE_INVALID)
905
* dbus_message_iter_next (&iter);
909
GType ibus_message_iter_get_arg_type (IBusMessageIter *iter);
912
* ibus_message_iter_get_element_type:
913
* @iter: An IBusMessageIter.
914
* @returns: The argument type.
916
* Returns the element type of the array that the message iterator points to.
917
* Note that you need to check that the iterator points to an array prior to using this function.
919
GType ibus_message_iter_get_element_type
920
(IBusMessageIter *iter);
923
* ibus_message_to_string:
924
* @message: An IBusMessage.
925
* @returns: A string which shows the information of the message.
927
* Produces a pretty formatted string which show the information of the IBusMessage.
928
* This string is suitable for debugging information print out.
930
* Free the string by g_free() after use.
932
gchar *ibus_message_to_string (IBusMessage *message);
added
removed
src/ibusmessage.h
