[Telepathy-commits] [telepathy-doc/master] Use <methodname> instead of <function> for D-Bus method names, as seen in Davyd's branch. Likewise, use <interfacename> (not <interface> which is a deprecated GUI tag) instead of <classname> for D-Bus interface names.
Murray Cumming
murrayc at murrayc.com
Tue Feb 3 03:21:50 PST 2009
---
ChangeLog | 85 ++++++++++++++++++++++++--------------------
docs/book/C/telepathy.xml | 52 ++++++++++++++--------------
2 files changed, 72 insertions(+), 65 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index cf99bfb..85eeae9 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,8 +1,15 @@
+2009-02-03 Murray Cumming <murrayc at openismus.com>
+
+ * Use <methodname> instead of <function> for D-Bus method names,
+ as seen in Davyd's branch.
+ Likewise, use <interfacename> (not <interface> which is a deprecated
+ GUI tag) instead of <classname> for D-Bus interface names.
+
2009-02-03 Davyd Madeley <davyd.madeley at collabora.co.uk>
* Added .gitignore files, cherry-pick -ed from Davyd's remote branch.
-2009-01-27 Murray Cumming <murrayc at murrayc.com>
+2009-01-27 Murray Cumming <murrayc at openismus.com>
* docs/examples/: Added basics_dbus_glib_signals/ and
basics_dbus_python_signals/
@@ -11,39 +18,39 @@
dbus-glib one doe not seem to work yet.
Entities: Corrected the base URL for the dbus-glib API reference.
-2009-01-27 Murray Cumming <murrayc at murrayc.com>
+2009-01-27 Murray Cumming <murrayc at openismus.com>
* docs/examples/:
* docs/book/C/telepathy.xml: Basics: Using D-Bus: Added sections with
examples of using D-Bus properties with dbus-glib and Python.
-2009-01-27 Murray Cumming <murrayc at murrayc.com>
+2009-01-27 Murray Cumming <murrayc at openismus.com>
* docs/book/C/telepathy.xml: Basics: Optional Interfaces: Mention how
to check with telepathy-glib. We need dbus-glib and Python examples
here too.
Connection: Added a Presence sub-section with the example.
-2009-01-26 Murray Cumming <murrayc at murrayc.com>
+2009-01-26 Murray Cumming <murrayc at openismus.com>
* docs/book/C/telepathy.xml: Basics: Optional Interfaces: Mention that
ConnectionManager and Channel also have optional interfaces (not just
Connection), and mention the new Interfaces property.
-2009-01-26 Murray Cumming <murrayc at murrayc.com>
+2009-01-26 Murray Cumming <murrayc at openismus.com>
* docs/book/C/telepathy.xml: Basics: API Conventions: Mention the
Request/Get distinction and link to the telepathy-glib conventions.
Removed the Asynchronous Calls section because we dealt with that here
and in the Using D-Bus section.
-2009-01-26 Murray Cumming <murrayc at murrayc.com>
+2009-01-26 Murray Cumming <murrayc at openismus.com>
* docs/book/C/telepathy.xml: Basics: Handles: Write this section.
Removed the main Handles chapter because a) It was planned to cover the
same stuff and b) It should be covered very early.
-2009-01-26 Murray Cumming <murrayc at murrayc.com>
+2009-01-26 Murray Cumming <murrayc at openismus.com>
* docs/book/C/telepathy.xml: Basics: D-Bus, telepathy-glib: Explicitly
point out that we are dealing with proxies, not the objects themselves.
@@ -54,18 +61,18 @@
Connection: Mention RequestConnection() and the telepathy-glib
equivalent.
-2009-01-23 Murray Cumming <murrayc at murrayc.com>
+2009-01-23 Murray Cumming <murrayc at openismus.com>
* docs/book/C/telepathy.xml: Basics: Correct the use of the indexterm
tags. Their contents are not displayed in the main text.
-2009-01-23 Murray Cumming <murrayc at murrayc.com>
+2009-01-23 Murray Cumming <murrayc at openismus.com>
* docs/book/C/telepathy.xml: Basics: telepathy-glib: Mention sync/async
prefixes. Mention generated/hand-coded prefixes. Mention
call_when_ready() functions.
-2009-01-23 Murray Cumming <murrayc at murrayc.com>
+2009-01-23 Murray Cumming <murrayc at openismus.com>
* docs/examples/basics_dbus_glib/main.c:
* docs/examples/basics_dbus_python/example.py: Call the D-Bus method
@@ -76,18 +83,18 @@
Added an Installation chapter.
Added an index and sprinkled some indexterm tags around to fill it.
-2009-01-22 Murray Cumming <murrayc at murrayc.com>
+2009-01-22 Murray Cumming <murrayc at openismus.com>
* docs/book/C/telepathy.xml: Basics: Add a Language Bindings sub-section
as a way to mention telepathy-glib, which we use (so far) for all our
examples.
-2009-01-22 Murray Cumming <murrayc at murrayc.com>
+2009-01-22 Murray Cumming <murrayc at openismus.com>
* docs/book/C/telepathy.xml: Basics: Move the boring stuff about
Introspect() into a notes section because it is too soon to get scary.
-2009-01-20 Murray Cumming <murrayc at murrayc.com>
+2009-01-20 Murray Cumming <murrayc at openismus.com>
* docs/book/C/telepathy.xml: Basics: Write some text about optional
interfaces. Added a Connection Managers section before it, so that we
@@ -97,7 +104,7 @@
* docs/book/C/figures/: Tried adding this again, adding a README because
git seems to ignore it if it is empty.
-2009-01-20 Murray Cumming <murrayc at murrayc.com>
+2009-01-20 Murray Cumming <murrayc at openismus.com>
* configure.ac:
* docs/examples/basics_dbus_python/Makefile.am:
@@ -108,7 +115,7 @@
* docs/book/insert-example-code.py: Read .py files as well as .h and .cc
files.
-2009-01-15 Murray Cumming <murrayc at murrayc.com>
+2009-01-15 Murray Cumming <murrayc at openismus.com>
* configure.ac:
* docs/examples/basics_dbus_glib/Makefile.am:
@@ -120,31 +127,31 @@
* docs/book/C/figures/: Added these directories to git. I forgot to do
that until now.
-2009-01-15 Murray Cumming <murrayc at murrayc.com>
+2009-01-15 Murray Cumming <murrayc at openismus.com>
* docs/book/C/telepathy.xml: Add a small part of the introduction.
Add some sect structure.
-2009-01-16 Murray Cumming <murrayc at murrayc.com>
+2009-01-16 Murray Cumming <murrayc at openismus.com>
* docs/examples/send_message/main.c: on_get_contacts_by_id(): Ref the
TpContact so we can use it later, avoiding the crash when calling
tp_contact_get_handle().
-2009-01-12 Murray Cumming <murrayc at murrayc.com>
+2009-01-12 Murray Cumming <murrayc at openismus.com>
* docs/examples/send_message/main.c: Set the TargetHandleType too,
though this then crashes:
https://bugs.freedesktop.org/show_bug.cgi?id=19523
(The previous mentioned error was fixed by upgrading telepathy-gabble.)
-2008-01-05 Murray Cumming <murrayc at murrayc.com>
+2008-01-05 Murray Cumming <murrayc at openismus.com>
* docs/examples/list_contacts/main.c: Do not null-terminated the array
given to tp_connection_get_contacts_by_handle() though I still get an
error about handle #2 having no contact-id.
-2008-12-23 Murray Cumming <murrayc at murrayc.com>
+2008-12-23 Murray Cumming <murrayc at openismus.com>
* docs/book/insert_example_code.pl: Base this on the gtkmm-documentation
one rather than the flumotion-doc one (but using .c, not .cc), to
@@ -154,12 +161,12 @@
* doc/book/C/telepathy.xml: Add the examples at some vaguely
appropriate places, to check that this works.
-2008-12-23 Murray Cumming <murrayc at murrayc.com>
+2008-12-23 Murray Cumming <murrayc at openismus.com>
* docs/book/C/telepathy.xml: Define a base URL entity and use ulink to
link to types, interfaces and methods in the Telepathy specification.
-2008-12-22 Murray Cumming <murrayc at murrayc.com>
+2008-12-22 Murray Cumming <murrayc at openismus.com>
* docs/examples/send_message/main.c: Implement code to get a text
channel and send a message on it, though (like the list_contacts example)
@@ -167,55 +174,55 @@
tp_connection_get_contacts_by_id():
Connection manager :1.171 is broken: contact #2 in the GetContactAttributes result has no contact-id
-2008-12-15 Murray Cumming <murrayc at murrayc.com>
+2008-12-15 Murray Cumming <murrayc at openismus.com>
* configure.ac:
* docs/examples/Makefile.am
* docs/examples/send_message/main.c: Added the beginnings of a
an example to send a single message to a single specific contact.
-2008-12-15 Murray Cumming <murrayc at murrayc.com>
+2008-12-15 Murray Cumming <murrayc at openismus.com>
* docs/examples/set_presence/main.c:
* docs/examples/list_contacts/main.c: Use the *_call_when_ready()
functions instead of *_run_until_ready().
-2008-12-15 Murray Cumming <murrayc at murrayc.com>
+2008-12-15 Murray Cumming <murrayc at openismus.com>
* docs/examples/set_presence/main.c: Wait until the connection is
ready, so that setting of the presence can succeed.
-2008-12-15 Murray Cumming <murrayc at murrayc.com>
+2008-12-15 Murray Cumming <murrayc at openismus.com>
* configure.ac:
* docs/examples/Makefile.am
* docs/examples/set_presence/: Added a (nonworking) example of
setting presence, by copying the connect example and adding a call.
-2008-12-01 Murray Cumming <murrayc at murrayc.com>
+2008-12-01 Murray Cumming <murrayc at openismus.com>
* docs/examples/list_contacts/main.c: Use *_call_* functions instead
of *_run_* functions because everybody says they should never be used.
-2008-11-14 Murray Cumming <murrayc at murrayc.com>
+2008-11-14 Murray Cumming <murrayc at openismus.com>
* docs/examples/list_contacts/main.c: Get other contact features,
to show aliases and presence.
-2008-11-14 Murray Cumming <murrayc at murrayc.com>
+2008-11-14 Murray Cumming <murrayc at openismus.com>
* docs/examples/list_contacts/main.c: Examine the actual contacts
handles as before rather than the handle for the list of contacts.
This now works.
-2008-11-14 Murray Cumming <murrayc at murrayc.com>
+2008-11-14 Murray Cumming <murrayc at openismus.com>
* docs/examples/list_contacts/main.c: Use the new TpContacts API
instead, which seems much simpler than all that channel stuff.
However, this currently gives this GError:
handle 2 is not currently a valid contact handle (type 1)
-2008-11-13 Murray Cumming <murrayc at murrayc.com>
+2008-11-13 Murray Cumming <murrayc at openismus.com>
* docs/examples/list_contacts/main.c: Still trying to read the subscribed
contacts details. Without code changes, I now get a non-null list of
@@ -223,24 +230,24 @@
I upgrade to Ubuntu Intrepid. However, the attribures GHashTable is empty
for all contacts.
-2008-09-31 Murray Cumming <murrayc at murrayc.com>
+2008-09-31 Murray Cumming <murrayc at openismus.com>
* docs/examples/list_contacts/main.c: Trying to read the subscribed
contacts details.
-2008-09-31 Murray Cumming <murrayc at murrayc.com>
+2008-09-31 Murray Cumming <murrayc at openismus.com>
* docs/examples/list_contacts/main.c: Get the ContactsList interface,
though I do not yet know how to get details for each contact via
the handle.
-2008-09-31 Murray Cumming <murrayc at murrayc.com>
+2008-09-31 Murray Cumming <murrayc at openismus.com>
* docs/examples/connect/: Added this as a copy of the current
list_contacts. Connecting is complex enough that it deserves its own
example, before we make it more complex by adding other stuff.
-2008-09-26 Murray Cumming <murrayc at murrayc.com>
+2008-09-26 Murray Cumming <murrayc at openismus.com>
* docs/examples/list_contacts/main.c: printf the reason as text.
@@ -250,24 +257,24 @@
status has been received in the callback, so the connection actually
has a chance to happen.
-2008-09-26 Murray Cumming <murrayc at murrayc.com>
+2008-09-26 Murray Cumming <murrayc at openismus.com>
* docs/examples/list_contacts/main.c: Try to catch connection problems
via the status_changed callback.
-2008-09-26 Murray Cumming <murrayc at murrayc.com>
+2008-09-26 Murray Cumming <murrayc at openismus.com>
* docs/examples/list_contacts/: Added the beginnings of another example.
So far it just tries to create the connection so it can later get the
contacts from it.
-2008-09-26 Murray Cumming <murrayc at murrayc.com>
+2008-09-26 Murray Cumming <murrayc at openismus.com>
* docs/examples/list_all_protocols/main.c: Asynchronously introspect
the connection manager for the protocols information if necessary,
though this raises many more questions.
-2008-09-26 Murray Cumming <murrayc at murrayc.com>
+2008-09-26 Murray Cumming <murrayc at openismus.com>
* docs/examples/list_all_protocols/main.c: Check whether the protocol
information has been introspected. Added TODOs wondering how/when to
diff --git a/docs/book/C/telepathy.xml b/docs/book/C/telepathy.xml
index 05edfc6..ae2da7e 100644
--- a/docs/book/C/telepathy.xml
+++ b/docs/book/C/telepathy.xml
@@ -177,7 +177,7 @@ of the Telapathy specification.
<sect3 id="sect-basics-dbus-glib-properties">
<title>Using Properties</title>
- <para>D-Bus properties are available via an additional <ulink url="&url_dbus_spec_base;standard-interfaces-properties">org.freedesktop.DBus.Properties</ulink> interface on some objects, which provides <function>Get()</function>, <function>Set()</function> and <function>GetAll</function> methods. You can call these methods to get or set property values for the object's other interfaces.</para>
+ <para>D-Bus properties are available via an additional <ulink url="&url_dbus_spec_base;standard-interfaces-properties">org.freedesktop.DBus.Properties</ulink> interface on some objects, which provides <methodname>Get()</methodname>, <methodname>Set()</methodname> and <methodname>GetAll</methodname> methods. You can call these methods to get or set property values for the object's other interfaces.</para>
<para>As of this writing, telepathy-glib has no simple API for dealing with properties so you must call these functions directly. Therefore this example is therefore very similar to the <link linkend="sect-basics-dbus-glib-methods">Calling Methods</link> example.</para>
<para><ulink url="&url_examples_base;basics_dbus_glib_properties">Source Code</ulink></para>
</sect3>
@@ -202,14 +202,14 @@ of the Telapathy specification.
<sect3 id="sect-basics-dbus-python-properties">
<title>Using Properties</title>
- <para>D-Bus properties are available via an additional <ulink url="&url_dbus_spec_base;standard-interfaces-properties">org.freedesktop.DBus.Properties</ulink> interface on some objects, which provides <function>Get()</function>, <function>Set()</function> and <function>GetAll</function> methods. You can call these methods to get or set property values for the object's other interfaces.</para>
+ <para>D-Bus properties are available via an additional <ulink url="&url_dbus_spec_base;standard-interfaces-properties">org.freedesktop.DBus.Properties</ulink> interface on some objects, which provides <methodname>Get()</methodname>, <methodname>Set()</methodname> and <methodname>GetAll</methodname> methods. You can call these methods to get or set property values for the object's other interfaces.</para>
<para>As of this writing, Python has no simple API for dealing with D-Bus properties so you must call these functions directly. Therefore this example is therefore very similar to the <link linkend="sect-basics-dbus-python-methods">Calling Methods</link> example.</para>
<para><ulink url="&url_examples_base;basics_dbus_python_properties">Source Code</ulink></para>
</sect3>
<sect3 id="sect-basics-dbus-python-signals">
<title>Handling Signals</title>
- <para>D-Bus signal handlers may be specified in Python with the proxy object's <ulink url="&url_dbus_python_base;dbus.proxies.Interface-class.html#connect_to_signal"><function>connect_to_signal()</function></ulink> method. The specified callback function will then be called when the signal is emitted. This example connects to the "DeviceAdded" signal of the "org.freedesktop.Hal.Manager" interface so it can print a message to the terminal when, for instance, you plug in a USB stick.</para>
+ <para>D-Bus signal handlers may be specified in Python with the proxy object's <ulink url="&url_dbus_python_base;dbus.proxies.Interface-class.html#connect_to_signal"><methodname>connect_to_signal()</methodname></ulink> method. The specified callback function will then be called when the signal is emitted. This example connects to the "DeviceAdded" signal of the "org.freedesktop.Hal.Manager" interface so it can print a message to the terminal when, for instance, you plug in a USB stick.</para>
<para><ulink url="&url_examples_base;basics_dbus_python_signals">Source Code</ulink></para>
</sect3>
@@ -299,20 +299,20 @@ AC_SUBST(EXAMPLE_LIBS)
<sect1 id="sec-basics-connection-managers">
<title>Connection Managers</title>
<para>Support for the various communication protocols is provided by several <literal>Connection Managers</literal>. For instance, the <literal>telepathy-gabble</literal> Connection Manager provides support for the <acronym>XMPP</acronym> protocol, also known as <literal>Jabber</literal>.</para>
- <para>There is no central &app; D-Bus service. Instead there are several connection manager services, activated on demand, and each of these connection managers provide the same core set of D-Bus interfaces, such as <ulink url="&url_spec_base;Connection"><classname>Connection</classname></ulink> and <ulink url="&url_spec_base;Channel"><classname>Channel</classname></ulink>, allowing application code to be written generically for all connection managers.</para>
+ <para>There is no central &app; D-Bus service. Instead there are several connection manager services, activated on demand, and each of these connection managers provide the same core set of D-Bus interfaces, such as <ulink url="&url_spec_base;Connection"><interfacename>Connection</interfacename></ulink> and <ulink url="&url_spec_base;Channel"><interfacename>Channel</interfacename></ulink>, allowing application code to be written generically for all connection managers.</para>
</sect1>
<!-- TODO: Notes: The interfaces are often called their type, particularly for channels. Explain. -->
<sect1 id="sec-basics-optional-interfaces">
<title>Optional Interfaces</title>
<para>Although a core set of D-Bus interfaces is provided by all connection managers, some extra D-Bus interfaces are optional. For instance, some connection managers only provide extra interfaces when they discover that the remote server provides that optional functionality. Therefore, when using these interfaces, application code should first check that the interface is available, sometimes falling back to alternative interfaces.</para>
- <para>For instance, use the <classname>Connection</classname> interface's <ulink url="&url_spec_base;Connection.GetInterfaces"><function>GetInterfaces()</function></ulink> method. For <classname>ConnectionManager</classname>s and <classname>Channel</classname>s use their <property>Interfaces</property> D-Bus property. Eventually <classname>Connection</classname> will also have an <property>Interfaces</property> property, when its <function>GetInterfaces()</function> method will be deprecated.</para>
+ <para>For instance, use the <interfacename>Connection</interfacename> interface's <ulink url="&url_spec_base;Connection.GetInterfaces"><methodname>GetInterfaces()</methodname></ulink> method. For <interfacename>ConnectionManager</interfacename>s and <interfacename>Channel</interfacename>s use their <property>Interfaces</property> D-Bus property. Eventually <interfacename>Connection</interfacename> will also have an <property>Interfaces</property> property, when its <methodname>GetInterfaces()</methodname> method will be deprecated.</para>
<para>When using telepathy-glib, you can simply call the <ulink url="&url_telepathy_glib_base;proxy.html#tp-proxy-has-interface"><function>tp_proxy_has_interface()</function></ulink> function for <classname>TpConnectionManager</classname>, <classname>TpConnection</classname>, or <classname>TpChannel</classname>.</para>
<para>Actually, the core interfaces are only "recommended" by the Telepathy D-Bus specification so you should check before using any interface even if it is not commonly considered to be optional.</para>
<note>
- <para>Note that the <property>Interfaces</property> property (or the <ulink url="&url_spec_base;Connection.GetInterfaces"><function>Connection.GetInterfaces()</function></ulink> method) does more than the standard D-Bus <ulink url="&url_dbus_spec_base;standard-interfaces-introspectable"><function>Introspectable.Introspect()</function></ulink> method. The Telepathy-specific mechanism allows tools and language bindings to know about the possible availability of interfaces via <function>Introspect()</function> while providing an additional check that the interface is really supported for the particular connection manager with the particular remote server to which that connection manager is connected.
+ <para>Note that the <property>Interfaces</property> property (or the <ulink url="&url_spec_base;Connection.GetInterfaces"><methodname>Connection.GetInterfaces()</methodname></ulink> method) does more than the standard D-Bus <ulink url="&url_dbus_spec_base;standard-interfaces-introspectable"><methodname>Introspectable.Introspect()</methodname></ulink> method. The Telepathy-specific mechanism allows tools and language bindings to know about the possible availability of interfaces via <methodname>Introspect()</methodname> while providing an additional check that the interface is really supported for the particular connection manager with the particular remote server to which that connection manager is connected.
</para>
</note>
@@ -334,9 +334,9 @@ AC_SUBST(EXAMPLE_LIBS)
<sect2>
<title>Hold and Release</title>
- <para>When a Telepathy object has finished with a handle that number may be forgotten and even reused later as a handle for a completely different item. However, your application may wish to "hold" the handle for a longer time. To do so, you should call the Connection's <ulink url="&url_spec_base;Connection.HoldHandles"><function>HoldHandles()</function></ulink> method and call <ulink url="&url_spec_base;Connection.ReleaseHandles"><function>ReleaseHandles()</function></ulink> when you have finished with the handle. However, a single <function>ReleaseHandles()</function> call will release a handle regardless of how many times <function>HoldHandles()</function> has been called, so be careful not to call it while other code may be using the handle.</para>
+ <para>When a Telepathy object has finished with a handle that number may be forgotten and even reused later as a handle for a completely different item. However, your application may wish to "hold" the handle for a longer time. To do so, you should call the Connection's <ulink url="&url_spec_base;Connection.HoldHandles"><methodname>HoldHandles()</methodname></ulink> method and call <ulink url="&url_spec_base;Connection.ReleaseHandles"><methodname>ReleaseHandles()</methodname></ulink> when you have finished with the handle. However, a single <methodname>ReleaseHandles()</methodname> call will release a handle regardless of how many times <methodname>HoldHandles()</methodname> has been called, so be careful not to call it while other code may be using the handle.</para>
- <para>This is less necessary when using Telepathy <link linkend="sec-basics-language-bindings">language bindings</link>, such as telepathy-glib, because they may automatically hold and release handles for the lifetime of their objects, such as telepathy-glib's <classname>TpContact</classname> object. Additionally, telepathy-glib wraps the <function>HoldHandles()</function> and <function>ReleaseHandles()</function> D-Bus methods with the <ulink url="&url_telepathy_glib_base;connection.html#tp-connection-hold-handles"><function>tp_connection_hold_handles()</function></ulink> and <ulink url="&url_telepathy_glib_base;connection.html#tp-connection-unref-handles"><function>tp_connection_unref_handles()</function></ulink> functions which reference-count the client-side handle "hold", allowing you to match each <function>tp_connection_hold_handles()</function> call with a call to <function>tp_connection_release_handles()</function>.</para>
+ <para>This is less necessary when using Telepathy <link linkend="sec-basics-language-bindings">language bindings</link>, such as telepathy-glib, because they may automatically hold and release handles for the lifetime of their objects, such as telepathy-glib's <classname>TpContact</classname> object. Additionally, telepathy-glib wraps the <methodname>HoldHandles()</methodname> and <methodname>ReleaseHandles()</methodname> D-Bus methods with the <ulink url="&url_telepathy_glib_base;connection.html#tp-connection-hold-handles"><function>tp_connection_hold_handles()</function></ulink> and <ulink url="&url_telepathy_glib_base;connection.html#tp-connection-unref-handles"><function>tp_connection_unref_handles()</function></ulink> functions which reference-count the client-side handle "hold", allowing you to match each <function>tp_connection_hold_handles()</function> call with a call to <function>tp_connection_release_handles()</function>.</para>
<!-- TODO: On irc, smcv said: "perhaps "the user types in the name of a chatroom to join" would be a better example of when you want to use tp_connection_request_handles/tp_connection_unref_handles". Explain that more fully. -->
@@ -349,9 +349,9 @@ AC_SUBST(EXAMPLE_LIBS)
<title>API conventions</title>
<para>Telepathy's method names follow a simple convention.</para>
<orderedlist>
- <listitem><simpara>Methods prefixed with <literal>Request</literal> are aysnchronous, meaning that the result will be provided later and your application should not block while it waits. For instance, <ulink url="&url_spec_base;Connection.RequestChannel"><function>Connection.RequestChannel()</function></ulink>.</simpara></listitem>
+ <listitem><simpara>Methods prefixed with <literal>Request</literal> are aysnchronous, meaning that the result will be provided later and your application should not block while it waits. For instance, <ulink url="&url_spec_base;Connection.RequestChannel"><methodname>Connection.RequestChannel()</methodname></ulink>.</simpara></listitem>
<!-- TODO: What is the D-Bus convention for the separator? . or :: ? -->
- <listitem><simpara>Methods prefixed with <literal>Get</literal> are synchronous, meaning that the result will be returned immediately. These methods generally access local information and do not need to make any contact with the remote server. For instance, <ulink url="&url_spec_base;Connection.GetStatus"><function>Connection.GetStatus()</function></ulink>.</simpara></listitem>
+ <listitem><simpara>Methods prefixed with <literal>Get</literal> are synchronous, meaning that the result will be returned immediately. These methods generally access local information and do not need to make any contact with the remote server. For instance, <ulink url="&url_spec_base;Connection.GetStatus"><methodname>Connection.GetStatus()</methodname></ulink>.</simpara></listitem>
</orderedlist>
<para>See the <link linkend="sec-basics-dbus">Using D-Bus</link> section to learn more about asynchronous D-Bus method calls. Note that many <literal>Get</literal> methods may be replaced with D-Bus properties in future, which will also be syncronous.</para>
@@ -394,10 +394,10 @@ AC_SUBST(EXAMPLE_LIBS)
<chapter id="chapter-connection-manager">
<title>Connection Manager</title>
- <para>As mentioned in the <link linkend="sec-basics-connection-managers">Basics</link> chapter, each <ulink url="&url_spec_base;ConnectionManager"><classname>ConnectionManager</classname></ulink> provides support for a communication protocol.</para>
+ <para>As mentioned in the <link linkend="sec-basics-connection-managers">Basics</link> chapter, each <ulink url="&url_spec_base;ConnectionManager"><interfacename>ConnectionManager</interfacename></ulink> provides support for a communication protocol.</para>
- <para>All Telepathy Connection Managers have <literal>bus name</literal>s that begin with "org.freedesktop.Telepathy.ConnectionManager" so you can discover all available connection managers by calling the D-Bus <ulink url="&url_dbus_spec_base;bus-messages-list-activatable-names"><function>ListActivatableNames()</function></ulink> method and then comparing the names with that prefix. telepathy-glib provides the <ulink url="&url_telepathy_glib_base;connection-manager.html#tp-list-connection-managers"><function>tp_list_connection_managers()</function></ulink> function that conveniently does this.</para>
- <para>You may then discover what protocols are provided by each connection manager by calling the ConnectionManagers's <ulink url="&url_spec_base;ConnectionManager.ListProtocols"><function>ListProtocols</function></ulink> D-Bus method. telepathy-glib's <ulink url="&url_telepathy_glib_base;connection-manager.html"><classname>TpConnectionManager</classname></ulink> object calls this automatically and emits the <literal>got-info</literal> signal when it has returned. You can examine the TpConnectionManager::protocols struct field in your signal handler.</para>
+ <para>All Telepathy Connection Managers have <literal>bus name</literal>s that begin with "org.freedesktop.Telepathy.ConnectionManager" so you can discover all available connection managers by calling the D-Bus <ulink url="&url_dbus_spec_base;bus-messages-list-activatable-names"><methodname>ListActivatableNames()</methodname></ulink> method and then comparing the names with that prefix. telepathy-glib provides the <ulink url="&url_telepathy_glib_base;connection-manager.html#tp-list-connection-managers"><function>tp_list_connection_managers()</function></ulink> function that conveniently does this.</para>
+ <para>You may then discover what protocols are provided by each connection manager by calling the ConnectionManagers's <ulink url="&url_spec_base;ConnectionManager.ListProtocols"><methodname>ListProtocols()</methodname></ulink> D-Bus method. telepathy-glib's <ulink url="&url_telepathy_glib_base;connection-manager.html"><classname>TpConnectionManager</classname></ulink> object calls this automatically and emits the <literal>got-info</literal> signal when it has returned. You can examine the TpConnectionManager::protocols struct field in your signal handler.</para>
<para>Applications, such as IM clients, might choose to offer the user a choice from that list of protocols and then use the appropriate connection manager. Others might use only one protocol and therefore hard-code the connection manager's <literal>bus name</literal>.</para>
<sect1>
@@ -413,13 +413,13 @@ AC_SUBST(EXAMPLE_LIBS)
<sect1>
<title>Connecting</title>
- <para>To attempt a connection to the remote server, for instance to your Jabber IM account, call a <classname>ConnectionManager</classname>'s <ulink url="&url_spec_base;ConnectionManager.RequestConnection"><function>RequestConnection</function></ulink> D-Bus method, providing the connection details. If the connection succeeds then this method returns the <literal>bus name</literal> and <literal>object path</literal> of a Telepathy <ulink url="&url_spec_base;Connection"><classname>Connection</classname></ulink> object.</para>
+ <para>To attempt a connection to the remote server, for instance to your Jabber IM account, call a <interfacename>ConnectionManager</interfacename>'s <ulink url="&url_spec_base;ConnectionManager.RequestConnection"><methodname>RequestConnection()</methodname></ulink> D-Bus method, providing the connection details. If the connection succeeds then this method returns the <literal>bus name</literal> and <literal>object path</literal> of a Telepathy <ulink url="&url_spec_base;Connection"><interfacename>Connection</interfacename></ulink> object.</para>
<para>As of this writing, there is no hand-coded telepathy-glib function to request the connection and directly provide a <ulink url="&url_telepathy_glib_base;connection.html"><classname>TpConnection</classname></ulink> proxy. However, you may use the generated <ulink url="&url_telepathy_glib_base;connection-manager.html#tp_cli_connection_manager_call_request_connection"><function>tp_cli_connection_manager_call_request_connection()</function></ulink> function. In the callback, you can then use the provided <literal>bus name</literal> and <literal>object path</literal> to instantiate a TpConnection proxy object.</para>
<note><para>See the <link linkend="sec-basics-language-bindings-telepathy-glib-generated">Basics</link> chapter for an explanation of hand-coded and generated API in telepathy-glib.</para></note>
- <para>See the <link linkend="chapter-channel">Channels</link> section about obtaining and using <classname>Channel</classname>s from the <classname>Connection</classname> with which you can list groups of contacts .</para>
+ <para>See the <link linkend="chapter-channel">Channels</link> section about obtaining and using <interfacename>Channel</interfacename>s from the <interfacename>Connection</interfacename> with which you can list groups of contacts .</para>
<!-- TODO: Mention these interfaces, mentioned by smcv on irc: Requests and Contacts are "recommended" (every protocol ought to be able to support them), and are only non-core because they're new (so clients can discover whether they're present)
murrayc: when we eventually remove deprecated stuff, it's likely that Requests and Contacts will become part of Connection -->
@@ -433,11 +433,11 @@ AC_SUBST(EXAMPLE_LIBS)
<sect1>
<title>Presence</title>
- <para>If a protocol has a concept of presence, showing when users are online or available, then that <classname>ConnectionManager</classname>'s <classname>Connection</classname> will provide the <ulink url="&url_spec_base;Connection.Interface.SimplePresence"><classname>SimplePresence</classname></ulink> interface. This interface has functions to set and get the current presence for the connected account. It also has a <ulink url="&url_spec_base;Connection.Interface.SimplePresence.PresencesChanged">PresencesChanged</ulink> signal to detect changes to the presence caused by other clients.</para>
+ <para>If a protocol has a concept of presence, showing when users are online or available, then that <interfacename>ConnectionManager</interfacename>'s <interfacename>Connection</interfacename> will provide the <ulink url="&url_spec_base;Connection.Interface.SimplePresence"><interfacename>SimplePresence</interfacename></ulink> interface. This interface has functions to set and get the current presence for the connected account. It also has a <ulink url="&url_spec_base;Connection.Interface.SimplePresence.PresencesChanged">PresencesChanged</ulink> signal to detect changes to the presence caused by other clients.</para>
<sect2>
<title>Presence Example</title>
- <para>This example sets the presence for a jabber account, by calling the <function>SetPresence()</function> method of the <classname>Connection</classname>'s <classname>SimplePresence</classname> interface, using telepathy-glib.</para>
+ <para>This example sets the presence for a jabber account, by calling the <methodname>SetPresence()</methodname> method of the <interfacename>Connection</interfacename>'s <interfacename>SimplePresence</interfacename> interface, using telepathy-glib.</para>
<para><ulink url="&url_examples_base;set_presence">Source Code</ulink></para>
</sect2>
@@ -445,7 +445,7 @@ AC_SUBST(EXAMPLE_LIBS)
<sect1>
<title>Optional Interfaces</title>
- <para>As mentioned in the <link linkend="sec-basics-optional-interfaces">Basics</link> section, the <classname>Connection</classname> may provide several optional interfaces, depending on the <classname>ConnectionManager</classname> used and depending on the capabilities of the remote server.</para>
+ <para>As mentioned in the <link linkend="sec-basics-optional-interfaces">Basics</link> section, the <interfacename>Connection</interfacename> may provide several optional interfaces, depending on the <interfacename>ConnectionManager</interfacename> used and depending on the capabilities of the remote server.</para>
<para>For instance, these interfaces are present if the remote server or its protocol provides that functionality:</para>
@@ -455,7 +455,7 @@ AC_SUBST(EXAMPLE_LIBS)
<varlistentry>
<term>
<indexterm><primary>Aliasing</primary></indexterm>
- <ulink url="&url_spec_base;Connection.Interface.Aliasing"><classname>Aliasing</classname></ulink>
+ <ulink url="&url_spec_base;Connection.Interface.Aliasing"><interfacename>Aliasing</interfacename></ulink>
</term>
<listitem>
<para>TODO: Notes: provides other information about contacts, and notifications when they change.</para>
@@ -465,7 +465,7 @@ AC_SUBST(EXAMPLE_LIBS)
<varlistentry>
<term>
<indexterm><primary>Avatars</primary></indexterm>
- <ulink url="&url_spec_base;Connection.Interface.Avatars"><classname>Avatars</classname></ulink>
+ <ulink url="&url_spec_base;Connection.Interface.Avatars"><interfacename>Avatars</interfacename></ulink>
</term>
<listitem>
<para>TODO: Notes: provides other information about contacts, and notifications when they change.</para>
@@ -475,7 +475,7 @@ AC_SUBST(EXAMPLE_LIBS)
<varlistentry>
<term>
<indexterm><primary>Presence</primary></indexterm>
- <ulink url="&url_spec_base;Connection.Interface.Presence"><classname>Presence</classname></ulink>
+ <ulink url="&url_spec_base;Connection.Interface.Presence"><interfacename>Presence</interfacename></ulink>
</term>
<listitem>
<para>TODO</para>
@@ -484,7 +484,7 @@ AC_SUBST(EXAMPLE_LIBS)
</variablelist>
- <para>These newer interfaces are present if the <classname>ConnectionManager</classname> has implemented them already. They generally replace older deprecated interfaces. They must be optional to avoid forcing all <classname>ConnectionManager</classname>s and all client code to use the new interfaces immediately.</para>
+ <para>These newer interfaces are present if the <interfacename>ConnectionManager</interfacename> has implemented them already. They generally replace older deprecated interfaces. They must be optional to avoid forcing all <interfacename>ConnectionManager</interfacename>s and all client code to use the new interfaces immediately.</para>
<!-- TODO: Are there other potential optional Connection interfaces. I can't tell from the Spec. murrayc. -->
<variablelist>
@@ -492,7 +492,7 @@ AC_SUBST(EXAMPLE_LIBS)
<varlistentry>
<term>
<indexterm><primary>Requests</primary></indexterm>
- <ulink url="&url_spec_base;Connection.Interface.Requests"><classname>Requests</classname></ulink>
+ <ulink url="&url_spec_base;Connection.Interface.Requests"><interfacename>Requests</interfacename></ulink>
</term>
<listitem>
<para>TODO: Notes: improves a similar existing interface - instead of <ulink url="&url_spec_base;Connection.RequestChannel">Connection.RequestChannel</ulink>.</para>
@@ -502,7 +502,7 @@ AC_SUBST(EXAMPLE_LIBS)
<varlistentry>
<term>
<indexterm><primary>SimplePresence</primary></indexterm>
- <ulink url="&url_spec_base;Connection.Interface.SimplePresence"><classname>SimplePresence</classname></ulink>
+ <ulink url="&url_spec_base;Connection.Interface.SimplePresence"><interfacename>SimplePresence</interfacename></ulink>
</term>
<listitem>
<para>TODO: Notes: to which I can give a contact handle
@@ -566,7 +566,7 @@ AC_SUBST(EXAMPLE_LIBS)
<sect1>
<title>Optional Interfaces</title>
- <para>As mentioned in the <link linkend="sec-basics-optional-interfaces">Basics</link> section, the <classname>Channel</classname> may provide several optional interfaces, depending on the <classname>ConnectionManager</classname> used and depending on the capabilities of the remote server.</para>
+ <para>As mentioned in the <link linkend="sec-basics-optional-interfaces">Basics</link> section, the <interfacename>Channel</interfacename> may provide several optional interfaces, depending on the <interfacename>ConnectionManager</interfacename> used and depending on the capabilities of the remote server.</para>
<para>For instance, these interfaces are present if the remote server or its protocol provides that functionality:</para>
@@ -585,7 +585,7 @@ AC_SUBST(EXAMPLE_LIBS)
<varlistentry>
<term>
<indexterm><primary>Group</primary></indexterm>
- <ulink url="&url_spec_base;Connection.Interface.Group"><classname>Group</classname></ulink>
+ <ulink url="&url_spec_base;Connection.Interface.Group"><interfacename>Group</interfacename></ulink>
</term>
<listitem>
<para>TODO.</para>
--
1.5.6.5
More information about the telepathy-commits
mailing list