[telepathy-doc/master] More on glib types
Davyd Madeley
davyd at madeley.id.au
Tue Mar 31 23:31:23 PDT 2009
---
docs/book/.gitignore | 1 +
docs/book/C/basics.xml | 90 +++++-
.../C/figures/src/telepathy-glib-type-unpacked.svg | 353 ++++++++++++++++++++
docs/book/Makefile.am | 3 +-
4 files changed, 442 insertions(+), 5 deletions(-)
create mode 100644 docs/book/C/figures/src/telepathy-glib-type-unpacked.svg
diff --git a/docs/book/.gitignore b/docs/book/.gitignore
index 413055b..1a04288 100644
--- a/docs/book/.gitignore
+++ b/docs/book/.gitignore
@@ -5,3 +5,4 @@ C/figures/telepathy-architecture-overview.png
C/figures/bus-conceptual.png
C/figures/bus-hierarchy-conceptual.png
C/figures/contactlist-flowchart.png
+C/figures/telepathy-glib-type-unpacked.png
diff --git a/docs/book/C/basics.xml b/docs/book/C/basics.xml
index fb7ffc7..d43b08c 100644
--- a/docs/book/C/basics.xml
+++ b/docs/book/C/basics.xml
@@ -1045,11 +1045,93 @@ get_channels_cb (TpProxy *proxy,
</para>
<para>
- To check that a given <classname>GValue</classname> is off the
- suspected type use the macro <function>G_VALUE_HOLDS</function>.
- You can also print its type for debugging with the macro
- <function>G_VALUE_TYPE_NAME</function>.
+ To check that a given <classname>GValue</classname> is of the
+ correct type, use the macro <function>G_VALUE_HOLDS</function>. To
+ retrieve the type of a <classname>GValue</classname> use the macro
+ <function>G_VALUE_TYPE</function>.
</para>
+
+ <para>
+ Decoding the contents of the GValue can be done either from the
+ <ulink url="&url_telepathy_glib_base;telepathy-glib-gtypes.html">manual</ulink>
+ or from the D-Bus type signature. For example the property
+ <property>Requests.Channels</property> is of the type
+ <type>Channel_Details_List</type> (<literal>a(oa{sv})</literal>). From
+ the manual, this is a <classname>GPtrArray</classname> of
+ <type>TP_STRUCT_TYPE_CHANNEL_DETAILS</type>, which in turn is a
+ <classname>GValueArray</classname> containing a object path and an
+ <link linkend="sect.basics.language-bindings.telepathy-glib.maps">a{sv}
+ map</link> (hashtable). The complete unpacking is shown in
+ <xref linkend="ex.basics.language-bindings.telepathy-glib.types"/>.
+ </para>
+
+ <para>
+ More generally, the structure of the type can be determined from its
+ D-Bus type signature by following several rules:
+ </para>
+ <itemizedlist>
+ <listitem><para>
+ Arrays (e.g. <literal>as</literal>) are stored as a
+ <classname>GPtrArray</classname>;
+ </para></listitem>
+ <listitem><para>
+ Structures (e.g. <literal>(oa{sv})</literal>) are stored as a
+ <classname>GValueArray</classname> where each member of the
+ structure is a GValue in the array in the respective order.
+ </para></listitem>
+ <listitem><para>
+ Maps (e.g. <literal>a{sv}</literal>) are stored as a
+ <classname>GHashTable</classname>.
+ </para></listitem>
+ <listitem><para>
+ Object paths (<literal>o</literal>) are stored as a boxed
+ <classname>GValue</classname>s of type
+ <type>DBUS_TYPE_G_OBJECT_PATH</type>.
+ </para></listitem>
+ <listitem><para>
+ Variant types (<literal>v</literal>) are stored as
+ <classname>GValue</classname>s of type specified by the spec.
+ </para></listitem>
+ </itemizedlist>
+
+ <para>
+ For example, the D-Bus type <literal>a{sa(usuu)}</literal> is a
+ <classname>GHashTable</classname> of string keys (<type>char *</type>)
+ to <classname>GPtrArray</classname>s containing
+ <classname>GValueArray</classname>s. This is shown graphically in
+ <xref linkend="fig.basics.language-bindings.telepathy-glib.types.unpacked"/>.
+ </para>
+
+ <figure id="fig.basics.language-bindings.telepathy-glib.types.unpacked">
+ <title>Expanded Type for a{sa(usuu)}</title>
+ <mediaobject><imageobject>
+ <imagedata fileref="figures/telepathy-glib-type-unpacked.png"
+ format="PNG" />
+ </imageobject></mediaobject>
+ </figure>
+
+ <example id="ex.basics.language-bindings.telepathy-glib.types">
+ <title>Decoding a GValue containing a Channel_Details_List</title>
+ <programlisting>
+<![CDATA[g_return_if_fail (G_VALUE_HOLDS (value, TP_ARRAY_TYPE_CHANNEL_DETAILS_LIST));
+
+GPtrArray *channels = g_value_get_boxed (value);
+
+int i;
+for (i = 0; i < channels->len; i++)
+{
+ GValueArray *channel = g_ptr_array_index (channels, i);
+
+ char *object_path = g_value_get_boxed (g_value_array_get_nth (channel, 0));
+ GHashTable *map = g_value_get_boxed (g_value_array_get_nth (channel, 1));
+
+ const char *type = tp_asv_get_string (map, TP_IFACE_CHANNEL ".ChannelType");
+
+ g_print ("Path: %s\n", object_path);
+ g_print ("Type: %s\n", type);
+}]]></programlisting>
+ </example>
+
</sect3>
<sect3 id="sect.basics.language-bindings.telepathy-glib.maps">
diff --git a/docs/book/C/figures/src/telepathy-glib-type-unpacked.svg b/docs/book/C/figures/src/telepathy-glib-type-unpacked.svg
new file mode 100644
index 0000000..0cccc5f
--- /dev/null
+++ b/docs/book/C/figures/src/telepathy-glib-type-unpacked.svg
@@ -0,0 +1,353 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="340"
+ height="380"
+ id="svg2"
+ sodipodi:version="0.32"
+ inkscape:version="0.46"
+ sodipodi:docname="telepathy-glib-type-unpacked.svg"
+ inkscape:output_extension="org.inkscape.output.svg.inkscape"
+ version="1.0">
+ <defs
+ id="defs4">
+ <marker
+ inkscape:stockid="Arrow1Send"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Send"
+ style="overflow:visible">
+ <path
+ id="path3375"
+ d="M 0,0 L 5,-5 L -12.5,0 L 5,5 L 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none"
+ transform="matrix(-0.2,0,0,-0.2,-1.2,0)" />
+ </marker>
+ <marker
+ inkscape:stockid="Arrow1Mend"
+ orient="auto"
+ refY="0"
+ refX="0"
+ id="Arrow1Mend"
+ style="overflow:visible">
+ <path
+ id="path3369"
+ d="M 0,0 L 5,-5 L -12.5,0 L 5,5 L 0,0 z"
+ style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none"
+ transform="matrix(-0.4,0,0,-0.4,-4,0)" />
+ </marker>
+ <inkscape:perspective
+ sodipodi:type="inkscape:persp3d"
+ inkscape:vp_x="0 : 526.18109 : 1"
+ inkscape:vp_y="0 : 1000 : 0"
+ inkscape:vp_z="744.09448 : 526.18109 : 1"
+ inkscape:persp3d-origin="372.04724 : 350.78739 : 1"
+ id="perspective10" />
+ </defs>
+ <sodipodi:namedview
+ id="base"
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1.0"
+ gridtolerance="10000"
+ guidetolerance="10"
+ objecttolerance="10"
+ inkscape:pageopacity="0.0"
+ inkscape:pageshadow="2"
+ inkscape:zoom="1"
+ inkscape:cx="201.5"
+ inkscape:cy="240"
+ inkscape:document-units="px"
+ inkscape:current-layer="layer1"
+ showgrid="false"
+ inkscape:window-width="1600"
+ inkscape:window-height="1129"
+ inkscape:window-x="1280"
+ inkscape:window-y="25" />
+ <metadata
+ id="metadata7">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <g
+ inkscape:label="Layer 1"
+ inkscape:groupmode="layer"
+ id="layer1"
+ transform="translate(-25.125,-589.48718)">
+ <g
+ id="g4680"
+ transform="translate(2,4.2499974)">
+ <rect
+ ry="10"
+ rx="10"
+ y="591.36218"
+ x="27"
+ height="368"
+ width="331"
+ id="rect2383"
+ style="opacity:1;fill:none;fill-opacity:1;stroke:#4e9a06;stroke-width:3.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
+ <text
+ id="text3155"
+ y="616.36218"
+ x="39"
+ style="font-size:18px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:start;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1pt;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Sans;-inkscape-font-specification:Sans Bold"
+ xml:space="preserve"><tspan
+ y="616.36218"
+ x="39"
+ id="tspan3157"
+ sodipodi:role="line">GHashTable</tspan></text>
+ <g
+ transform="translate(-3,-90)"
+ id="g3165">
+ <rect
+ style="font-weight:bold;opacity:1;fill:none;fill-opacity:1;stroke:#204a87;stroke-width:3.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;-inkscape-font-specification:Sans Bold"
+ id="rect3159"
+ width="72"
+ height="28"
+ x="48"
+ y="732.36218"
+ rx="5"
+ ry="5" />
+ <text
+ xml:space="preserve"
+ style="font-size:18px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1pt;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Sans;-inkscape-font-specification:Sans Bold"
+ x="83.797852"
+ y="753.07263"
+ id="text3161"><tspan
+ sodipodi:role="line"
+ id="tspan3163"
+ x="83.797852"
+ y="753.07263">char *</tspan></text>
+ </g>
+ <g
+ transform="translate(24,0)"
+ id="g3325">
+ <rect
+ style="opacity:1;fill:none;fill-opacity:1;stroke:#f57900;stroke-width:3.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+ id="rect3170"
+ width="172"
+ height="261"
+ x="148"
+ y="641.36218"
+ rx="5"
+ ry="5" />
+ <text
+ xml:space="preserve"
+ style="font-size:18px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:start;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1pt;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Sans;-inkscape-font-specification:Sans Bold"
+ x="154"
+ y="661.36218"
+ id="text3172"><tspan
+ sodipodi:role="line"
+ id="tspan3174"
+ x="154"
+ y="661.36218">GPtrArray</tspan></text>
+ <g
+ id="g3217"
+ transform="translate(-4,-4)">
+ <rect
+ ry="5"
+ rx="5"
+ y="675.36218"
+ x="163"
+ height="171"
+ width="150"
+ id="rect3176"
+ style="opacity:1;fill:none;fill-opacity:1;stroke:#5c3566;stroke-width:3.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
+ <text
+ id="text3178"
+ y="696.36218"
+ x="171"
+ style="font-size:18px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:start;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1pt;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Sans;-inkscape-font-specification:Sans Bold"
+ xml:space="preserve"><tspan
+ y="696.36218"
+ x="171"
+ id="tspan3180"
+ sodipodi:role="line">GValueArray</tspan></text>
+ <g
+ transform="translate(-46,-23.709839)"
+ id="g3188">
+ <rect
+ style="opacity:1;fill:none;fill-opacity:1;stroke:#cc0000;stroke-width:3.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+ id="rect3182"
+ width="79"
+ height="28"
+ x="222.17334"
+ y="730.65173"
+ rx="5"
+ ry="5" />
+ <text
+ xml:space="preserve"
+ style="font-size:18px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:start;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1pt;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Sans;-inkscape-font-specification:Sans Bold"
+ x="229"
+ y="751.36218"
+ id="text3184"><tspan
+ sodipodi:role="line"
+ id="tspan3186"
+ x="229"
+ y="751.36218">uint32</tspan></text>
+ </g>
+ <g
+ id="g3193"
+ transform="translate(-46,10.860107)">
+ <rect
+ ry="5"
+ rx="5"
+ y="730.65173"
+ x="222.17334"
+ height="28"
+ width="79"
+ id="rect3195"
+ style="opacity:1;fill:none;fill-opacity:1;stroke:#cc0000;stroke-width:3.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
+ <text
+ id="text3197"
+ y="751.36218"
+ x="229"
+ style="font-size:18px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:start;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1pt;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Sans;-inkscape-font-specification:Sans Bold"
+ xml:space="preserve"><tspan
+ y="751.36218"
+ x="229"
+ id="tspan3199"
+ sodipodi:role="line">uint32</tspan></text>
+ </g>
+ <g
+ id="g3201"
+ transform="translate(128.17334,43.719604)">
+ <rect
+ ry="5"
+ rx="5"
+ y="732.36218"
+ x="48"
+ height="28"
+ width="72"
+ id="rect3203"
+ style="font-weight:bold;opacity:1;fill:none;fill-opacity:1;stroke:#204a87;stroke-width:3.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;-inkscape-font-specification:Sans Bold" />
+ <text
+ id="text3205"
+ y="753.07263"
+ x="83.797852"
+ style="font-size:18px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1pt;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Sans;-inkscape-font-specification:Sans Bold"
+ xml:space="preserve"><tspan
+ y="753.07263"
+ x="83.797852"
+ id="tspan3207"
+ sodipodi:role="line">char *</tspan></text>
+ </g>
+ <g
+ transform="translate(-46,80)"
+ id="g3209">
+ <rect
+ style="opacity:1;fill:none;fill-opacity:1;stroke:#cc0000;stroke-width:3.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+ id="rect3211"
+ width="79"
+ height="28"
+ x="222.17334"
+ y="730.65173"
+ rx="5"
+ ry="5" />
+ <text
+ xml:space="preserve"
+ style="font-size:18px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:start;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1pt;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Sans;-inkscape-font-specification:Sans Bold"
+ x="229"
+ y="751.36218"
+ id="text3213"><tspan
+ sodipodi:role="line"
+ id="tspan3215"
+ x="229"
+ y="751.36218">uint32</tspan></text>
+ </g>
+ </g>
+ <g
+ id="g3298">
+ <path
+ sodipodi:nodetypes="cccccc"
+ id="rect3240"
+ d="M 159,889.3622 L 159,858.36218 C 159,855.59218 161.23,853.36218 164,853.36218 L 304,853.36218 C 306.77,853.36218 309,855.59218 309,858.36218 L 309,890.3622"
+ style="fill:none;fill-opacity:1;stroke:#5c3566;stroke-width:3.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dashoffset:0;stroke-opacity:1" />
+ <text
+ xml:space="preserve"
+ style="font-size:18px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:start;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1pt;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Sans;-inkscape-font-specification:Sans Bold"
+ x="167"
+ y="874.36218"
+ id="text3242"><tspan
+ sodipodi:role="line"
+ id="tspan3244"
+ x="167"
+ y="874.36218">GValueArray</tspan></text>
+ </g>
+ <rect
+ ry="5"
+ rx="5"
+ y="641.36218"
+ x="148"
+ height="261"
+ width="172"
+ id="rect3303"
+ style="opacity:1;fill:none;fill-opacity:1;stroke:#f57900;stroke-width:3.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
+ </g>
+ <g
+ transform="translate(24,-2.9999974)"
+ id="g3312">
+ <text
+ id="text3305"
+ y="933.36218"
+ x="154"
+ style="font-size:18px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:start;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1pt;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Sans;-inkscape-font-specification:Sans Bold"
+ xml:space="preserve"><tspan
+ y="933.36218"
+ x="154"
+ id="tspan3307"
+ sodipodi:role="line">GPtrArray</tspan></text>
+ <path
+ style="fill:none;fill-opacity:1;stroke:#f57900;stroke-width:3.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dashoffset:0;stroke-opacity:1"
+ d="M 148,947.3622 L 148,918.36218 C 148,915.59218 150.23,913.36218 153,913.36218 L 315,913.36218 C 317.77,913.36218 320,915.59218 320,918.36218 L 320,945.3622"
+ id="rect3309"
+ sodipodi:nodetypes="cccccc" />
+ </g>
+ <g
+ id="g3317"
+ transform="translate(-3,178)">
+ <rect
+ ry="5"
+ rx="5"
+ y="732.36218"
+ x="48"
+ height="28"
+ width="72"
+ id="rect3319"
+ style="font-weight:bold;opacity:1;fill:none;fill-opacity:1;stroke:#204a87;stroke-width:3.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;-inkscape-font-specification:Sans Bold" />
+ <text
+ id="text3321"
+ y="753.07263"
+ x="83.797852"
+ style="font-size:18px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1pt;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Sans;-inkscape-font-specification:Sans Bold"
+ xml:space="preserve"><tspan
+ y="753.07263"
+ x="83.797852"
+ id="tspan3323"
+ sodipodi:role="line">char *</tspan></text>
+ </g>
+ <path
+ id="path3355"
+ d="M 126,656.36218 L 159,656.36218"
+ style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:#000000;stroke-width:3.75;stroke-linecap:butt;stroke-linejoin:miter;marker-end:url(#Arrow1Send);stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
+ <path
+ style="fill:none;fill-opacity:0.75;fill-rule:evenodd;stroke:#000000;stroke-width:3.75;stroke-linecap:butt;stroke-linejoin:miter;marker-end:url(#Arrow1Send);stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+ d="M 126,924.36218 L 159,924.36218"
+ id="path4658" />
+ </g>
+ </g>
+</svg>
diff --git a/docs/book/Makefile.am b/docs/book/Makefile.am
index 220f6af..a3cc947 100644
--- a/docs/book/Makefile.am
+++ b/docs/book/Makefile.am
@@ -30,7 +30,8 @@ DOC_FIGURES_SRC = \
telepathy-architecture-overview.svg \
bus-conceptual.svg \
bus-hierarchy-conceptual.svg \
- contactlist-flowchart.svg
+ contactlist-flowchart.svg \
+ telepathy-glib-type-unpacked.svg
# The names of any pictures:
DOC_FIGURES =
--
1.5.6.5
More information about the telepathy-commits
mailing list