~ubuntu-branches/ubuntu/vivid/glib2.0/vivid-proposed

lower-case form. The CamelCase form is used for the <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType">GType</a> and

struct name, while lower-case form is used in function names. The

lower-case form is calculated by converting from CamelCase to

lower-case and inserting underscores at word boundaries (using

267

268

269

When generating C code, this annotation is used to add

270

<a href="../glib/glib-Miscellaneous-Macros.html#G-GNUC-DEPRECATED:CAPS">G_GNUC_DEPRECATED</a> to generated functions for the element.

270

<a href="http://library.gnome.org/devel/glib/unstable/glib-Miscellaneous-Macros.html#G-GNUC-DEPRECATED:CAPS">G_GNUC_DEPRECATED</a> to generated functions for the element.

271

272

273

When generating Docbook XML, a deprecation warning will

330

<tr>

331

<td><code class="literal">org.gtk.GDBus.C.ForceGVariant</code></td>

332

<td>

333

If set to a non-empty string, a <a href="../glib/glib-GVariant.html#GVariant">GVariant</a> instance will

333

If set to a non-empty string, a <a href="http://library.gnome.org/devel/glib/unstable/glib-GVariant.html#GVariant">GVariant</a> instance will

334

be used instead of the natural C type. This annotation can

335

be used on any <code class="literal"><arg></code> and

336

<code class="literal"><property></code> element.

531

two files called

532

<code class="filename">myapp-generated.[ch]</code> are

533

generated. The files provide an abstract

534

<a href="../gobject/gobject-Type-Information.html#GTypeInterface">GTypeInterface</a>-derived type called

534

<a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GTypeInterface">GTypeInterface</a>-derived type called

535

MyAppFrobber as well as two instantiable types with

536

the same name but suffixed with Proxy and

537

Skeleton. The generated file, roughly, contains the

656

const gchar* const *messages);

657

658

/* Signal handler for the ::handle-hello-world signal */

659

<a href="../glib/glib-Basic-Types.html#gboolean">gboolean</a> (*handle_hello_world) (MyAppFrobber *proxy,

659

<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean">gboolean</a> (*handle_hello_world) (MyAppFrobber *proxy,

660

GDBusMethodInvocation *invocation,

661

const gchar *greeting);

662

} MyAppFrobberIface;

742

743

744

Thus, for every D-Bus method, there will be three C functions for

745

calling the method, one <a href="../gobject/gobject-The-Base-Object-Type.html#GObject">GObject</a> signal for handling an incoming

745

calling the method, one <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a> signal for handling an incoming

746

call and one C function for completing an incoming call. For every

747

D-Bus signal, there's one <a href="../gobject/gobject-The-Base-Object-Type.html#GObject">GObject</a> signal and one C function for

747

D-Bus signal, there's one <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a> signal and one C function for

748

emitting it. For every D-Bus property, two C functions are

749

generated (one setter, one getter) and one <a href="../gobject/gobject-The-Base-Object-Type.html#GObject">GObject</a> property. The

749

generated (one setter, one getter) and one <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a> property. The

750

following table summarizes the generated facilities and where they

751

are applicable:

752

782

<tr>

783

<td>Properties (Reading)</td>

784

<td>Use <code class="function"><code class="function">m_a_f_get_verbose()</code></code> or <code>:verbose</code>.</td>

785

<td>Implement <a href="../gobject/gobject-The-Base-Object-Type.html#GObject">GObject</a>'s <code class="function"><code class="function">get_property()</code></code> vfunc.</td>

785

<td>Implement <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a>'s <code class="function"><code class="function">get_property()</code></code> vfunc.</td>

786

</tr>

787

<tr>

788

<td>Properties (writing)</td>

789

<td>Use <code class="function"><code class="function">m_a_f_set_verbose()</code></code> or <code>:verbose</code>.</td>

790

791

</tr>

792

</tbody>

793

</table></div>

826

NULL, /* GCancellable* */

827

&error);

828

/* do stuff with proxy */

829

<a href="../gobject/gobject-The-Base-Object-Type.html#g-object-unref">g_object_unref</a> (proxy);</pre></td>

829

<a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#g-object-unref">g_object_unref</a> (proxy);</pre></td>

830

</tr>

831

</tbody>

832

</table>

846

<code>:verbose</code> or the

847

<code class="function"><code class="function">my_app_get_verbose()</code></code> and

848

<code class="function"><code class="function">my_app_set_verbose()</code></code> methods. Use the

849

standard <a href="../gobject/gobject-The-Base-Object-Type.html#GObject-notify">“notify”</a> signal to listen to property changes.

849

standard <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject-notify">“notify”</a> signal to listen to property changes.

850

851

852

Note that all property access is via <a class="link" href="GDBusProxy.html" title="GDBusProxy">GDBusProxy</a>'s

863

<a name="id-1.4.24.7.10.11"></a><h3>Server-side usage</h3>

864

865

The generated MyAppFrobber interface is designed so

866

it is easy to implement it in a <a href="../gobject/gobject-The-Base-Object-Type.html#GObject">GObject</a>

866

it is easy to implement it in a <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a>

867

subclass. For example, to handle

868

<code class="function"><code class="function">HelloWorld()</code></code> method invocations, set the

869

vfunc for <code class="function"><code class="function">handle_hello_hello_world()</code></code> in the

870

MyAppFrobberIface structure. Similary, to handle

871

the <code>net.Corp.MyApp.Frobber:Verbose</code>

872

property override the <code>:verbose</code> <a href="../gobject/gobject-The-Base-Object-Type.html#GObject">GObject</a>

872

property override the <code>:verbose</code> <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a>

873

property from the subclass. To emit a signal, use

874

e.g. <code class="function"><code class="function">my_app_emit_signal()</code></code> or

875

<a href="../gobject/gobject-Signals.html#g-signal-emit-by-name"><code class="function">g_signal_emit_by_name()</code></a>.

875

<a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-emit-by-name"><code class="function">g_signal_emit_by_name()</code></a>.

876

877

878

Instead of subclassing, it is often easier to use the generated

879

MyAppFrobberSkeleton subclass. To handle incoming

880

method calls, use <code class="function"><a href="../gobject/gobject-Signals.html#g-signal-connect"><code class="function">g_signal_connect()</code></a></code> with

880

method calls, use <code class="function"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-connect"><code class="function">g_signal_connect()</code></a></code> with

881

the <code class="function">::handle-*</code> signals and instead of

882

overriding <a href="../gobject/gobject-The-Base-Object-Type.html#GObject">GObject</a>'s

882

overriding <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a>'s

883

<code class="function"><code class="function">get_property()</code></code> and

884

<code class="function"><code class="function">set_property()</code></code> vfuncs, use

885

<a href="../gobject/gobject-The-Base-Object-Type.html#g-object-get"><code class="function">g_object_get()</code></a> and

886

<a href="../gobject/gobject-The-Base-Object-Type.html#g-object-set"><code class="function">g_object_set()</code></a> or the generated property

885

<a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#g-object-get"><code class="function">g_object_get()</code></a> and

886

<a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#g-object-set"><code class="function">g_object_set()</code></a> or the generated property

887

getters and setters (the generated class has an internal

888

property bag implementation).

889

941

const gchar *greeting,

942

gpointer user_data)

943

{

944

if (<a href="../glib/glib-String-Utility-Functions.html#g-strcmp0">g_strcmp0</a> (greeting, "Boo") != 0)

944

if (<a href="http://library.gnome.org/devel/glib/unstable/glib-String-Utility-Functions.html#g-strcmp0">g_strcmp0</a> (greeting, "Boo") != 0)

945

{

946

gchar *response;

947

response = <a href="../glib/glib-String-Utility-Functions.html#g-strdup-printf">g_strdup_printf</a> ("Word! You said `%s'.", greeting);

947

response = <a href="http://library.gnome.org/devel/glib/unstable/glib-String-Utility-Functions.html#g-strdup-printf">g_strdup_printf</a> ("Word! You said `%s'.", greeting);

948

my_app_complete_hello_world (interface, invocation, response);

949

<a href="../glib/glib-Memory-Allocation.html#g-free">g_free</a> (response);

949

<a href="http://library.gnome.org/devel/glib/unstable/glib-Memory-Allocation.html#g-free">g_free</a> (response);

950

}

951

else

952

{

964

interface = my_app_frobber_skeleton_new ();

965

my_app_frobber_set_verbose (interface, TRUE);

966

967

<a href="../gobject/gobject-Signals.html#g-signal-connect">g_signal_connect</a> (interface,

967

<a href="http://library.gnome.org/devel/gobject/unstable/gobject-Signals.html#g-signal-connect">g_signal_connect</a> (interface,

968

"handle-hello-world",

969

<a href="../gobject/gobject-Closures.html#G-CALLBACK:CAPS">G_CALLBACK</a> (on_handle_hello_world),

969

<a href="http://library.gnome.org/devel/gobject/unstable/gobject-Closures.html#G-CALLBACK:CAPS">G_CALLBACK</a> (on_handle_hello_world),

970

some_user_data);

971

972

[...]

986

987

988

To facilitate atomic changesets (multiple properties changing at

989

the same time), <a href="../gobject/gobject-The-Base-Object-Type.html#GObject-notify">“notify”</a> signals are queued up when

989

the same time), <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject-notify">“notify”</a> signals are queued up when

990

received. The queue is drained in an idle handler (which is called from the

991

<a href="../glib/glib-The-Main-Event-Loop.html#g-main-context-push-thread-default">thread-default main loop</a>

991

<a href="http://library.gnome.org/devel/glib/unstable/glib-The-Main-Event-Loop.html#g-main-context-push-thread-default">thread-default main loop</a>

992

of the thread where the skeleton object was

993

contructed) and will cause emissions of the <a class="ulink" href="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties" target="_top">org.freedesktop.DBus.Properties::PropertiesChanged</a>

994

signal with all the properties that have changed. Use

995

<a class="link" href="GDBusInterfaceSkeleton.html#g-dbus-interface-skeleton-flush" title="g_dbus_interface_skeleton_flush ()"><code class="function">g_dbus_interface_skeleton_flush()</code></a> or

996

<a class="link" href="GDBusObjectSkeleton.html#g-dbus-object-skeleton-flush" title="g_dbus_object_skeleton_flush ()"><code class="function">g_dbus_object_skeleton_flush()</code></a> to empty the queue

997

immediately. Use <a href="../gobject/gobject-The-Base-Object-Type.html#g-object-freeze-notify"><code class="function">g_object_freeze_notify()</code></a> and

998

<a href="../gobject/gobject-The-Base-Object-Type.html#g-object-thaw-notify"><code class="function">g_object_thaw_notify()</code></a> for atomic changesets if on a different

997

immediately. Use <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#g-object-freeze-notify"><code class="function">g_object_freeze_notify()</code></a> and

998

<a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#g-object-thaw-notify"><code class="function">g_object_thaw_notify()</code></a> for atomic changesets if on a different

999

thread.

1000

1001

</div>

1005

1006

Scalar types

1007

(type-strings

1008

<a href="../glib/glib-GVariantType.html#G-VARIANT-TYPE-BOOLEAN:CAPS">'b'</a>,

1009

<a href="../glib/glib-GVariantType.html#G-VARIANT-TYPE-BYTE:CAPS">'y'</a>,

1010

<a href="../glib/glib-GVariantType.html#G-VARIANT-TYPE-INT16:CAPS">'n'</a>,

1011

<a href="../glib/glib-GVariantType.html#G-VARIANT-TYPE-UINT16:CAPS">'q'</a>,

1012

<a href="../glib/glib-GVariantType.html#G-VARIANT-TYPE-INT32:CAPS">'i'</a>,

1013

<a href="../glib/glib-GVariantType.html#G-VARIANT-TYPE-UINT32:CAPS">'u'</a>,

1014

<a href="../glib/glib-GVariantType.html#G-VARIANT-TYPE-INT64:CAPS">'x'</a>,

1015

<a href="../glib/glib-GVariantType.html#G-VARIANT-TYPE-UINT64:CAPS">'t'</a> and

1016

<a href="../glib/glib-GVariantType.html#G-VARIANT-TYPE-DOUBLE:CAPS">'d'</a>)

1008

<a href="http://library.gnome.org/devel/glib/unstable/glib-GVariantType.html#G-VARIANT-TYPE-BOOLEAN:CAPS">'b'</a>,

1009

<a href="http://library.gnome.org/devel/glib/unstable/glib-GVariantType.html#G-VARIANT-TYPE-BYTE:CAPS">'y'</a>,

1010

<a href="http://library.gnome.org/devel/glib/unstable/glib-GVariantType.html#G-VARIANT-TYPE-INT16:CAPS">'n'</a>,

1011

<a href="http://library.gnome.org/devel/glib/unstable/glib-GVariantType.html#G-VARIANT-TYPE-UINT16:CAPS">'q'</a>,

1012

<a href="http://library.gnome.org/devel/glib/unstable/glib-GVariantType.html#G-VARIANT-TYPE-INT32:CAPS">'i'</a>,

1013

<a href="http://library.gnome.org/devel/glib/unstable/glib-GVariantType.html#G-VARIANT-TYPE-UINT32:CAPS">'u'</a>,

1014

<a href="http://library.gnome.org/devel/glib/unstable/glib-GVariantType.html#G-VARIANT-TYPE-INT64:CAPS">'x'</a>,

1015

<a href="http://library.gnome.org/devel/glib/unstable/glib-GVariantType.html#G-VARIANT-TYPE-UINT64:CAPS">'t'</a> and

1016

<a href="http://library.gnome.org/devel/glib/unstable/glib-GVariantType.html#G-VARIANT-TYPE-DOUBLE:CAPS">'d'</a>)

1017

1018

strings (type-strings

1019

<a href="../glib/glib-GVariantType.html#G-VARIANT-TYPE-STRING:CAPS">'s'</a>,

1020

<a href="../glib/glib-GVariantType.html#G-VARIANT-TYPE-BYTESTRING:CAPS">'ay'</a>,

1021

<a href="../glib/glib-GVariantType.html#G-VARIANT-TYPE-OBJECT-PATH:CAPS">'o'</a> and

1022

<a href="../glib/glib-GVariantType.html#G-VARIANT-TYPE-SIGNATURE:CAPS">'g'</a>) and

1019

<a href="http://library.gnome.org/devel/glib/unstable/glib-GVariantType.html#G-VARIANT-TYPE-STRING:CAPS">'s'</a>,

1020

<a href="http://library.gnome.org/devel/glib/unstable/glib-GVariantType.html#G-VARIANT-TYPE-BYTESTRING:CAPS">'ay'</a>,

1021

<a href="http://library.gnome.org/devel/glib/unstable/glib-GVariantType.html#G-VARIANT-TYPE-OBJECT-PATH:CAPS">'o'</a> and

1022

<a href="http://library.gnome.org/devel/glib/unstable/glib-GVariantType.html#G-VARIANT-TYPE-SIGNATURE:CAPS">'g'</a>) and

1023

arrays of string (type-strings

1024

<a href="../glib/glib-GVariantType.html#G-VARIANT-TYPE-STRING-ARRAY:CAPS">'as'</a>,

1025

<a href="../glib/glib-GVariantType.html#G-VARIANT-TYPE-OBJECT-PATH-ARRAY:CAPS">'ao'</a> and

1026

<a href="../glib/glib-GVariantType.html#G-VARIANT-TYPE-BYTESTRING-ARRAY:CAPS">'aay'</a>)

1024

<a href="http://library.gnome.org/devel/glib/unstable/glib-GVariantType.html#G-VARIANT-TYPE-STRING-ARRAY:CAPS">'as'</a>,

1025

<a href="http://library.gnome.org/devel/glib/unstable/glib-GVariantType.html#G-VARIANT-TYPE-OBJECT-PATH-ARRAY:CAPS">'ao'</a> and

1026

<a href="http://library.gnome.org/devel/glib/unstable/glib-GVariantType.html#G-VARIANT-TYPE-BYTESTRING-ARRAY:CAPS">'aay'</a>)

1027

are mapped to the natural types,

1028

e.g. <a href="../glib/glib-Basic-Types.html#gboolean">gboolean</a>, <a href="../glib/glib-Basic-Types.html#gdouble">gdouble</a>, <a href="../glib/glib-Basic-Types.html#gint">gint</a>, <a href="../gobject/gobject-Standard-Parameter-and-Value-Types.html#gchararray">gchar*</a>,

1029

<a href="../gobject/gobject-Boxed-Types.html#GStrv">gchar**</a> and

1030

so on. Everything else is mapped to the <a href="../glib/glib-GVariant.html#GVariant">GVariant</a>

1028

e.g. <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean">gboolean</a>, <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gdouble">gdouble</a>, <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gint">gint</a>, <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Standard-Parameter-and-Value-Types.html#gchararray">gchar*</a>,

1029

<a href="http://library.gnome.org/devel/gobject/unstable/gobject-Boxed-Types.html#GStrv">gchar**</a> and

1030

so on. Everything else is mapped to the <a href="http://library.gnome.org/devel/glib/unstable/glib-GVariant.html#GVariant">GVariant</a>

1031

type.

1032

1033

1034

This automatic mapping can be turned off by using the annotation

1035

<code class="literal">org.gtk.GDBus.C.ForceGVariant</code> - if used then a

1036

<a href="../glib/glib-GVariant.html#GVariant">GVariant</a> is always exchanged instead of the

1036

<a href="http://library.gnome.org/devel/glib/unstable/glib-GVariant.html#GVariant">GVariant</a> is always exchanged instead of the

1037

corresponding native C type. This annotation may be convenient to

1038

use when using

1039

bytestrings (type-string <a href="../glib/glib-GVariantType.html#G-VARIANT-TYPE-BYTESTRING:CAPS">'ay'</a>)

1039

bytestrings (type-string <a href="http://library.gnome.org/devel/glib/unstable/glib-GVariantType.html#G-VARIANT-TYPE-BYTESTRING:CAPS">'ay'</a>)

1040

for data that could have embedded NUL bytes.

1041

1042

</div>

1050

class structures will be preserved as well.

1051

1052

1053

The ABI of the generated <a href="../gobject/gobject-Type-Information.html#GType">GType</a>s will be preserved only if

1053

The ABI of the generated <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GType">GType</a>s will be preserved only if

1054

the <code class="literal">org.gtk.GDBus.Since</code> annotation is used

1055

judiciously — this is because the VTable for the <a href="/home/desrt/.cache/jhbuild/install/share/gtk-doc/html/gobject/GTypeModule.html">GInterface</a>

1055

judiciously — this is because the VTable for the <a href="http://library.gnome.org/devel/gobject/unstable/GTypeModule.html">GInterface</a>

1056

relies on functions pointers for signal handlers. Specifically, if

1057

a D-Bus method, property or signal or is added to a D-Bus

1058

interface, then ABI of the generated <a href="/home/desrt/.cache/jhbuild/install/share/gtk-doc/html/gobject/GTypeModule.html">GInterface</a> type is preserved

1058

interface, then ABI of the generated <a href="http://library.gnome.org/devel/gobject/unstable/GTypeModule.html">GInterface</a> type is preserved

1059

if, and only if, each added method, property signal is annotated

1060

with they <code class="literal">org.gtk.GDBus.Since</code> annotation using

1061

a greater version number than previous versions.

Older »