summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--AUTHORS1
-rw-r--r--CMakeLists.txt148
-rw-r--r--COPYING510
-rw-r--r--ChangeLog2
-rw-r--r--HACKING55
-rw-r--r--NEWS10
-rw-r--r--README60
-rw-r--r--TODO1
-rw-r--r--TelepathyQt4Yell/CMakeLists.txt132
-rw-r--r--TelepathyQt4Yell/Channel13
-rw-r--r--TelepathyQt4Yell/Constants13
-rw-r--r--TelepathyQt4Yell/Global13
-rw-r--r--TelepathyQt4Yell/TelepathyQt4Yell-uninstalled.pc.in11
-rw-r--r--TelepathyQt4Yell/TelepathyQt4Yell.pc.in11
-rw-r--r--TelepathyQt4Yell/Types13
-rw-r--r--TelepathyQt4Yell/channel.cpp24
-rw-r--r--TelepathyQt4Yell/channel.h30
-rw-r--r--TelepathyQt4Yell/channel.xml14
-rw-r--r--TelepathyQt4Yell/constants.h30
-rw-r--r--TelepathyQt4Yell/global.h44
-rw-r--r--TelepathyQt4Yell/stable-interfaces.xml12
-rw-r--r--TelepathyQt4Yell/types.cpp42
-rw-r--r--TelepathyQt4Yell/types.h39
-rw-r--r--cmake/modules/CompilerWarnings.cmake63
-rw-r--r--cmake/modules/Doxygen.cmake24
-rw-r--r--cmake/modules/FindDBus.cmake72
-rw-r--r--cmake/modules/FindGLIB2.cmake52
-rw-r--r--cmake/modules/FindGObject.cmake75
-rw-r--r--cmake/modules/FindGStreamer.cmake80
-rw-r--r--cmake/modules/FindLibPython.py12
-rw-r--r--cmake/modules/FindLibXml2.cmake57
-rw-r--r--cmake/modules/FindPythonLibrary.cmake83
-rw-r--r--cmake/modules/FindTelepathyFarsight.cmake49
-rw-r--r--cmake/modules/FindTelepathyGlib.cmake54
-rw-r--r--cmake/modules/FindTelepathyQt4.cmake28
-rw-r--r--cmake/modules/MacroLogFeature.cmake146
-rw-r--r--cmake/modules/TelepathyDefaults.cmake137
-rw-r--r--cmake/modules/TelepathyDist.cmake39
-rw-r--r--cmake/modules/TpQt4Macros.cmake428
-rw-r--r--cmake_uninstall.cmake.in21
-rw-r--r--config.h.in2
-rw-r--r--doxygen-footer.html7
-rw-r--r--doxygen-header.html30
-rw-r--r--doxygen.cfg.in1470
-rw-r--r--doxygen.css434
-rw-r--r--spec/Account.xml733
-rw-r--r--spec/Account_Interface_Addressing.xml76
-rw-r--r--spec/Account_Interface_Avatar.xml76
-rw-r--r--spec/Account_Interface_Storage.xml169
-rw-r--r--spec/Account_Manager.xml296
-rw-r--r--spec/Authentication_TLS_Certificate.xml305
-rw-r--r--spec/Call_Content.xml291
-rw-r--r--spec/Call_Content_Codec_Offer.xml87
-rw-r--r--spec/Call_Content_Interface_Media.xml331
-rw-r--r--spec/Call_Content_Interface_Mute.xml85
-rw-r--r--spec/Call_Stream.xml261
-rw-r--r--spec/Call_Stream_Endpoint.xml182
-rw-r--r--spec/Call_Stream_Interface_Media.xml447
-rw-r--r--spec/Channel.xml557
-rw-r--r--spec/Channel_Bundle.xml48
-rw-r--r--spec/Channel_Dispatch_Operation.xml483
-rw-r--r--spec/Channel_Dispatcher.xml595
-rw-r--r--spec/Channel_Dispatcher_Interface_Operation_List.xml140
-rw-r--r--spec/Channel_Future.xml68
-rw-r--r--spec/Channel_Handler.xml78
-rw-r--r--spec/Channel_Interface_Addressing.xml107
-rw-r--r--spec/Channel_Interface_Anonymity.xml68
-rw-r--r--spec/Channel_Interface_Call_State.xml147
-rw-r--r--spec/Channel_Interface_Chat_State.xml144
-rw-r--r--spec/Channel_Interface_Conference.xml628
-rw-r--r--spec/Channel_Interface_DTMF.xml342
-rw-r--r--spec/Channel_Interface_Destroyable.xml82
-rw-r--r--spec/Channel_Interface_Group.xml1166
-rw-r--r--spec/Channel_Interface_HTML.xml86
-rw-r--r--spec/Channel_Interface_Hold.xml222
-rw-r--r--spec/Channel_Interface_Media_Signalling.xml235
-rw-r--r--spec/Channel_Interface_Mergeable_Conference.xml110
-rw-r--r--spec/Channel_Interface_Messages.xml1433
-rw-r--r--spec/Channel_Interface_Password.xml104
-rw-r--r--spec/Channel_Interface_Room.xml373
-rw-r--r--spec/Channel_Interface_SASL_Authentication.xml704
-rw-r--r--spec/Channel_Interface_SMS.xml179
-rw-r--r--spec/Channel_Interface_Securable.xml78
-rw-r--r--spec/Channel_Interface_Service_Point.xml86
-rw-r--r--spec/Channel_Interface_Splittable.xml71
-rw-r--r--spec/Channel_Interface_Transfer.xml53
-rw-r--r--spec/Channel_Interface_Tube.xml258
-rw-r--r--spec/Channel_Request.xml300
-rw-r--r--spec/Channel_Type_Call.xml1429
-rw-r--r--spec/Channel_Type_Contact_List.xml104
-rw-r--r--spec/Channel_Type_Contact_Search.xml462
-rw-r--r--spec/Channel_Type_DBus_Tube.xml189
-rw-r--r--spec/Channel_Type_File_Transfer.xml531
-rw-r--r--spec/Channel_Type_Room_List.xml166
-rw-r--r--spec/Channel_Type_Server_Authentication.xml121
-rw-r--r--spec/Channel_Type_Server_TLS_Connection.xml69
-rw-r--r--spec/Channel_Type_Stream_Tube.xml292
-rw-r--r--spec/Channel_Type_Streamed_Media.xml853
-rw-r--r--spec/Channel_Type_Text.xml669
-rw-r--r--spec/Channel_Type_Tubes.xml615
-rw-r--r--spec/Client.xml122
-rw-r--r--spec/Client_Approver.xml197
-rw-r--r--spec/Client_Handler.xml337
-rw-r--r--spec/Client_Handler_Future.xml88
-rw-r--r--spec/Client_Interface_Requests.xml175
-rw-r--r--spec/Client_Observer.xml379
-rw-r--r--spec/Connection.xml1293
-rw-r--r--spec/Connection_Future.xml110
-rw-r--r--spec/Connection_Interface_Addressing.xml258
-rw-r--r--spec/Connection_Interface_Aliasing.xml185
-rw-r--r--spec/Connection_Interface_Anonymity.xml165
-rw-r--r--spec/Connection_Interface_Avatars.xml516
-rw-r--r--spec/Connection_Interface_Balance.xml111
-rw-r--r--spec/Connection_Interface_Capabilities.xml254
-rw-r--r--spec/Connection_Interface_Cellular.xml131
-rw-r--r--spec/Connection_Interface_Client_Types.xml218
-rw-r--r--spec/Connection_Interface_Communication_Policy.xml163
-rw-r--r--spec/Connection_Interface_Contact_Capabilities.xml306
-rw-r--r--spec/Connection_Interface_Contact_Groups.xml549
-rw-r--r--spec/Connection_Interface_Contact_Info.xml550
-rw-r--r--spec/Connection_Interface_Contact_List.xml1085
-rw-r--r--spec/Connection_Interface_Contacts.xml191
-rw-r--r--spec/Connection_Interface_Forwarding.xml346
-rw-r--r--spec/Connection_Interface_Keepalive.xml73
-rw-r--r--spec/Connection_Interface_Location.xml464
-rw-r--r--spec/Connection_Interface_Mail_Notification.xml624
-rw-r--r--spec/Connection_Interface_Power_Saving.xml109
-rw-r--r--spec/Connection_Interface_Presence.xml346
-rw-r--r--spec/Connection_Interface_Privacy.xml94
-rw-r--r--spec/Connection_Interface_Renaming.xml98
-rw-r--r--spec/Connection_Interface_Requests.xml628
-rw-r--r--spec/Connection_Interface_Resources.xml212
-rw-r--r--spec/Connection_Interface_Service_Point.xml136
-rw-r--r--spec/Connection_Interface_Simple_Presence.xml634
-rw-r--r--spec/Connection_Manager.xml614
-rw-r--r--spec/Debug.xml165
-rw-r--r--spec/Media_Session_Handler.xml81
-rw-r--r--spec/Media_Stream_Handler.xml725
-rw-r--r--spec/Properties_Interface.xml194
-rw-r--r--spec/Protocol.xml485
-rw-r--r--spec/Protocol_Interface_Addressing.xml300
-rw-r--r--spec/Protocol_Interface_Avatars.xml157
-rw-r--r--spec/Protocol_Interface_Presence.xml113
-rw-r--r--spec/all.xml303
-rw-r--r--spec/errors.xml564
-rw-r--r--spec/generic-types.xml215
-rw-r--r--spec/template.xml33
-rw-r--r--tests/CMakeLists.txt35
-rw-r--r--tests/README13
-rw-r--r--tests/dbus-1/CMakeLists.txt2
-rw-r--r--tests/dbus-1/session.conf.in30
-rw-r--r--tests/dbus/CMakeLists.txt9
-rw-r--r--tests/lib/CMakeLists.txt7
-rw-r--r--tests/lib/test.cpp127
-rw-r--r--tests/lib/test.h62
-rw-r--r--tools/CMakeLists.txt102
-rw-r--r--tools/c-constants-gen.py154
-rw-r--r--tools/check-misc.sh13
-rw-r--r--tools/check-whitespace.sh17
-rw-r--r--tools/git-which-branch.sh25
-rw-r--r--tools/glib-ginterface-gen.py802
-rw-r--r--tools/glib-gtypes-generator.py291
-rw-r--r--tools/glib-interfaces-gen.py119
-rw-r--r--tools/glib-signals-marshal-gen.py55
-rw-r--r--tools/libglibcodegen.py172
-rw-r--r--tools/libqt4codegen.py365
-rw-r--r--tools/libtpcodegen.py215
-rw-r--r--tools/manager-file.py175
-rw-r--r--tools/qt4-client-gen.py545
-rw-r--r--tools/qt4-constants-gen.py309
-rw-r--r--tools/qt4-types-gen.py556
-rwxr-xr-xtools/repeat-tests.sh23
-rw-r--r--tools/telepathy-glib.supp390
-rw-r--r--tools/telepathy-qt4.supp53
-rw-r--r--tools/with-session-bus.sh94
-rw-r--r--tools/xincludator.py39
176 files changed, 42270 insertions, 0 deletions
diff --git a/AUTHORS b/AUTHORS
new file mode 100644
index 0000000..fa774ff
--- /dev/null
+++ b/AUTHORS
@@ -0,0 +1 @@
+Andre Moreira Magalhaes (andrunko) <andre.magalhaes@collabora.co.uk>
diff --git a/CMakeLists.txt b/CMakeLists.txt
new file mode 100644
index 0000000..edbdf4a
--- /dev/null
+++ b/CMakeLists.txt
@@ -0,0 +1,148 @@
+project(TelepathyQt4Yell)
+
+cmake_minimum_required(VERSION 2.6)
+
+# CMake policies are used for backwards compatibilty. Setting a policy to a behavior lets newer
+# CMake versions where some behaviors changed behave in a way or another. In our specific case,
+# From CMake's documentation:
+#
+# In CMake 2.6.2 and below, CMake Policy settings in scripts loaded by
+# the include() and find_package() commands would affect the includer.
+# Explicit invocations of cmake_policy(PUSH) and cmake_policy(POP) were
+# required to isolate policy changes and protect the includer. While
+# some scripts intend to affect the policies of their includer, most do
+# not. In CMake 2.6.3 and above, include() and find_package() by
+# default PUSH and POP an entry on the policy stack around an included
+# script, but provide a NO_POLICY_SCOPE option to disable it. This
+# policy determines whether or not to imply NO_POLICY_SCOPE for
+# compatibility. The OLD behavior for this policy is to imply
+# NO_POLICY_SCOPE for include() and find_package() commands. The NEW
+# behavior for this policy is to allow the commands to do their default
+# cmake_policy PUSH and POP.
+#
+# This policy was introduced in CMake version 2.6.3. CMake version
+# 2.8.2 warns when the policy is not set and uses OLD behavior. Use the
+# cmake_policy command to set it to OLD or NEW explicitly.
+#
+# Whenever our cmake_minimum_required version bumps up to 2.7 or 2.6.3, this policy setting can
+# hence be removed.
+if(POLICY CMP0011)
+ cmake_policy(SET CMP0011 NEW)
+endif(POLICY CMP0011)
+
+# Making releases:
+# set the new version number:
+# odd minor -> development series
+# even minor -> stable series
+# increment micro for each release within a series
+# set nano_version to 0
+# make the release, tag it
+# set nano_version to 1
+set(TP_QT4_YELL_MAJOR_VERSION 0)
+set(TP_QT4_YELL_MINOR_VERSION 0)
+set(TP_QT4_YELL_MICRO_VERSION 99)
+set(TP_QT4_YELL_NANO_VERSION 1)
+
+# This value contains the library's SOVERSION. This value is to be increased everytime an API/ABI break
+# occurs, and will be used for the SOVERSION of the generated shared libraries.
+set(TP_QT4_YELL_ABI_VERSION 0)
+# This variable is used for the library's long version. It is generated dynamically, so don't change its
+# value! Change TP_QT4_YELL_ABI_VERSION and TP_QT4_YELL_*_VERSION instead.
+if (${TP_QT4_YELL_NANO_VERSION} EQUAL 0)
+ set(TP_QT4_YELL_LIBRARY_VERSION ${TP_QT4_YELL_ABI_VERSION}.${TP_QT4_YELL_MAJOR_VERSION}.${TP_QT4_YELL_MINOR_VERSION}.${TP_QT4_YELL_MICRO_VERSION})
+else (${TP_QT4_YELL_NANO_VERSION} EQUAL 0)
+ set(TP_QT4_YELL_LIBRARY_VERSION ${TP_QT4_YELL_ABI_VERSION}.${TP_QT4_YELL_MAJOR_VERSION}.${TP_QT4_YELL_MINOR_VERSION}.${TP_QT4_YELL_MICRO_VERSION}.${TP_QT4_NANO_VERSION})
+endif (${TP_QT4_YELL_NANO_VERSION} EQUAL 0)
+
+set(PACKAGE_NAME telepathy-qt4-yell)
+
+if (${TP_QT4_YELL_NANO_VERSION} EQUAL 0)
+ set(PACKAGE_VERSION ${TP_QT4_YELL_MAJOR_VERSION}.${TP_QT4_YELL_MINOR_VERSION}.${TP_QT4_YELL_MICRO_VERSION})
+else (${TP_QT4_YELL_NANO_VERSION} EQUAL 0)
+ set(PACKAGE_VERSION ${TP_QT4_YELL_MAJOR_VERSION}.${TP_QT4_YELL_MINOR_VERSION}.${TP_QT4_YELL_MICRO_VERSION}.${TP_QT4_YELL_NANO_VERSION})
+endif (${TP_QT4_YELL_NANO_VERSION} EQUAL 0)
+
+# where to look first for cmake modules, before ${CMAKE_ROOT}/Modules/ is
+# checked
+set(CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake/modules")
+
+# Default build type is RelWithDebInfo for release versions and Debug for developement
+# versions
+if(NOT CMAKE_BUILD_TYPE)
+ if(TP_QT4_YELL_NANO_VERSION EQUAL 0)
+ set(CMAKE_BUILD_TYPE RelWithDebInfo)
+ else(TP_QT4_YELL_NANO_VERSION EQUAL 0)
+ set(CMAKE_BUILD_TYPE Debug)
+ endif(TP_QT4_YELL_NANO_VERSION EQUAL 0)
+endif(NOT CMAKE_BUILD_TYPE)
+
+# This file contains all the needed initialization macros
+include(TelepathyDefaults)
+
+# TelepathyQt4Yell specific defines needed to trigger deprecation warnings
+if (CXX_DEPRECATED_DECLARATIONS)
+ set(DEPRECATED_DECLARATIONS_FLAGS "${DEPRECATED_DECLARATIONS_FLAGS} -DTELEPATHY_QT4_YELL_DEPRECATED_WARNINGS")
+endif (CXX_DEPRECATED_DECLARATIONS)
+
+# This file contains all macros used in the buildsystem
+include(TpQt4Macros)
+
+include(Doxygen)
+include(MacroLogFeature)
+
+# external dependencies
+
+# Required dependencies
+# Find qt4 version >= 4.5
+set (QT_MIN_VERSION "4.5.0")
+find_package(Qt4 REQUIRED)
+find_package(TelepathyQt4 REQUIRED)
+
+include_directories(${CMAKE_SOURCE_DIR}
+ ${CMAKE_BINARY_DIR}
+ ${QT_INCLUDES}
+ ${TELEPATHY_QT4_INCLUDE_DIR})
+
+add_definitions(-DQT_NO_CAST_FROM_ASCII)
+
+set(ENABLE_DEBUG_OUTPUT ON CACHE BOOL "If activated, compiles support for printing debug output to stderr")
+if (ENABLE_DEBUG_OUTPUT)
+ add_definitions(-DENABLE_DEBUG)
+endif (ENABLE_DEBUG_OUTPUT)
+
+# Find python version >= 2.5
+find_package(PythonLibrary REQUIRED)
+set(REQUIRED_PY 2.5)
+if(${PYTHON_SHORT_VERSION} VERSION_GREATER ${REQUIRED_PY} OR ${PYTHON_SHORT_VERSION} VERSION_EQUAL ${REQUIRED_PY})
+ message(STATUS "Python ${PYTHON_SHORT_VERSION} found")
+else(${PYTHON_SHORT_VERSION} VERSION_GREATER ${REQUIRED_PY} OR ${PYTHON_SHORT_VERSION} VERSION_EQUAL ${REQUIRED_PY})
+ message(SEND_ERROR "Python >= ${REQUIRED_PY} is required")
+endif(${PYTHON_SHORT_VERSION} VERSION_GREATER ${REQUIRED_PY} OR ${PYTHON_SHORT_VERSION} VERSION_EQUAL ${REQUIRED_PY})
+
+# Add the source subdirectories
+add_subdirectory(TelepathyQt4Yell)
+add_subdirectory(tests)
+add_subdirectory(tools)
+
+# Generate config.h
+configure_file(${CMAKE_SOURCE_DIR}/config.h.in ${CMAKE_BINARY_DIR}/config.h)
+
+# Create the uninstall target
+configure_file(
+ "${CMAKE_CURRENT_SOURCE_DIR}/cmake_uninstall.cmake.in"
+ "${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake"
+ IMMEDIATE @ONLY)
+
+add_custom_target(uninstall
+ "${CMAKE_COMMAND}" -P "${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake")
+
+# Display the feature log
+macro_display_feature_log()
+
+add_custom_command(OUTPUT ${CMAKE_BINARY_DIR}/FIXME.out
+ COMMAND egrep
+ ARGS -A 5 '[F]IXME|[T]ODO|[X]XX' ${CMAKE_SOURCE_DIR}/TelepathyQt4Yell/*.[ch]*
+ > FIXME.out || true)
+add_custom_target(check-local DEPENDS ${CMAKE_BINARY_DIR}/FIXME.out)
+
+include(TelepathyDist)
diff --git a/COPYING b/COPYING
new file mode 100644
index 0000000..2d2d780
--- /dev/null
+++ b/COPYING
@@ -0,0 +1,510 @@
+
+ GNU LESSER GENERAL PUBLIC LICENSE
+ Version 2.1, February 1999
+
+ Copyright (C) 1991, 1999 Free Software Foundation, Inc.
+ 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+[This is the first released version of the Lesser GPL. It also counts
+ as the successor of the GNU Library Public License, version 2, hence
+ the version number 2.1.]
+
+ Preamble
+
+ The licenses for most software are designed to take away your
+freedom to share and change it. By contrast, the GNU General Public
+Licenses are intended to guarantee your freedom to share and change
+free software--to make sure the software is free for all its users.
+
+ This license, the Lesser General Public License, applies to some
+specially designated software packages--typically libraries--of the
+Free Software Foundation and other authors who decide to use it. You
+can use it too, but we suggest you first think carefully about whether
+this license or the ordinary General Public License is the better
+strategy to use in any particular case, based on the explanations
+below.
+
+ When we speak of free software, we are referring to freedom of use,
+not price. Our General Public Licenses are designed to make sure that
+you have the freedom to distribute copies of free software (and charge
+for this service if you wish); that you receive source code or can get
+it if you want it; that you can change the software and use pieces of
+it in new free programs; and that you are informed that you can do
+these things.
+
+ To protect your rights, we need to make restrictions that forbid
+distributors to deny you these rights or to ask you to surrender these
+rights. These restrictions translate to certain responsibilities for
+you if you distribute copies of the library or if you modify it.
+
+ For example, if you distribute copies of the library, whether gratis
+or for a fee, you must give the recipients all the rights that we gave
+you. You must make sure that they, too, receive or can get the source
+code. If you link other code with the library, you must provide
+complete object files to the recipients, so that they can relink them
+with the library after making changes to the library and recompiling
+it. And you must show them these terms so they know their rights.
+
+ We protect your rights with a two-step method: (1) we copyright the
+library, and (2) we offer you this license, which gives you legal
+permission to copy, distribute and/or modify the library.
+
+ To protect each distributor, we want to make it very clear that
+there is no warranty for the free library. Also, if the library is
+modified by someone else and passed on, the recipients should know
+that what they have is not the original version, so that the original
+author's reputation will not be affected by problems that might be
+introduced by others.
+
+ Finally, software patents pose a constant threat to the existence of
+any free program. We wish to make sure that a company cannot
+effectively restrict the users of a free program by obtaining a
+restrictive license from a patent holder. Therefore, we insist that
+any patent license obtained for a version of the library must be
+consistent with the full freedom of use specified in this license.
+
+ Most GNU software, including some libraries, is covered by the
+ordinary GNU General Public License. This license, the GNU Lesser
+General Public License, applies to certain designated libraries, and
+is quite different from the ordinary General Public License. We use
+this license for certain libraries in order to permit linking those
+libraries into non-free programs.
+
+ When a program is linked with a library, whether statically or using
+a shared library, the combination of the two is legally speaking a
+combined work, a derivative of the original library. The ordinary
+General Public License therefore permits such linking only if the
+entire combination fits its criteria of freedom. The Lesser General
+Public License permits more lax criteria for linking other code with
+the library.
+
+ We call this license the "Lesser" General Public License because it
+does Less to protect the user's freedom than the ordinary General
+Public License. It also provides other free software developers Less
+of an advantage over competing non-free programs. These disadvantages
+are the reason we use the ordinary General Public License for many
+libraries. However, the Lesser license provides advantages in certain
+special circumstances.
+
+ For example, on rare occasions, there may be a special need to
+encourage the widest possible use of a certain library, so that it
+becomes a de-facto standard. To achieve this, non-free programs must
+be allowed to use the library. A more frequent case is that a free
+library does the same job as widely used non-free libraries. In this
+case, there is little to gain by limiting the free library to free
+software only, so we use the Lesser General Public License.
+
+ In other cases, permission to use a particular library in non-free
+programs enables a greater number of people to use a large body of
+free software. For example, permission to use the GNU C Library in
+non-free programs enables many more people to use the whole GNU
+operating system, as well as its variant, the GNU/Linux operating
+system.
+
+ Although the Lesser General Public License is Less protective of the
+users' freedom, it does ensure that the user of a program that is
+linked with the Library has the freedom and the wherewithal to run
+that program using a modified version of the Library.
+
+ The precise terms and conditions for copying, distribution and
+modification follow. Pay close attention to the difference between a
+"work based on the library" and a "work that uses the library". The
+former contains code derived from the library, whereas the latter must
+be combined with the library in order to run.
+
+ GNU LESSER GENERAL PUBLIC LICENSE
+ TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+ 0. This License Agreement applies to any software library or other
+program which contains a notice placed by the copyright holder or
+other authorized party saying it may be distributed under the terms of
+this Lesser General Public License (also called "this License").
+Each licensee is addressed as "you".
+
+ A "library" means a collection of software functions and/or data
+prepared so as to be conveniently linked with application programs
+(which use some of those functions and data) to form executables.
+
+ The "Library", below, refers to any such software library or work
+which has been distributed under these terms. A "work based on the
+Library" means either the Library or any derivative work under
+copyright law: that is to say, a work containing the Library or a
+portion of it, either verbatim or with modifications and/or translated
+straightforwardly into another language. (Hereinafter, translation is
+included without limitation in the term "modification".)
+
+ "Source code" for a work means the preferred form of the work for
+making modifications to it. For a library, complete source code means
+all the source code for all modules it contains, plus any associated
+interface definition files, plus the scripts used to control
+compilation and installation of the library.
+
+ Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope. The act of
+running a program using the Library is not restricted, and output from
+such a program is covered only if its contents constitute a work based
+on the Library (independent of the use of the Library in a tool for
+writing it). Whether that is true depends on what the Library does
+and what the program that uses the Library does.
+
+ 1. You may copy and distribute verbatim copies of the Library's
+complete source code as you receive it, in any medium, provided that
+you conspicuously and appropriately publish on each copy an
+appropriate copyright notice and disclaimer of warranty; keep intact
+all the notices that refer to this License and to the absence of any
+warranty; and distribute a copy of this License along with the
+Library.
+
+ You may charge a fee for the physical act of transferring a copy,
+and you may at your option offer warranty protection in exchange for a
+fee.
+
+ 2. You may modify your copy or copies of the Library or any portion
+of it, thus forming a work based on the Library, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+ a) The modified work must itself be a software library.
+
+ b) You must cause the files modified to carry prominent notices
+ stating that you changed the files and the date of any change.
+
+ c) You must cause the whole of the work to be licensed at no
+ charge to all third parties under the terms of this License.
+
+ d) If a facility in the modified Library refers to a function or a
+ table of data to be supplied by an application program that uses
+ the facility, other than as an argument passed when the facility
+ is invoked, then you must make a good faith effort to ensure that,
+ in the event an application does not supply such function or
+ table, the facility still operates, and performs whatever part of
+ its purpose remains meaningful.
+
+ (For example, a function in a library to compute square roots has
+ a purpose that is entirely well-defined independent of the
+ application. Therefore, Subsection 2d requires that any
+ application-supplied function or table used by this function must
+ be optional: if the application does not supply it, the square
+ root function must still compute square roots.)
+
+These requirements apply to the modified work as a whole. If
+identifiable sections of that work are not derived from the Library,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works. But when you
+distribute the same sections as part of a whole which is a work based
+on the Library, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote
+it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Library.
+
+In addition, mere aggregation of another work not based on the Library
+with the Library (or with a work based on the Library) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+ 3. You may opt to apply the terms of the ordinary GNU General Public
+License instead of this License to a given copy of the Library. To do
+this, you must alter all the notices that refer to this License, so
+that they refer to the ordinary GNU General Public License, version 2,
+instead of to this License. (If a newer version than version 2 of the
+ordinary GNU General Public License has appeared, then you can specify
+that version instead if you wish.) Do not make any other change in
+these notices.
+
+ Once this change is made in a given copy, it is irreversible for
+that copy, so the ordinary GNU General Public License applies to all
+subsequent copies and derivative works made from that copy.
+
+ This option is useful when you wish to copy part of the code of
+the Library into a program that is not a library.
+
+ 4. You may copy and distribute the Library (or a portion or
+derivative of it, under Section 2) in object code or executable form
+under the terms of Sections 1 and 2 above provided that you accompany
+it with the complete corresponding machine-readable source code, which
+must be distributed under the terms of Sections 1 and 2 above on a
+medium customarily used for software interchange.
+
+ If distribution of object code is made by offering access to copy
+from a designated place, then offering equivalent access to copy the
+source code from the same place satisfies the requirement to
+distribute the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+ 5. A program that contains no derivative of any portion of the
+Library, but is designed to work with the Library by being compiled or
+linked with it, is called a "work that uses the Library". Such a
+work, in isolation, is not a derivative work of the Library, and
+therefore falls outside the scope of this License.
+
+ However, linking a "work that uses the Library" with the Library
+creates an executable that is a derivative of the Library (because it
+contains portions of the Library), rather than a "work that uses the
+library". The executable is therefore covered by this License.
+Section 6 states terms for distribution of such executables.
+
+ When a "work that uses the Library" uses material from a header file
+that is part of the Library, the object code for the work may be a
+derivative work of the Library even though the source code is not.
+Whether this is true is especially significant if the work can be
+linked without the Library, or if the work is itself a library. The
+threshold for this to be true is not precisely defined by law.
+
+ If such an object file uses only numerical parameters, data
+structure layouts and accessors, and small macros and small inline
+functions (ten lines or less in length), then the use of the object
+file is unrestricted, regardless of whether it is legally a derivative
+work. (Executables containing this object code plus portions of the
+Library will still fall under Section 6.)
+
+ Otherwise, if the work is a derivative of the Library, you may
+distribute the object code for the work under the terms of Section 6.
+Any executables containing that work also fall under Section 6,
+whether or not they are linked directly with the Library itself.
+
+ 6. As an exception to the Sections above, you may also combine or
+link a "work that uses the Library" with the Library to produce a
+work containing portions of the Library, and distribute that work
+under terms of your choice, provided that the terms permit
+modification of the work for the customer's own use and reverse
+engineering for debugging such modifications.
+
+ You must give prominent notice with each copy of the work that the
+Library is used in it and that the Library and its use are covered by
+this License. You must supply a copy of this License. If the work
+during execution displays copyright notices, you must include the
+copyright notice for the Library among them, as well as a reference
+directing the user to the copy of this License. Also, you must do one
+of these things:
+
+ a) Accompany the work with the complete corresponding
+ machine-readable source code for the Library including whatever
+ changes were used in the work (which must be distributed under
+ Sections 1 and 2 above); and, if the work is an executable linked
+ with the Library, with the complete machine-readable "work that
+ uses the Library", as object code and/or source code, so that the
+ user can modify the Library and then relink to produce a modified
+ executable containing the modified Library. (It is understood
+ that the user who changes the contents of definitions files in the
+ Library will not necessarily be able to recompile the application
+ to use the modified definitions.)
+
+ b) Use a suitable shared library mechanism for linking with the
+ Library. A suitable mechanism is one that (1) uses at run time a
+ copy of the library already present on the user's computer system,
+ rather than copying library functions into the executable, and (2)
+ will operate properly with a modified version of the library, if
+ the user installs one, as long as the modified version is
+ interface-compatible with the version that the work was made with.
+
+ c) Accompany the work with a written offer, valid for at least
+ three years, to give the same user the materials specified in
+ Subsection 6a, above, for a charge no more than the cost of
+ performing this distribution.
+
+ d) If distribution of the work is made by offering access to copy
+ from a designated place, offer equivalent access to copy the above
+ specified materials from the same place.
+
+ e) Verify that the user has already received a copy of these
+ materials or that you have already sent this user a copy.
+
+ For an executable, the required form of the "work that uses the
+Library" must include any data and utility programs needed for
+reproducing the executable from it. However, as a special exception,
+the materials to be distributed need not include anything that is
+normally distributed (in either source or binary form) with the major
+components (compiler, kernel, and so on) of the operating system on
+which the executable runs, unless that component itself accompanies
+the executable.
+
+ It may happen that this requirement contradicts the license
+restrictions of other proprietary libraries that do not normally
+accompany the operating system. Such a contradiction means you cannot
+use both them and the Library together in an executable that you
+distribute.
+
+ 7. You may place library facilities that are a work based on the
+Library side-by-side in a single library together with other library
+facilities not covered by this License, and distribute such a combined
+library, provided that the separate distribution of the work based on
+the Library and of the other library facilities is otherwise
+permitted, and provided that you do these two things:
+
+ a) Accompany the combined library with a copy of the same work
+ based on the Library, uncombined with any other library
+ facilities. This must be distributed under the terms of the
+ Sections above.
+
+ b) Give prominent notice with the combined library of the fact
+ that part of it is a work based on the Library, and explaining
+ where to find the accompanying uncombined form of the same work.
+
+ 8. You may not copy, modify, sublicense, link with, or distribute
+the Library except as expressly provided under this License. Any
+attempt otherwise to copy, modify, sublicense, link with, or
+distribute the Library is void, and will automatically terminate your
+rights under this License. However, parties who have received copies,
+or rights, from you under this License will not have their licenses
+terminated so long as such parties remain in full compliance.
+
+ 9. You are not required to accept this License, since you have not
+signed it. However, nothing else grants you permission to modify or
+distribute the Library or its derivative works. These actions are
+prohibited by law if you do not accept this License. Therefore, by
+modifying or distributing the Library (or any work based on the
+Library), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Library or works based on it.
+
+ 10. Each time you redistribute the Library (or any work based on the
+Library), the recipient automatically receives a license from the
+original licensor to copy, distribute, link with or modify the Library
+subject to these terms and conditions. You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties with
+this License.
+
+ 11. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License. If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Library at all. For example, if a patent
+license would not permit royalty-free redistribution of the Library by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Library.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply, and the section as a whole is intended to apply in other
+circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system which is
+implemented by public license practices. Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+ 12. If the distribution and/or use of the Library is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Library under this License
+may add an explicit geographical distribution limitation excluding those
+countries, so that distribution is permitted only in or among
+countries not thus excluded. In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+ 13. The Free Software Foundation may publish revised and/or new
+versions of the Lesser General Public License from time to time.
+Such new versions will be similar in spirit to the present version,
+but may differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number. If the Library
+specifies a version number of this License which applies to it and
+"any later version", you have the option of following the terms and
+conditions either of that version or of any later version published by
+the Free Software Foundation. If the Library does not specify a
+license version number, you may choose any version ever published by
+the Free Software Foundation.
+
+ 14. If you wish to incorporate parts of the Library into other free
+programs whose distribution conditions are incompatible with these,
+write to the author to ask for permission. For software which is
+copyrighted by the Free Software Foundation, write to the Free
+Software Foundation; we sometimes make exceptions for this. Our
+decision will be guided by the two goals of preserving the free status
+of all derivatives of our free software and of promoting the sharing
+and reuse of software generally.
+
+ NO WARRANTY
+
+ 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
+WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
+EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
+OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY
+KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
+LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
+THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+ 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
+WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
+AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
+FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
+CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
+LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
+RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
+FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
+SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
+DAMAGES.
+
+ END OF TERMS AND CONDITIONS
+
+ How to Apply These Terms to Your New Libraries
+
+ If you develop a new library, and you want it to be of the greatest
+possible use to the public, we recommend making it free software that
+everyone can redistribute and change. You can do so by permitting
+redistribution under these terms (or, alternatively, under the terms
+of the ordinary General Public License).
+
+ To apply these terms, attach the following notices to the library.
+It is safest to attach them to the start of each source file to most
+effectively convey the exclusion of warranty; and each file should
+have at least the "copyright" line and a pointer to where the full
+notice is found.
+
+
+ <one line to give the library's name and a brief idea of what it does.>
+ Copyright (C) <year> <name of author>
+
+ This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ License as published by the Free Software Foundation; either
+ version 2.1 of the License, or (at your option) any later version.
+
+ This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.
+
+ You should have received a copy of the GNU Lesser General Public
+ License along with this library; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+
+Also add information on how to contact you by electronic and paper mail.
+
+You should also get your employer (if you work as a programmer) or
+your school, if any, to sign a "copyright disclaimer" for the library,
+if necessary. Here is a sample; alter the names:
+
+ Yoyodyne, Inc., hereby disclaims all copyright interest in the
+ library `Frob' (a library for tweaking knobs) written by James
+ Random Hacker.
+
+ <signature of Ty Coon>, 1 April 1990
+ Ty Coon, President of Vice
+
+That's all there is to it!
+
+
diff --git a/ChangeLog b/ChangeLog
new file mode 100644
index 0000000..a4617b4
--- /dev/null
+++ b/ChangeLog
@@ -0,0 +1,2 @@
+This is a placeholder ChangeLog - use `git log` instead.
+In distributed tarballs this is replaced by the output of `git log`.
diff --git a/HACKING b/HACKING
new file mode 100644
index 0000000..327a532
--- /dev/null
+++ b/HACKING
@@ -0,0 +1,55 @@
+Contents:
+
+- Version control
+- Coding style...
+ - ...for C++ code
+ - ...for C and Python code
+- Submitting patches
+
+
+===============================================================================
+Version control
+===============================================================================
+
+The current development version of telepathy-qt4-yell is available from the
+'master' branch in the git repository:
+
+ <git://git.collabora.co.uk/git/telepathy-qt4-yell.git>
+ <git+ssh://git.collabora.co.uk/git/telepathy-qt4-yell.git> (for committers)
+ <http://git.collabora.co.uk/?p=telepathy-qt4-yell.git> (gitweb)
+
+
+===============================================================================
+Coding style
+===============================================================================
+
+For C++ code:
+-------------
+
+TelepathyQt4Yell uses the same coding style used by TelepathyQt4, check the
+HACKING file that comes with TelepathyQt4 for more details.
+
+
+===============================================================================
+Submitting patches
+===============================================================================
+
+Patches should be made as (preferably) git branches or (last resort) -uNr diffs
+against upstream git master, as found at:
+
+ git://git.collabora.co.uk/git/telepathy-qt4-yell.git
+ git+ssh://git.collabora.co.uk/git/telepathy-qt4-yell.git (for committers)
+ http://git.collabora.co.uk/?p=telepathy-qt4-yell.git (gitweb)
+
+Patches can be announced at the freedesktop.org bugzilla, using the product
+"Telepathy" and component "tp-qt4":
+
+ https://bugs.freedesktop.org/enter_bug.cgi?product=Telepathy&component=tp-qt4
+
+If submitting a Git branch, please set the URL field of the bug to point to
+your Git branch. Regardless of whether you are referring to a Git branch or
+attaching patches, please specify the "patch" keyword on the bug.
+
+For details on the code review procedure, see:
+
+ http://telepathy.freedesktop.org/wiki/Review%20Procedure
diff --git a/NEWS b/NEWS
new file mode 100644
index 0000000..98561c4
--- /dev/null
+++ b/NEWS
@@ -0,0 +1,10 @@
+telepathy-qt4-yell 0.1.0 (UNRELEASED)
+=================================
+
+The "..." release.
+
+Enhancements:
+ * ...
+
+Fixes:
+ * ...
diff --git a/README b/README
new file mode 100644
index 0000000..727b9f6
--- /dev/null
+++ b/README
@@ -0,0 +1,60 @@
+==================
+telepathy-qt4-yell
+==================
+
+This is a library for Qt-based Telepathy clients. This library adds support for some DRAFT
+interfaces that could not land in TelepathyQt4 itself due to API/ABI stability rules.
+Once the interfaces are final and the implementation is ready, the code will move to TelepathyQt4
+itself and removed from here.
+
+Telepathy is a D-Bus framework for unifying real time communication,
+including instant messaging, voice calls and video calls. It abstracts
+differences between protocols to provide a unified interface for
+applications. See the Telepathy website for more information:
+
+ http://telepathy.freedesktop.org/
+
+Telepathy specification
+=======================
+
+The copy of the Telepathy specification in the spec/ directory indicates
+the specification that this library claims to implement. The HTML documentation for the latest version of the specification can be viewed at:
+
+ http://telepathy.freedesktop.org/spec/
+
+Requirements
+============
+
+Building telepathy-qt4-yell requires:
+ TelepathyQt4 and its dependencies
+
+See CMakeLists.txt for full details, including versions required.
+Of the packages listed above, only QtCore and QtDBus are required at runtime.
+
+Building also requires the cmake build system.
+
+Bugs, feature requests and to-do list
+=====================================
+
+Report all bugs, feature requests and "to-do" items here:
+ <https://bugs.freedesktop.org/enter_bug.cgi?product=Telepathy&component=tp-qt4>
+
+Running "make check" will produce FIXME.out, which lists all the mentions of
+FIXME, TODO or XXX in the source code. Ideally, all of these should be in
+Bugzilla, but sometimes they're not.
+
+Contact info
+============
+
+This library is maintained by the Telepathy project:
+ <http://telepathy.freedesktop.org/>
+ <mailto:telepathy@lists.freedesktop.org>
+ <irc://irc.freenode.net/telepathy>
+
+Telepathy development is supported by Collabora Ltd.
+ <http://www.collabora.co.uk/>.
+
+Hacking
+=======
+
+See HACKING for version control, coding style and patch submission information.
diff --git a/TODO b/TODO
new file mode 100644
index 0000000..8b13789
--- /dev/null
+++ b/TODO
@@ -0,0 +1 @@
+
diff --git a/TelepathyQt4Yell/CMakeLists.txt b/TelepathyQt4Yell/CMakeLists.txt
new file mode 100644
index 0000000..654c5ea
--- /dev/null
+++ b/TelepathyQt4Yell/CMakeLists.txt
@@ -0,0 +1,132 @@
+file(MAKE_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/_gen")
+
+# Set the required flags found in TelepathyDefaults
+set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${VISIBILITY_HIDDEN_FLAGS} ${COMPILER_COVERAGE_FLAGS} ${DEPRECATED_DECLARATIONS_FLAGS}")
+set(LD_FLAGS "${LD_FLAGS} ${VISIBILITY_HIDDEN_FLAGS} ${COMPILER_COVERAGE_FLAGS} ${DEPRECATED_DECLARATIONS_FLAGS}")
+
+# We are building telepathy-qt4-yell
+add_definitions(-DBUILDING_TELEPATHY_QT4_YELL)
+
+# Sources for Tp-Qt4
+set(telepathy_qt4_yell_SRCS
+ channel.cpp
+ types.cpp)
+
+# Exported headers for Tp-Qt4
+set(telepathy_qt4_yell_HEADERS
+ Channel
+ Constants
+ Global
+ Types
+ channel.h
+ constants.h
+ global.h
+ types.h)
+
+# Headers file moc will be run on
+set(telepathy_qt4_yell_MOC_SRCS
+ channel.h)
+
+# Generated headers which will be installed and exported
+set(telepathy_qt4_yell_gen_HEADERS
+ ${CMAKE_CURRENT_BINARY_DIR}/_gen/cli-channel.h
+ ${CMAKE_CURRENT_BINARY_DIR}/_gen/constants.h
+ ${CMAKE_CURRENT_BINARY_DIR}/_gen/types.h)
+
+# The escape character in MSVC is ^
+if(MSVC)
+ set(TYPES_INCLUDE ^<TelepathyQt4Yell/Types^> )
+ set(GLOBAL_INCLUDE ^<TelepathyQt4Yell/Global^> )
+ set(CHANNEL_EXTRA_INCLUDES '^<TelepathyQt4Yell/Types^>,^<TelepathyQt4/Channel^>' )
+else(MSVC)
+ set(TYPES_INCLUDE '<TelepathyQt4Yell/Types>' )
+ set(GLOBAL_INCLUDE '<TelepathyQt4Yell/Global>' )
+ set(CHANNEL_EXTRA_INCLUDES '<TelepathyQt4Yell/Types>,<TelepathyQt4/Channel>' )
+endif(MSVC)
+
+# Generate the spec files
+set(gen_stable_spec_xml ${CMAKE_CURRENT_BINARY_DIR}/_gen/stable-spec.xml)
+
+tpqt4_xincludator(stable-ifaces-includator ${CMAKE_CURRENT_SOURCE_DIR}/stable-interfaces.xml ${gen_stable_spec_xml})
+
+tpqt4_constants_gen(stable-constants ${gen_stable_spec_xml} ${CMAKE_CURRENT_BINARY_DIR}/_gen/constants.h
+ --namespace=Tpy
+ --define-prefix=TP_QT4_YELL_
+ --must-define=IN_TELEPATHY_QT4_YELL_HEADER
+ DEPENDS stable-ifaces-includator)
+
+tpqt4_types_gen(stable-typesgen ${gen_stable_spec_xml}
+ ${CMAKE_CURRENT_BINARY_DIR}/_gen/types.h ${CMAKE_CURRENT_BINARY_DIR}/_gen/types-body.hpp
+ Tpy TelepathyQt4Yell/types.h TelepathyQt4Yell/Types
+ --must-define=IN_TELEPATHY_QT4_YELL_HEADER
+ --visibility=TELEPATHY_QT4_YELL_EXPORT
+ --extraincludes=${GLOBAL_INCLUDE}
+ DEPENDS stable-constants)
+
+# Add the generated types to the library's sources
+list(APPEND telepathy_qt4_yell_SRCS ${CMAKE_CURRENT_BINARY_DIR}/_gen/types.h)
+list(APPEND telepathy_qt4_yell_SRCS ${CMAKE_CURRENT_BINARY_DIR}/_gen/types-body.hpp)
+
+# For each spec, generate a cli file and add it to the sources (including mocs).
+set(SPECS
+ channel)
+foreach(spec ${SPECS})
+ tpqt4_xincludator(${spec}-spec-xincludator ${CMAKE_CURRENT_SOURCE_DIR}/${spec}.xml ${CMAKE_CURRENT_BINARY_DIR}/_gen/spec-${spec}.xml
+ DEPENDS stable-typesgen)
+ set(NEW_FILES
+ ${CMAKE_CURRENT_BINARY_DIR}/_gen/cli-${spec}-body.hpp
+ ${CMAKE_CURRENT_BINARY_DIR}/_gen/cli-${spec}.moc.hpp)
+ list(APPEND telepathy_qt4_yell_SRCS ${NEW_FILES})
+ list(APPEND telepathy_qt4_yell_generated_specs_mocs "moc-cli-${spec}.moc.hpp")
+ set_source_files_properties(${NEW_FILES} PROPERTIES GENERATED true)
+endforeach(spec ${SPECS})
+
+# Use the client generator for generating headers out of specs
+tpqt4_client_generator(${gen_stable_spec_xml} channel clientchannel TelepathyQt4Yell/channel.h TelepathyQt4Yell/Channel Tpy::Client Tpy IN_TELEPATHY_QT4_YELL_HEADER TELEPATHY_QT4_YELL_EXPORT --mainiface=Tp::Client::ChannelInterface --extraincludes=${CHANNEL_EXTRA_INCLUDES} DEPENDS channel-spec-xincludator)
+
+# Create the library
+add_library(telepathy-qt4-yell STATIC ${telepathy_qt4_yell_SRCS})
+
+# generate client moc files
+foreach(moc_src ${telepathy_qt4_yell_MOC_SRCS})
+ set(generated_file _gen/${moc_src})
+ string(REPLACE ".h" ".moc.hpp" generated_file ${generated_file})
+ tpqt4_generate_moc_i_target_deps(${CMAKE_CURRENT_SOURCE_DIR}/${moc_src} ${CMAKE_CURRENT_BINARY_DIR}/${generated_file}
+ ${telepathy_qt4_yell_generated_specs_mocs})
+ list(APPEND telepathy_qt4_yell_SRCS ${CMAKE_CURRENT_BINARY_DIR}/${generated_file})
+ string(REPLACE ".h" ".moc.hpp" moc_src ${moc_src})
+ add_dependencies(telepathy-qt4-yell "moc-${moc_src}")
+endforeach(moc_src ${telepathy_qt4_yell_MOC_SRCS})
+
+# Link
+target_link_libraries(telepathy-qt4-yell
+ ${QT_QTCORE_LIBRARY}
+ ${QT_QTDBUS_LIBRARY}
+ ${TELEPATHY_QT4_LIBRARIES})
+
+if (ENABLE_COMPILER_COVERAGE)
+ target_link_libraries(telepathy-qt4-yell gcov)
+endif (ENABLE_COMPILER_COVERAGE)
+
+# Set the correct version number
+set_target_properties(telepathy-qt4-yell PROPERTIES
+ SOVERSION ${TP_QT4_YELL_ABI_VERSION}
+ VERSION ${TP_QT4_YELL_LIBRARY_VERSION})
+
+# Install header files
+install(FILES ${telepathy_qt4_yell_HEADERS} DESTINATION ${INCLUDE_INSTALL_DIR}/telepathy-1.0/TelepathyQt4Yell COMPONENT headers)
+install(FILES ${telepathy_qt4_yell_gen_HEADERS} DESTINATION ${INCLUDE_INSTALL_DIR}/telepathy-1.0/TelepathyQt4Yell/_gen COMPONENT headers)
+
+# Install the library - watch out for the correct components
+if (WIN32)
+ install(TARGETS telepathy-qt4-yell RUNTIME DESTINATION ${LIB_INSTALL_DIR} COMPONENT mainlibrary
+ ARCHIVE DESTINATION ${LIB_INSTALL_DIR} COMPONENT headers)
+else (WIN32)
+ install(TARGETS telepathy-qt4-yell LIBRARY DESTINATION ${LIB_INSTALL_DIR} COMPONENT mainlibrary
+ ARCHIVE DESTINATION ${LIB_INSTALL_DIR} COMPONENT headers)
+endif (WIN32)
+
+# pkg-config file
+configure_file(${CMAKE_CURRENT_SOURCE_DIR}/TelepathyQt4Yell.pc.in ${CMAKE_CURRENT_BINARY_DIR}/TelepathyQt4Yell.pc)
+configure_file(${CMAKE_CURRENT_SOURCE_DIR}/TelepathyQt4Yell-uninstalled.pc.in ${CMAKE_CURRENT_BINARY_DIR}/TelepathyQt4Yell-uninstalled.pc)
+install(FILES ${CMAKE_CURRENT_BINARY_DIR}/TelepathyQt4Yell.pc DESTINATION ${LIB_INSTALL_DIR}/pkgconfig COMPONENT headers)
diff --git a/TelepathyQt4Yell/Channel b/TelepathyQt4Yell/Channel
new file mode 100644
index 0000000..15d1e5c
--- /dev/null
+++ b/TelepathyQt4Yell/Channel
@@ -0,0 +1,13 @@
+#ifndef _TelepathyQt4Yell_Channel_HEADER_GUARD_
+#define _TelepathyQt4Yell_Channel_HEADER_GUARD_
+
+#ifndef IN_TELEPATHY_QT4_YELL_HEADER
+#define IN_TELEPATHY_QT4_YELL_HEADER
+#endif
+
+#include <TelepathyQt4Yell/channel.h>
+
+#undef IN_TELEPATHY_QT4_YELL_HEADER
+
+#endif
+// vim:set ft=cpp:
diff --git a/TelepathyQt4Yell/Constants b/TelepathyQt4Yell/Constants
new file mode 100644
index 0000000..44895d6
--- /dev/null
+++ b/TelepathyQt4Yell/Constants
@@ -0,0 +1,13 @@
+#ifndef _TelepathyQt4Yell_Constants_HEADER_GUARD_
+#define _TelepathyQt4Yell_Constants_HEADER_GUARD_
+
+#ifndef IN_TELEPATHY_QT4_YELL_HEADER
+#define IN_TELEPATHY_QT4_YELL_HEADER
+#endif
+
+#include <TelepathyQt4Yell/constants.h>
+
+#undef IN_TELEPATHY_QT4_YELL_HEADER
+
+#endif
+// vim:set ft=cpp:
diff --git a/TelepathyQt4Yell/Global b/TelepathyQt4Yell/Global
new file mode 100644
index 0000000..95e7a2a
--- /dev/null
+++ b/TelepathyQt4Yell/Global
@@ -0,0 +1,13 @@
+#ifndef _TelepathyQt4Yell_Global_HEADER_GUARD_
+#define _TelepathyQt4Yell_Global_HEADER_GUARD_
+
+#ifndef IN_TELEPATHY_QT4_YELL_HEADER
+#define IN_TELEPATHY_QT4_YELL_HEADER
+#endif
+
+#include <TelepathyQt4Yell/global.h>
+
+#undef IN_TELEPATHY_QT4_YELL_HEADER
+
+#endif
+// vim:set ft=cpp:
diff --git a/TelepathyQt4Yell/TelepathyQt4Yell-uninstalled.pc.in b/TelepathyQt4Yell/TelepathyQt4Yell-uninstalled.pc.in
new file mode 100644
index 0000000..b344b1a
--- /dev/null
+++ b/TelepathyQt4Yell/TelepathyQt4Yell-uninstalled.pc.in
@@ -0,0 +1,11 @@
+prefix=/nonexistent
+exec_prefix=/nonexistent
+abs_top_builddir=${CMAKE_BINARY_DIR}
+abs_top_srcdir=${CMAKE_SOURCE_DIR}
+
+Name: Telepathy-Qt4-Yell (uninstalled copy)
+Description: Qt4 utility library for the Telepathy framework
+Version: ${PACKAGE_VERSION}
+Requires.private: QtCore >= 4.5, QtDBus >= 4.5, TelepathyQt4 >= 0.5
+Libs: ${CMAKE_BINARY_DIR}/TelepathyQt4/libtelepathy-qt4-yell.a
+Cflags: -I${CMAKE_SOURCE_DIR} -I${CMAKE_BINARY_DIR}
diff --git a/TelepathyQt4Yell/TelepathyQt4Yell.pc.in b/TelepathyQt4Yell/TelepathyQt4Yell.pc.in
new file mode 100644
index 0000000..b20a141
--- /dev/null
+++ b/TelepathyQt4Yell/TelepathyQt4Yell.pc.in
@@ -0,0 +1,11 @@
+prefix=${CMAKE_INSTALL_PREFIX}
+exec_prefix=${CMAKE_INSTALL_PREFIX}
+libdir=${CMAKE_INSTALL_PREFIX}/${LIB_INSTALL_DIR}
+includedir=${CMAKE_INSTALL_PREFIX}/${INCLUDE_INSTALL_DIR}
+
+Name: Telepathy-Qt4-Yell
+Description: Qt4 utility library for the Telepathy framework
+Version: ${PACKAGE_VERSION}
+Requires.private: QtCore >= 4.5, QtDBus >= 4.5, TelepathyQt4 >= 0.5
+Libs: -L${CMAKE_INSTALL_PREFIX}/${LIB_INSTALL_DIR} -ltelepathy-qt4-yell
+Cflags: -I${CMAKE_INSTALL_PREFIX}/${INCLUDE_INSTALL_DIR}/telepathy-1.0
diff --git a/TelepathyQt4Yell/Types b/TelepathyQt4Yell/Types
new file mode 100644
index 0000000..12c4247
--- /dev/null
+++ b/TelepathyQt4Yell/Types
@@ -0,0 +1,13 @@
+#ifndef _TelepathyQt4Yell_Types_HEADER_GUARD_
+#define _TelepathyQt4Yell_Types_HEADER_GUARD_
+
+#ifndef IN_TELEPATHY_QT4_YELL_HEADER
+#define IN_TELEPATHY_QT4_YELL_HEADER
+#endif
+
+#include <TelepathyQt4Yell/types.h>
+
+#undef IN_TELEPATHY_QT4_YELL_HEADER
+
+#endif
+// vim:set ft=cpp:
diff --git a/TelepathyQt4Yell/channel.cpp b/TelepathyQt4Yell/channel.cpp
new file mode 100644
index 0000000..862acd8
--- /dev/null
+++ b/TelepathyQt4Yell/channel.cpp
@@ -0,0 +1,24 @@
+/*
+ * This file is part of TelepathyQt4Yell
+ *
+ * Copyright (C) 2010 Collabora Ltd. <http://www.collabora.co.uk/>
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+ */
+
+#include <TelepathyQt4Yell/Channel>
+
+#include "TelepathyQt4Yell/_gen/cli-channel-body.hpp"
+#include "TelepathyQt4Yell/_gen/cli-channel.moc.hpp"
diff --git a/TelepathyQt4Yell/channel.h b/TelepathyQt4Yell/channel.h
new file mode 100644
index 0000000..6e7c931
--- /dev/null
+++ b/TelepathyQt4Yell/channel.h
@@ -0,0 +1,30 @@
+/*
+ * This file is part of TelepathyQt4Yell
+ *
+ * Copyright (C) 2010 Collabora Ltd. <http://www.collabora.co.uk/>
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+ */
+
+#ifndef _TelepathyQt4Yell_channel_h_HEADER_GUARD_
+#define _TelepathyQt4Yell_channel_h_HEADER_GUARD_
+
+#ifndef IN_TELEPATHY_QT4_YELL_HEADER
+#error IN_TELEPATHY_QT4_YELL_HEADER
+#endif
+
+#include <TelepathyQt4Yell/_gen/cli-channel.h>
+
+#endif
diff --git a/TelepathyQt4Yell/channel.xml b/TelepathyQt4Yell/channel.xml
new file mode 100644
index 0000000..d974060
--- /dev/null
+++ b/TelepathyQt4Yell/channel.xml
@@ -0,0 +1,14 @@
+<tp:spec
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"
+ xmlns:xi="http://www.w3.org/2001/XInclude">
+
+<tp:title>Channel interfaces</tp:title>
+
+<xi:include href="../spec/Channel_Type_Call.xml"/>
+<xi:include href="../spec/Call_Content.xml"/>
+<xi:include href="../spec/Call_Stream.xml"/>
+
+<xi:include href="../spec/generic-types.xml"/>
+<xi:include href="../spec/errors.xml"/>
+
+</tp:spec>
diff --git a/TelepathyQt4Yell/constants.h b/TelepathyQt4Yell/constants.h
new file mode 100644
index 0000000..1bb279d
--- /dev/null
+++ b/TelepathyQt4Yell/constants.h
@@ -0,0 +1,30 @@
+/*
+ * This file is part of TelepathyQt4Yell
+ *
+ * Copyright (C) 2010 Collabora Ltd. <http://www.collabora.co.uk/>
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+ */
+
+#ifndef _TelepathyQt4Yell_constants_h_HEADER_GUARD_
+#define _TelepathyQt4Yell_constants_h_HEADER_GUARD_
+
+#ifndef IN_TELEPATHY_QT4_YELL_HEADER
+#error IN_TELEPATHY_QT4_YELL_HEADER
+#endif
+
+#include <TelepathyQt4Yell/_gen/constants.h>
+
+#endif
diff --git a/TelepathyQt4Yell/global.h b/TelepathyQt4Yell/global.h
new file mode 100644
index 0000000..d3ff6c2
--- /dev/null
+++ b/TelepathyQt4Yell/global.h
@@ -0,0 +1,44 @@
+/*
+ * This file is part of TelepathyQt4Yell
+ *
+ * Copyright (C) 2010 Collabora Ltd. <http://www.collabora.co.uk/>
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+ */
+
+#ifndef _TelepathyQt4Yell_global_h_HEADER_GUARD_
+#define _TelepathyQt4Yell_global_h_HEADER_GUARD_
+
+#ifndef IN_TELEPATHY_QT4_YELL_HEADER
+#error IN_TELEPATHY_QT4_YELL_HEADER
+#endif
+
+#include <QtGlobal>
+
+#ifdef BUILDING_TELEPATHY_QT4_YELL
+# define TELEPATHY_QT4_YELL_EXPORT Q_DECL_EXPORT
+#else
+# define TELEPATHY_QT4_YELL_EXPORT Q_DECL_IMPORT
+#endif
+
+#if !defined(Q_OS_WIN) && defined(QT_VISIBILITY_AVAILABLE)
+# define TELEPATHY_QT4_YELL_NO_EXPORT __attribute__((visibility("hidden")))
+#endif
+
+#ifndef TELEPATHY_QT4_YELL_NO_EXPORT
+# define TELEPATHY_QT4_YELL_NO_EXPORT
+#endif
+
+#endif
diff --git a/TelepathyQt4Yell/stable-interfaces.xml b/TelepathyQt4Yell/stable-interfaces.xml
new file mode 100644
index 0000000..d0647ae
--- /dev/null
+++ b/TelepathyQt4Yell/stable-interfaces.xml
@@ -0,0 +1,12 @@
+<tp:spec
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"
+ xmlns:xi="http://www.w3.org/2001/XInclude">
+
+<tp:title>Telepathy D-Bus Interface Specification, TelepathyQt4Yell copy</tp:title>
+
+<xi:include href="channel.xml"/>
+
+<xi:include href="../spec/generic-types.xml"/>
+<xi:include href="../spec/errors.xml"/>
+
+</tp:spec>
diff --git a/TelepathyQt4Yell/types.cpp b/TelepathyQt4Yell/types.cpp
new file mode 100644
index 0000000..c10236c
--- /dev/null
+++ b/TelepathyQt4Yell/types.cpp
@@ -0,0 +1,42 @@
+/*
+ * This file is part of TelepathyQt4Yell
+ *
+ * Copyright (C) 2010 Collabora Ltd. <http://www.collabora.co.uk/>
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+ */
+
+#include <TelepathyQt4Yell/Types>
+
+#include "TelepathyQt4Yell/_gen/types-body.hpp"
+
+namespace Tpy
+{
+
+/**
+ * \\ingroup types
+ * \headerfile TelepathyQt4Yell/types.h <TelepathyQt4Yell/Types>
+ *
+ * Register the types used by the library with the QtDBus type system.
+ *
+ * Call this function to register the types used before using anything else in
+ * the library.
+ */
+void registerTypes()
+{
+ Tpy::_registerTypes();
+}
+
+}
diff --git a/TelepathyQt4Yell/types.h b/TelepathyQt4Yell/types.h
new file mode 100644
index 0000000..94b5062
--- /dev/null
+++ b/TelepathyQt4Yell/types.h
@@ -0,0 +1,39 @@
+/*
+ * This file is part of TelepathyQt4Yell
+ *
+ * Copyright (C) 2010 Collabora Ltd. <http://www.collabora.co.uk/>
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+ */
+
+#ifndef _TelepathyQt4Yell_types_h_HEADER_GUARD_
+#define _TelepathyQt4Yell_types_h_HEADER_GUARD_
+
+#ifndef IN_TELEPATHY_QT4_YELL_HEADER
+#error IN_TELEPATHY_QT4_YELL_HEADER
+#endif
+
+#include <TelepathyQt4Yell/_gen/types.h>
+
+#include <TelepathyQt4/Types>
+
+namespace Tpy
+{
+
+TELEPATHY_QT4_YELL_EXPORT void registerTypes();
+
+} // Tpy
+
+#endif
diff --git a/cmake/modules/CompilerWarnings.cmake b/cmake/modules/CompilerWarnings.cmake
new file mode 100644
index 0000000..81367ff
--- /dev/null
+++ b/cmake/modules/CompilerWarnings.cmake
@@ -0,0 +1,63 @@
+include(CheckCXXCompilerFlag)
+include(CheckCCompilerFlag)
+
+macro(check_lang_compiler_flag lang flag variable)
+
+ if(${lang} STREQUAL c)
+ check_c_compiler_flag(${flag} ${variable})
+ endif(${lang} STREQUAL c)
+
+ if(${lang} STREQUAL cxx)
+ check_cxx_compiler_flag(${flag} ${variable})
+ endif(${lang} STREQUAL cxx)
+
+endmacro(check_lang_compiler_flag flag variable)
+
+macro(compiler_warnings ret lang werror_by_default desirable_flags undesirable_flags)
+ set(warning_flags "")
+ foreach(flag ${desirable_flags})
+ check_lang_compiler_flag(${lang} -W${flag} ${flag}_${lang}_result)
+ if(${${flag}_${lang}_result})
+ set(warning_flags "${warning_flags} -W${flag}")
+ endif( ${${flag}_${lang}_result} )
+ endforeach(flag ${desirable_flags})
+
+ check_lang_compiler_flag(${lang} -Werror error_${lang}_result)
+
+ if(${error_${lang}_result})
+ set(error_flags "-Werror")
+ endif(${error_${lang}_result})
+
+ set(all_nowarning_flags_supported 1)
+
+ foreach(flag ${undesirable_flags})
+ check_lang_compiler_flag(${lang} -Wno-${flag} ${flag}_${lang}_result)
+
+ if(${${flag}_${lang}_result})
+ set(warning_flags "${warning_flags} -Wno-${flag}")
+ else(${${flag}_${lang}_result})
+ set(all_nowarning_flags_supported 0)
+ break()
+ endif(${${flag}_${lang}_result})
+
+ check_lang_compiler_flag(${lang} -Wno-error=${flag} noerror_${flag}_${lang}_result)
+
+ if(${noerror_${flag}_${lang}_result})
+ set(error_flags "${error_flags} -Wno-error=${flag}")
+ endif(${noerror_${flag}_${lang}_result})
+
+ endforeach(flag ${undesirable_flags})
+
+ if(${DISABLE_WERROR} STREQUAL ON)
+ set(enable_werror 0)
+ else(${DISABLE_WERROR} STREQUAL ON)
+ set(enable_werror 1)
+ endif(${DISABLE_WERROR} STREQUAL ON)
+
+ if(${werror_by_default} AND ${enable_werror} AND ${all_nowarning_flags_supported})
+ set(${ret} "${warning_flags} ${error_flags}")
+ else(${werror_by_default} AND ${enable_werror} AND ${all_nowarning_flags_supported})
+ set(${ret} "${warning_flags}")
+ endif(${werror_by_default} AND ${enable_werror} AND ${all_nowarning_flags_supported})
+
+endmacro(compiler_warnings ret lang werror_by_default desirable_flags undesirable_flags)
diff --git a/cmake/modules/Doxygen.cmake b/cmake/modules/Doxygen.cmake
new file mode 100644
index 0000000..1258878
--- /dev/null
+++ b/cmake/modules/Doxygen.cmake
@@ -0,0 +1,24 @@
+# generate documentation on 'make doxygen-doc'
+file(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/doc)
+
+find_package(Doxygen)
+if(DOXYGEN_FOUND)
+ find_program(QHELPGENERATOR_EXECUTABLE qhelpgenerator)
+ mark_as_advanced(QHELPGENERATOR_EXECUTABLE)
+
+ include(FindPackageHandleStandardArgs)
+ find_package_handle_standard_args(QHELPGENERATOR DEFAULT_MSG QHELPGENERATOR_EXECUTABLE)
+
+ set(abs_top_builddir ${CMAKE_BINARY_DIR})
+ set(abs_top_srcdir ${CMAKE_SOURCE_DIR})
+ set(GENERATE_HTML YES)
+ set(GENERATE_RTF NO)
+ set(GENERATE_CHM NO)
+ set(GENERATE_CHI NO)
+ set(GENERATE_LATEX NO)
+ set(GENERATE_MAN NO)
+ set(GENERATE_XML NO)
+ set(GENERATE_QHP ${QHELPGENERATOR_FOUND})
+ configure_file(doxygen.cfg.in ${CMAKE_BINARY_DIR}/doxygen.cfg)
+ add_custom_target(doxygen-doc ${DOXYGEN_EXECUTABLE} ${CMAKE_BINARY_DIR}/doxygen.cfg)
+endif(DOXYGEN_FOUND)
diff --git a/cmake/modules/FindDBus.cmake b/cmake/modules/FindDBus.cmake
new file mode 100644
index 0000000..a0b7c3a
--- /dev/null
+++ b/cmake/modules/FindDBus.cmake
@@ -0,0 +1,72 @@
+# - Try to find the low-level D-Bus library
+# Once done this will define
+#
+# DBUS_FOUND - system has D-Bus
+# DBUS_INCLUDE_DIR - the D-Bus include directory
+# DBUS_ARCH_INCLUDE_DIR - the D-Bus architecture-specific include directory
+# DBUS_LIBRARIES - the libraries needed to use D-Bus
+
+# Copyright (c) 2008, Kevin Kofler, <kevin.kofler@chello.at>
+# modeled after FindLibArt.cmake:
+# Copyright (c) 2006, Alexander Neundorf, <neundorf@kde.org>
+#
+# Redistribution and use is allowed according to the terms of the BSD license.
+# For details see the accompanying COPYING-CMAKE-SCRIPTS file.
+
+if (DBUS_INCLUDE_DIR AND DBUS_ARCH_INCLUDE_DIR AND DBUS_LIBRARIES)
+
+ # in cache already
+ SET(DBUS_FOUND TRUE)
+
+else (DBUS_INCLUDE_DIR AND DBUS_ARCH_INCLUDE_DIR AND DBUS_LIBRARIES)
+
+ IF (NOT WIN32)
+ FIND_PACKAGE(PkgConfig)
+ IF (PKG_CONFIG_FOUND)
+ # use pkg-config to get the directories and then use these values
+ # in the FIND_PATH() and FIND_LIBRARY() calls
+ pkg_check_modules(_DBUS_PC dbus-1)
+ ENDIF (PKG_CONFIG_FOUND)
+ ENDIF (NOT WIN32)
+
+ FIND_PATH(DBUS_INCLUDE_DIR dbus/dbus.h
+ ${_DBUS_PC_INCLUDE_DIRS}
+ /usr/include
+ /usr/include/dbus-1.0
+ /usr/local/include
+ )
+
+ FIND_PATH(DBUS_ARCH_INCLUDE_DIR dbus/dbus-arch-deps.h
+ ${_DBUS_PC_INCLUDE_DIRS}
+ /usr/lib${LIB_SUFFIX}/include
+ /usr/lib${LIB_SUFFIX}/dbus-1.0/include
+ /usr/lib64/include
+ /usr/lib64/dbus-1.0/include
+ /usr/lib/include
+ /usr/lib/dbus-1.0/include
+ )
+
+ FIND_LIBRARY(DBUS_LIBRARIES NAMES dbus-1 dbus
+ PATHS
+ ${_DBUS_PC_LIBDIR}
+ )
+
+
+ if (DBUS_INCLUDE_DIR AND DBUS_ARCH_INCLUDE_DIR AND DBUS_LIBRARIES)
+ set(DBUS_FOUND TRUE)
+ endif (DBUS_INCLUDE_DIR AND DBUS_ARCH_INCLUDE_DIR AND DBUS_LIBRARIES)
+
+
+ if (DBUS_FOUND)
+ if (NOT DBus_FIND_QUIETLY)
+ message(STATUS "Found D-Bus: ${DBUS_LIBRARIES}")
+ endif (NOT DBus_FIND_QUIETLY)
+ else (DBUS_FOUND)
+ if (DBus_FIND_REQUIRED)
+ message(FATAL_ERROR "Could NOT find D-Bus")
+ endif (DBus_FIND_REQUIRED)
+ endif (DBUS_FOUND)
+
+ MARK_AS_ADVANCED(DBUS_INCLUDE_DIR DBUS_ARCH_INCLUDE_DIR DBUS_LIBRARIES)
+
+endif (DBUS_INCLUDE_DIR AND DBUS_ARCH_INCLUDE_DIR AND DBUS_LIBRARIES)
diff --git a/cmake/modules/FindGLIB2.cmake b/cmake/modules/FindGLIB2.cmake
new file mode 100644
index 0000000..e40f05f
--- /dev/null
+++ b/cmake/modules/FindGLIB2.cmake
@@ -0,0 +1,52 @@
+# - Try to find the GLIB2 libraries
+# Once done this will define
+#
+# GLIB2_FOUND - system has glib2
+# GLIB2_INCLUDE_DIR - the glib2 include directory
+# GLIB2_LIBRARIES - glib2 library
+
+# Copyright (c) 2008 Laurent Montel, <montel@kde.org>
+#
+# Redistribution and use is allowed according to the terms of the BSD license.
+# For details see the accompanying COPYING-CMAKE-SCRIPTS file.
+
+
+if(GLIB2_INCLUDE_DIR AND GLIB2_LIBRARIES)
+ # Already in cache, be silent
+ set(GLIB2_FIND_QUIETLY TRUE)
+endif(GLIB2_INCLUDE_DIR AND GLIB2_LIBRARIES)
+
+find_package(PkgConfig)
+pkg_check_modules(PC_LibGLIB2 glib-2.0)
+
+find_path(GLIB2_MAIN_INCLUDE_DIR
+ NAMES glib.h
+ HINTS ${PC_LibGLIB2_INCLUDEDIR}
+ PATH_SUFFIXES glib-2.0)
+
+find_library(GLIB2_LIBRARY
+ NAMES glib-2.0
+ HINTS ${PC_LibGLIB2_LIBDIR}
+)
+
+set(GLIB2_LIBRARIES ${GLIB2_LIBRARY})
+
+# search the glibconfig.h include dir under the same root where the library is found
+get_filename_component(glib2LibDir "${GLIB2_LIBRARIES}" PATH)
+
+find_path(GLIB2_INTERNAL_INCLUDE_DIR glibconfig.h
+ PATH_SUFFIXES glib-2.0/include
+ HINTS ${PC_LibGLIB2_INCLUDEDIR} "${glib2LibDir}" ${CMAKE_SYSTEM_LIBRARY_PATH})
+
+set(GLIB2_INCLUDE_DIR "${GLIB2_MAIN_INCLUDE_DIR}")
+
+# not sure if this include dir is optional or required
+# for now it is optional
+if(GLIB2_INTERNAL_INCLUDE_DIR)
+ set(GLIB2_INCLUDE_DIR ${GLIB2_INCLUDE_DIR} "${GLIB2_INTERNAL_INCLUDE_DIR}")
+endif(GLIB2_INTERNAL_INCLUDE_DIR)
+
+include(FindPackageHandleStandardArgs)
+find_package_handle_standard_args(GLIB2 DEFAULT_MSG GLIB2_LIBRARIES GLIB2_MAIN_INCLUDE_DIR)
+
+mark_as_advanced(GLIB2_INCLUDE_DIR GLIB2_LIBRARIES)
diff --git a/cmake/modules/FindGObject.cmake b/cmake/modules/FindGObject.cmake
new file mode 100644
index 0000000..1507b43
--- /dev/null
+++ b/cmake/modules/FindGObject.cmake
@@ -0,0 +1,75 @@
+# - Try to find GObject
+# Once done this will define
+#
+# GOBJECT_FOUND - system has GObject
+# GOBJECT_INCLUDE_DIR - the GObject include directory
+# GOBJECT_LIBRARIES - the libraries needed to use GObject
+# GOBJECT_DEFINITIONS - Compiler switches required for using GObject
+
+# Copyright (c) 2008 Helio Chissini de Castro, <helio@kde.org>
+# (c)2006, Tim Beaulen <tbscope@gmail.com>
+
+
+IF (GOBJECT_INCLUDE_DIR AND GOBJECT_LIBRARIES)
+ # in cache already
+ SET(GObject_FIND_QUIETLY TRUE)
+ELSE (GOBJECT_INCLUDE_DIR AND GOBJECT_LIBRARIES)
+ SET(GObject_FIND_QUIETLY FALSE)
+ENDIF (GOBJECT_INCLUDE_DIR AND GOBJECT_LIBRARIES)
+
+IF (NOT WIN32)
+ FIND_PACKAGE(PkgConfig REQUIRED)
+ # use pkg-config to get the directories and then use these values
+ # in the FIND_PATH() and FIND_LIBRARY() calls
+ PKG_CHECK_MODULES(PKG_GOBJECT2 REQUIRED gobject-2.0)
+ SET(GOBJECT_DEFINITIONS ${PKG_GOBJECT2_CFLAGS})
+ENDIF (NOT WIN32)
+
+FIND_PATH(GOBJECT_INCLUDE_DIR gobject/gobject.h
+ PATHS
+ ${PKG_GOBJECT2_INCLUDE_DIRS}
+ /usr/include/glib-2.0/
+ PATH_SUFFIXES glib-2.0
+ )
+
+FIND_LIBRARY(_GObjectLibs NAMES gobject-2.0
+ PATHS
+ ${PKG_GOBJECT2_LIBRARY_DIRS}
+ )
+FIND_LIBRARY(_GModuleLibs NAMES gmodule-2.0
+ PATHS
+ ${PKG_GOBJECT2_LIBRARY_DIRS}
+ )
+FIND_LIBRARY(_GThreadLibs NAMES gthread-2.0
+ PATHS
+ ${PKG_GOBJECT2_LIBRARY_DIRS}
+ )
+FIND_LIBRARY(_GLibs NAMES glib-2.0
+ PATHS
+ ${PKG_GOBJECT2_LIBRARY_DIRS}
+ )
+
+IF (WIN32)
+SET (GOBJECT_LIBRARIES ${_GObjectLibs} ${_GModuleLibs} ${_GThreadLibs} ${_GLibs})
+ELSE (WIN32)
+SET (GOBJECT_LIBRARIES ${PKG_GOBJECT2_LIBRARIES})
+ENDIF (WIN32)
+
+IF (GOBJECT_INCLUDE_DIR AND GOBJECT_LIBRARIES)
+ SET(GOBJECT_FOUND TRUE)
+ELSE (GOBJECT_INCLUDE_DIR AND GOBJECT_LIBRARIES)
+ SET(GOBJECT_FOUND FALSE)
+ENDIF (GOBJECT_INCLUDE_DIR AND GOBJECT_LIBRARIES)
+
+IF (GOBJECT_FOUND)
+ IF (NOT GObject_FIND_QUIETLY)
+ MESSAGE(STATUS "Found GObject libraries: ${GOBJECT_LIBRARIES}")
+ MESSAGE(STATUS "Found GObject includes : ${GOBJECT_INCLUDE_DIR}")
+ ENDIF (NOT GObject_FIND_QUIETLY)
+ELSE (GOBJECT_FOUND)
+ IF (GObject_FIND_REQUIRED)
+ MESSAGE(STATUS "Could NOT find GObject")
+ ENDIF(GObject_FIND_REQUIRED)
+ENDIF (GOBJECT_FOUND)
+
+MARK_AS_ADVANCED(GOBJECT_INCLUDE_DIR GOBJECT_LIBRARIES)
diff --git a/cmake/modules/FindGStreamer.cmake b/cmake/modules/FindGStreamer.cmake
new file mode 100644
index 0000000..f6c5681
--- /dev/null
+++ b/cmake/modules/FindGStreamer.cmake
@@ -0,0 +1,80 @@
+# - Try to find GStreamer
+# Once done this will define
+#
+# GSTREAMER_FOUND - system has GStreamer
+# GSTREAMER_INCLUDE_DIR - the GStreamer include directory
+# GSTREAMER_LIBRARIES - the libraries needed to use GStreamer
+# GSTREAMER_DEFINITIONS - Compiler switches required for using GStreamer
+
+# Copyright (c) 2006, Tim Beaulen <tbscope@gmail.com>
+#
+# Redistribution and use is allowed according to the terms of the BSD license.
+# For details see the accompanying COPYING-CMAKE-SCRIPTS file.
+
+# TODO: Other versions --> GSTREAMER_X_Y_FOUND (Example: GSTREAMER_0_8_FOUND and GSTREAMER_0_10_FOUND etc)
+
+IF (GSTREAMER_INCLUDE_DIR AND GSTREAMER_LIBRARIES AND GSTREAMER_BASE_LIBRARY AND GSTREAMER_INTERFACE_LIBRARY)
+ # in cache already
+ SET(GSTREAMER_FIND_QUIETLY TRUE)
+ELSE (GSTREAMER_INCLUDE_DIR AND GSTREAMER_LIBRARIES AND GSTREAMER_BASE_LIBRARY AND GSTREAMER_INTERFACE_LIBRARY)
+ SET(GSTREAMER_FIND_QUIETLY FALSE)
+ENDIF (GSTREAMER_INCLUDE_DIR AND GSTREAMER_LIBRARIES AND GSTREAMER_BASE_LIBRARY AND GSTREAMER_INTERFACE_LIBRARY)
+
+IF (NOT WIN32)
+ # use pkg-config to get the directories and then use these values
+ # in the FIND_PATH() and FIND_LIBRARY() calls
+ FIND_PACKAGE(PkgConfig)
+ PKG_CHECK_MODULES(PC_GSTREAMER gstreamer-0.10)
+ #MESSAGE(STATUS "DEBUG: GStreamer include directory = ${GSTREAMER_INCLUDE_DIRS}")
+ #MESSAGE(STATUS "DEBUG: GStreamer link directory = ${GSTREAMER_LIBRARY_DIRS}")
+ #MESSAGE(STATUS "DEBUG: GStreamer CFlags = ${GSTREAMER_CFLAGS_OTHER}")
+ SET(GSTREAMER_DEFINITIONS ${PC_GSTREAMER_CFLAGS_OTHER})
+ENDIF (NOT WIN32)
+
+FIND_PATH(GSTREAMER_INCLUDE_DIR gst/gst.h
+ PATHS
+ ${PC_GSTREAMER_INCLUDEDIR}
+ ${PC_GSTREAMER_INCLUDE_DIRS}
+ PATH_SUFFIXES gstreamer-0.10
+ )
+
+FIND_LIBRARY(GSTREAMER_LIBRARIES NAMES gstreamer-0.10
+ PATHS
+ ${PC_GSTREAMER_LIBDIR}
+ ${PC_GSTREAMER_LIBRARY_DIRS}
+ )
+
+FIND_LIBRARY(GSTREAMER_BASE_LIBRARY NAMES gstbase-0.10
+ PATHS
+ ${PC_GSTREAMER_LIBDIR}
+ ${PC_GSTREAMER_LIBRARY_DIRS}
+ )
+
+FIND_LIBRARY(GSTREAMER_INTERFACE_LIBRARY NAMES gstinterfaces-0.10
+ PATHS
+ ${PC_GSTREAMER_LIBDIR}
+ ${PC_GSTREAMER_LIBRARY_DIRS}
+ )
+
+IF (GSTREAMER_INCLUDE_DIR)
+ #MESSAGE(STATUS "DEBUG: Found GStreamer include dir: ${GSTREAMER_INCLUDE_DIR}")
+ELSE (GSTREAMER_INCLUDE_DIR)
+ MESSAGE(STATUS "GStreamer: WARNING: include dir not found")
+ENDIF (GSTREAMER_INCLUDE_DIR)
+
+IF (GSTREAMER_LIBRARIES)
+ #MESSAGE(STATUS "DEBUG: Found GStreamer library: ${GSTREAMER_LIBRARIES}")
+ELSE (GSTREAMER_LIBRARIES)
+ MESSAGE(STATUS "GStreamer: WARNING: library not found")
+ENDIF (GSTREAMER_LIBRARIES)
+
+IF (GSTREAMER_INTERFACE_LIBRARY)
+ #MESSAGE(STATUS "DEBUG: Found GStreamer interface library: ${GSTREAMER_INTERFACE_LIBRARY}")
+ELSE (GSTREAMER_INTERFACE_LIBRARY)
+ MESSAGE(STATUS "GStreamer: WARNING: interface library not found")
+ENDIF (GSTREAMER_INTERFACE_LIBRARY)
+
+INCLUDE(FindPackageHandleStandardArgs)
+FIND_PACKAGE_HANDLE_STANDARD_ARGS(GStreamer DEFAULT_MSG GSTREAMER_LIBRARIES GSTREAMER_INCLUDE_DIR GSTREAMER_BASE_LIBRARY GSTREAMER_INTERFACE_LIBRARY)
+
+MARK_AS_ADVANCED(GSTREAMER_INCLUDE_DIR GSTREAMER_LIBRARIES GSTREAMER_BASE_LIBRARY GSTREAMER_INTERFACE_LIBRARY)
diff --git a/cmake/modules/FindLibPython.py b/cmake/modules/FindLibPython.py
new file mode 100644
index 0000000..0cbd53c
--- /dev/null
+++ b/cmake/modules/FindLibPython.py
@@ -0,0 +1,12 @@
+# Copyright (c) 2007, Simon Edwards <simon@simonzone.com>
+# Redistribution and use is allowed according to the terms of the BSD license.
+# For details see the accompanying COPYING-CMAKE-SCRIPTS file.
+
+import sys
+import distutils.sysconfig
+
+print("exec_prefix:%s" % sys.exec_prefix)
+print("short_version:%s" % sys.version[:3])
+print("long_version:%s" % sys.version.split()[0])
+print("py_inc_dir:%s" % distutils.sysconfig.get_python_inc())
+print("site_packages_dir:%s" % distutils.sysconfig.get_python_lib(plat_specific=1))
diff --git a/cmake/modules/FindLibXml2.cmake b/cmake/modules/FindLibXml2.cmake
new file mode 100644
index 0000000..353be55
--- /dev/null
+++ b/cmake/modules/FindLibXml2.cmake
@@ -0,0 +1,57 @@
+# - Try to find LibXml2
+# Once done this will define
+#
+# LIBXML2_FOUND - System has LibXml2
+# LIBXML2_INCLUDE_DIR - The LibXml2 include directory
+# LIBXML2_LIBRARIES - The libraries needed to use LibXml2
+# LIBXML2_DEFINITIONS - Compiler switches required for using LibXml2
+# LIBXML2_XMLLINT_EXECUTABLE - The XML checking tool xmllint coming with LibXml2
+
+# Copyright (c) 2006, Alexander Neundorf, <neundorf@kde.org>
+#
+# Redistribution and use is allowed according to the terms of the BSD license.
+# For details see the accompanying COPYING-CMAKE-SCRIPTS file.
+
+
+IF (LIBXML2_INCLUDE_DIR AND LIBXML2_LIBRARIES)
+ # in cache already
+ SET(LibXml2_FIND_QUIETLY TRUE)
+ENDIF (LIBXML2_INCLUDE_DIR AND LIBXML2_LIBRARIES)
+
+IF (NOT WIN32)
+ # use pkg-config to get the directories and then use these values
+ # in the FIND_PATH() and FIND_LIBRARY() calls
+ FIND_PACKAGE(PkgConfig)
+ PKG_CHECK_MODULES(PC_LIBXML libxml-2.0)
+ SET(LIBXML2_DEFINITIONS ${PC_LIBXML_CFLAGS_OTHER})
+ENDIF (NOT WIN32)
+
+FIND_PATH(LIBXML2_INCLUDE_DIR libxml/xpath.h
+ HINTS
+ ${PC_LIBXML_INCLUDEDIR}
+ ${PC_LIBXML_INCLUDE_DIRS}
+ PATH_SUFFIXES libxml2
+ )
+
+FIND_LIBRARY(LIBXML2_LIBRARIES NAMES xml2 libxml2
+ HINTS
+ ${PC_LIBXML_LIBDIR}
+ ${PC_LIBXML_LIBRARY_DIRS}
+ )
+
+FIND_PROGRAM(LIBXML2_XMLLINT_EXECUTABLE xmllint)
+# for backwards compat. with KDE 4.0.x:
+SET(XMLLINT_EXECUTABLE "${LIBXML2_XMLLINT_EXECUTABLE}")
+
+IF( NOT LIBXML2_XMLLINT_EXECUTABLE )
+ MESSAGE(STATUS "xmllint program not found. Install it if you want validate generated doc file.")
+ENDIF(NOT LIBXML2_XMLLINT_EXECUTABLE )
+
+
+INCLUDE(FindPackageHandleStandardArgs)
+
+# handle the QUIETLY and REQUIRED arguments and set LIBXML2_FOUND to TRUE if
+# all listed variables are TRUE
+FIND_PACKAGE_HANDLE_STANDARD_ARGS(LibXml2 DEFAULT_MSG LIBXML2_LIBRARIES LIBXML2_INCLUDE_DIR)
+
+MARK_AS_ADVANCED(LIBXML2_INCLUDE_DIR LIBXML2_LIBRARIES LIBXML2_XMLLINT_EXECUTABLE)
diff --git a/cmake/modules/FindPythonLibrary.cmake b/cmake/modules/FindPythonLibrary.cmake
new file mode 100644
index 0000000..2585859
--- /dev/null
+++ b/cmake/modules/FindPythonLibrary.cmake
@@ -0,0 +1,83 @@
+# FindPythonLibrary.cmake
+# ~~~~~~~~~~~~~~~~~~~~~~~
+# Find the Python interpreter and related Python directories.
+#
+# This file defines the following variables:
+#
+# PYTHON_EXECUTABLE - The path and filename of the Python interpreter.
+#
+# PYTHON_SHORT_VERSION - The version of the Python interpreter found,
+# excluding the patch version number. (e.g. 2.5 and not 2.5.1))
+#
+# PYTHON_LONG_VERSION - The version of the Python interpreter found as a human
+# readable string.
+#
+# PYTHON_SITE_PACKAGES_DIR - Location of the Python site-packages directory.
+#
+# PYTHON_INCLUDE_PATH - Directory holding the python.h include file.
+#
+# PYTHON_LIBRARY, PYTHON_LIBRARIES- Location of the Python library.
+
+# Copyright (c) 2007, Simon Edwards <simon@simonzone.com>
+# Redistribution and use is allowed according to the terms of the BSD license.
+# For details see the accompanying COPYING-CMAKE-SCRIPTS file.
+
+INCLUDE(CMakeFindFrameworks)
+
+if(EXISTS PYTHON_LIBRARY)
+ # Already in cache, be silent
+ set(PYTHONLIBRARY_FOUND TRUE)
+else(EXISTS PYTHON_LIBRARY)
+ FIND_PACKAGE(PythonInterp)
+
+ if(PYTHONINTERP_FOUND)
+ FIND_FILE(_find_lib_python_py FindLibPython.py PATHS ${CMAKE_MODULE_PATH})
+
+ EXECUTE_PROCESS(COMMAND ${PYTHON_EXECUTABLE} ${_find_lib_python_py} OUTPUT_VARIABLE python_config)
+ if(python_config)
+ STRING(REGEX REPLACE ".*exec_prefix:([^\n]+).*$" "\\1" PYTHON_PREFIX ${python_config})
+ STRING(REGEX REPLACE ".*\nshort_version:([^\n]+).*$" "\\1" PYTHON_SHORT_VERSION ${python_config})
+ STRING(REGEX REPLACE ".*\nlong_version:([^\n]+).*$" "\\1" PYTHON_LONG_VERSION ${python_config})
+ STRING(REGEX REPLACE ".*\npy_inc_dir:([^\n]+).*$" "\\1" PYTHON_INCLUDE_PATH ${python_config})
+ STRING(REGEX REPLACE ".*\nsite_packages_dir:([^\n]+).*$" "\\1" PYTHON_SITE_PACKAGES_DIR ${python_config})
+ STRING(REGEX REPLACE "([0-9]+).([0-9]+)" "\\1\\2" PYTHON_SHORT_VERSION_NO_DOT ${PYTHON_SHORT_VERSION})
+ set(PYTHON_LIBRARY_NAMES python${PYTHON_SHORT_VERSION} python${PYTHON_SHORT_VERSION_NO_DOT})
+ if(WIN32)
+ STRING(REPLACE "\\" "/" PYTHON_SITE_PACKAGES_DIR ${PYTHON_SITE_PACKAGES_DIR})
+ endif(WIN32)
+ FIND_LIBRARY(PYTHON_LIBRARY NAMES ${PYTHON_LIBRARY_NAMES} PATHS ${PYTHON_PREFIX}/lib ${PYTHON_PREFIX}/libs NO_DEFAULT_PATH)
+ set(PYTHONLIBRARY_FOUND TRUE)
+ endif(python_config)
+
+ # adapted from cmake's builtin FindPythonLibs
+ if(APPLE)
+ CMAKE_FIND_FRAMEWORKS(Python)
+ set(PYTHON_FRAMEWORK_INCLUDES)
+ if(Python_FRAMEWORKS)
+ # If a framework has been selected for the include path,
+ # make sure "-framework" is used to link it.
+ if("${PYTHON_INCLUDE_PATH}" MATCHES "Python\\.framework")
+ set(PYTHON_LIBRARY "")
+ set(PYTHON_DEBUG_LIBRARY "")
+ endif("${PYTHON_INCLUDE_PATH}" MATCHES "Python\\.framework")
+ if(NOT PYTHON_LIBRARY)
+ set (PYTHON_LIBRARY "-framework Python" CACHE FILEPATH "Python Framework" FORCE)
+ endif(NOT PYTHON_LIBRARY)
+ set(PYTHONLIBRARY_FOUND TRUE)
+ endif(Python_FRAMEWORKS)
+ endif(APPLE)
+ endif(PYTHONINTERP_FOUND)
+
+ if(PYTHONLIBRARY_FOUND)
+ set(PYTHON_LIBRARIES ${PYTHON_LIBRARY})
+ if(NOT PYTHONLIBRARY_FIND_QUIETLY)
+ message(STATUS "Found Python executable: ${PYTHON_EXECUTABLE}")
+ message(STATUS "Found Python version: ${PYTHON_LONG_VERSION}")
+ endif(NOT PYTHONLIBRARY_FIND_QUIETLY)
+ else(PYTHONLIBRARY_FOUND)
+ if(PYTHONLIBRARY_FIND_REQUIRED)
+ message(FATAL_ERROR "Could not find Python")
+ endif(PYTHONLIBRARY_FIND_REQUIRED)
+ endif(PYTHONLIBRARY_FOUND)
+
+endif (EXISTS PYTHON_LIBRARY)
diff --git a/cmake/modules/FindTelepathyFarsight.cmake b/cmake/modules/FindTelepathyFarsight.cmake
new file mode 100644
index 0000000..65215d6
--- /dev/null
+++ b/cmake/modules/FindTelepathyFarsight.cmake
@@ -0,0 +1,49 @@
+# - Try to find Telepathy-Farsight
+# Once done this will define
+#
+# TELEPATHY_FARSIGHT_FOUND - system has TelepathyFarsight
+# TELEPATHY_FARSIGHT_INCLUDE_DIR - the TelepathyFarsight include directory
+# TELEPATHY_FARSIGHT_LIBRARIES - the libraries needed to use TelepathyFarsight
+# TELEPATHY_FARSIGHT_DEFINITIONS - Compiler switches required for using TelepathyFarsight
+
+# Copyright (c) 2010, Dario Freddi <dario.freddi@collabora.co.uk>
+#
+# Redistribution and use is allowed according to the terms of the BSD license.
+
+if (TELEPATHY_FARSIGHT_INCLUDE_DIR AND TELEPATHY_FARSIGHT_LIBRARIES)
+ # in cache already
+ set(TelepathyFarsight_FIND_QUIETLY TRUE)
+else (TELEPATHY_FARSIGHT_INCLUDE_DIR AND TELEPATHY_FARSIGHT_LIBRARIES)
+ set(TelepathyFarsight_FIND_QUIETLY FALSE)
+endif (TELEPATHY_FARSIGHT_INCLUDE_DIR AND TELEPATHY_FARSIGHT_LIBRARIES)
+
+if (NOT WIN32)
+ # use pkg-config to get the directories and then use these values
+ # in the find_path() and find_library() calls
+ find_package(PkgConfig)
+ if (TELEPATHY_FARSIGHT_MIN_VERSION)
+ PKG_CHECK_MODULES(PC_TELEPATHY_FARSIGHT telepathy-farsight>=${TELEPATHY_FARSIGHT_MIN_VERSION})
+ else (TELEPATHY_FARSIGHT_MIN_VERSION)
+ PKG_CHECK_MODULES(PC_TELEPATHY_FARSIGHT telepathy-farsight)
+ endif (TELEPATHY_FARSIGHT_MIN_VERSION)
+ set(TELEPATHY_FARSIGHT_DEFINITIONS ${PC_TELEPATHY_FARSIGHT_CFLAGS_OTHER})
+endif (NOT WIN32)
+
+find_path(TELEPATHY_FARSIGHT_INCLUDE_DIR telepathy-farsight/channel.h
+ PATHS
+ ${PC_TELEPATHY_FARSIGHT_INCLUDEDIR}
+ ${PC_TELEPATHY_FARSIGHT_INCLUDE_DIRS}
+ PATH_SUFFIXES telepathy-1.0
+ )
+
+find_library(TELEPATHY_FARSIGHT_LIBRARIES NAMES telepathy-farsight
+ PATHS
+ ${PC_TELEPATHY_FARSIGHT_LIBDIR}
+ ${PC_TELEPATHY_FARSIGHT_LIBRARY_DIRS}
+ )
+
+include(FindPackageHandleStandardArgs)
+find_package_handle_standard_args(TelepathyFarsight DEFAULT_MSG TELEPATHY_FARSIGHT_LIBRARIES
+ TELEPATHY_FARSIGHT_INCLUDE_DIR)
+
+mark_as_advanced(TELEPATHY_FARSIGHT_INCLUDE_DIR TELEPATHY_FARSIGHT_LIBRARIES)
diff --git a/cmake/modules/FindTelepathyGlib.cmake b/cmake/modules/FindTelepathyGlib.cmake
new file mode 100644
index 0000000..8728dab
--- /dev/null
+++ b/cmake/modules/FindTelepathyGlib.cmake
@@ -0,0 +1,54 @@
+# - Try to find Telepathy-Glib
+# Once done this will define
+#
+# TELEPATHY_GLIB_FOUND - system has Telepathy-Glib
+# TELEPATHY_GLIB_INCLUDE_DIR - the Telepathy-Glib include directory
+# TELEPATHY_GLIB_LIBRARIES - the libraries needed to use Telepathy-Glib
+# TELEPATHY_GLIB_DEFINITIONS - Compiler switches required for using Telepathy-Glib
+
+# Copyright (c) 2010, Dario Freddi <dario.freddi@collabora.co.uk>
+#
+# Redistribution and use is allowed according to the terms of the BSD license.
+
+if (TELEPATHY_GLIB_INCLUDE_DIR AND TELEPATHY_GLIB_LIBRARIES)
+ # in cache already
+ set(TELEPATHYGLIB_FIND_QUIETLY TRUE)
+else (TELEPATHY_GLIB_INCLUDE_DIR AND TELEPATHY_GLIB_LIBRARIES)
+ set(TELEPATHYGLIB_FIND_QUIETLY FALSE)
+endif (TELEPATHY_GLIB_INCLUDE_DIR AND TELEPATHY_GLIB_LIBRARIES)
+
+if (NOT WIN32)
+ # use pkg-config to get the directories and then use these values
+ # in the find_path() and find_library() calls
+ find_package(PkgConfig)
+ if (TELEPATHY_GLIB_MIN_VERSION)
+ PKG_CHECK_MODULES(PC_TELEPATHY_GLIB telepathy-glib>=${TELEPATHY_GLIB_MIN_VERSION})
+ else (TELEPATHY_GLIB_MIN_VERSION)
+ PKG_CHECK_MODULES(PC_TELEPATHY_GLIB telepathy-glib)
+ endif (TELEPATHY_GLIB_MIN_VERSION)
+ set(TELEPATHY_GLIB_DEFINITIONS ${PC_TELEPATHY_GLIB_CFLAGS_OTHER})
+endif (NOT WIN32)
+
+if (TELEPATHY_GLIB_MIN_VERSION AND PKG_CONFIG_FOUND AND NOT PC_TELEPATHY_GLIB_FOUND)
+ message(STATUS "Telepathy-glib not found or its version is < ${TELEPATHY_GLIB_MIN_VERSION}")
+else (TELEPATHY_GLIB_MIN_VERSION AND PKG_CONFIG_FOUND AND NOT PC_TELEPATHY_GLIB_FOUND)
+ find_path(TELEPATHY_GLIB_INCLUDE_DIR telepathy-glib/client.h
+ PATHS
+ ${PC_TELEPATHY_GLIB_INCLUDEDIR}
+ ${PC_TELEPATHY_GLIB_INCLUDE_DIRS}
+ PATH_SUFFIXES telepathy-1.0
+ )
+
+ find_library(TELEPATHY_GLIB_LIBRARIES NAMES telepathy-glib
+ PATHS
+ ${PC_TELEPATHY_GLIB_LIBDIR}
+ ${PC_TELEPATHY_GLIB_LIBRARY_DIRS}
+ )
+
+ include(FindPackageHandleStandardArgs)
+ find_package_handle_standard_args(TelepathyGlib DEFAULT_MSG TELEPATHY_GLIB_LIBRARIES
+ TELEPATHY_GLIB_INCLUDE_DIR)
+
+ mark_as_advanced(TELEPATHY_GLIB_INCLUDE_DIR TELEPATHY_GLIB_LIBRARIES)
+
+endif (TELEPATHY_GLIB_MIN_VERSION AND PKG_CONFIG_FOUND AND NOT PC_TELEPATHY_GLIB_FOUND)
diff --git a/cmake/modules/FindTelepathyQt4.cmake b/cmake/modules/FindTelepathyQt4.cmake
new file mode 100644
index 0000000..b5105df
--- /dev/null
+++ b/cmake/modules/FindTelepathyQt4.cmake
@@ -0,0 +1,28 @@
+# Try to find the Qt binding of the Telepathy library
+# TELEPATHY_QT_FOUND - system has Telepathy-Qt
+# TELEPATHY_QT_INCLUDE_DIR - the Telepathy-Qt include directory
+# TELEPATHY_QT_LIBRARIES - Link these to use Telepathy-Qt
+
+# Copyright (c) 2008, Allen Winter <winter@kde.org>
+#
+# Redistribution and use is allowed according to the terms of the BSD license.
+# For details see the accompanying COPYING-CMAKE-SCRIPTS file.
+
+set (TELEPATHY_QT4_FIND_REQUIRED ${TelepathyQt4_FIND_REQUIRED})
+if (TELEPATHY_QT4_INCLUDE_DIR AND TELEPATHY_QT4_LIBRARIES)
+ # Already in cache, be silent
+ set (TELEPATHY_QT4_FIND_QUIETLY TRUE)
+endif (TELEPATHY_QT4_INCLUDE_DIR AND TELEPATHY_QT4_LIBRARIES)
+
+find_path (TELEPATHY_QT4_INCLUDE_DIR
+ NAMES TelepathyQt4/Client/Channel TelepathyQt4/Client/Connection TelepathyQt4/Types
+ PATHS ${CMAKE_INSTALL_PREFIX}/include/telepathy-1.0
+)
+find_library (TELEPATHY_QT4_LIBRARIES
+ NAMES telepathy-qt4
+ PATHS ${CMAKE_INSTALL_PREFIX}/lib
+)
+
+include (FindPackageHandleStandardArgs)
+FIND_PACKAGE_HANDLE_STANDARD_ARGS (TELEPATHY_QT4 DEFAULT_MSG
+ TELEPATHY_QT4_LIBRARIES TELEPATHY_QT4_INCLUDE_DIR)
diff --git a/cmake/modules/MacroLogFeature.cmake b/cmake/modules/MacroLogFeature.cmake
new file mode 100644
index 0000000..86e1c3c
--- /dev/null
+++ b/cmake/modules/MacroLogFeature.cmake
@@ -0,0 +1,146 @@
+# This file defines the Feature Logging macros.
+#
+# MACRO_LOG_FEATURE(VAR FEATURE DESCRIPTION URL [REQUIRED [MIN_VERSION [COMMENTS]]])
+# Logs the information so that it can be displayed at the end
+# of the configure run
+# VAR : TRUE or FALSE, indicating whether the feature is supported
+# FEATURE: name of the feature, e.g. "libjpeg"
+# DESCRIPTION: description what this feature provides
+# URL: home page
+# REQUIRED: TRUE or FALSE, indicating whether the featue is required
+# MIN_VERSION: minimum version number. empty string if unneeded
+# COMMENTS: More info you may want to provide. empty string if unnecessary
+#
+# MACRO_DISPLAY_FEATURE_LOG()
+# Call this to display the collected results.
+# Exits CMake with a FATAL error message if a required feature is missing
+#
+# Example:
+#
+# INCLUDE(MacroLogFeature)
+#
+# FIND_PACKAGE(JPEG)
+# MACRO_LOG_FEATURE(JPEG_FOUND "libjpeg" "Support JPEG images" "http://www.ijg.org" TRUE "3.2a" "")
+# ...
+# MACRO_DISPLAY_FEATURE_LOG()
+
+# Copyright (c) 2006, Alexander Neundorf, <neundorf@kde.org>
+# Copyright (c) 2006, Allen Winter, <winter@kde.org>
+# Copyright (c) 2009, Sebastian Trueg, <trueg@kde.org>
+#
+# Redistribution and use is allowed according to the terms of the BSD license.
+# For details see the accompanying COPYING-CMAKE-SCRIPTS file.
+
+IF (NOT _macroLogFeatureAlreadyIncluded)
+ SET(_file ${CMAKE_BINARY_DIR}/MissingRequirements.txt)
+ IF (EXISTS ${_file})
+ FILE(REMOVE ${_file})
+ ENDIF (EXISTS ${_file})
+
+ SET(_file ${CMAKE_BINARY_DIR}/EnabledFeatures.txt)
+ IF (EXISTS ${_file})
+ FILE(REMOVE ${_file})
+ ENDIF (EXISTS ${_file})
+
+ SET(_file ${CMAKE_BINARY_DIR}/DisabledFeatures.txt)
+ IF (EXISTS ${_file})
+ FILE(REMOVE ${_file})
+ ENDIF (EXISTS ${_file})
+
+ SET(_macroLogFeatureAlreadyIncluded TRUE)
+ENDIF (NOT _macroLogFeatureAlreadyIncluded)
+
+
+MACRO(MACRO_LOG_FEATURE _var _package _description _url ) # _required _minvers _comments)
+
+ STRING(TOUPPER "${ARGV4}" _required)
+ SET(_minvers "${ARGV5}")
+ SET(_comments "${ARGV6}")
+
+ IF (${_var})
+ SET(_LOGFILENAME ${CMAKE_BINARY_DIR}/EnabledFeatures.txt)
+ ELSE (${_var})
+ IF ("${_required}" STREQUAL "TRUE")
+ SET(_LOGFILENAME ${CMAKE_BINARY_DIR}/MissingRequirements.txt)
+ ELSE ("${_required}" STREQUAL "TRUE")
+ SET(_LOGFILENAME ${CMAKE_BINARY_DIR}/DisabledFeatures.txt)
+ ENDIF ("${_required}" STREQUAL "TRUE")
+ ENDIF (${_var})
+
+ SET(_logtext " * ${_package}")
+
+ IF (NOT ${_var})
+ IF (${_minvers} MATCHES ".*")
+ SET(_logtext "${_logtext} (${_minvers} or higher)")
+ ENDIF (${_minvers} MATCHES ".*")
+ SET(_logtext "${_logtext} <${_url}>\n ")
+ ELSE (NOT ${_var})
+ SET(_logtext "${_logtext} - ")
+ ENDIF (NOT ${_var})
+
+ SET(_logtext "${_logtext}${_description}")
+
+ IF (NOT ${_var})
+ IF (${_comments} MATCHES ".*")
+ SET(_logtext "${_logtext}\n ${_comments}")
+ ENDIF (${_comments} MATCHES ".*")
+# SET(_logtext "${_logtext}\n") #double-space missing features?
+ ENDIF (NOT ${_var})
+
+ FILE(APPEND "${_LOGFILENAME}" "${_logtext}\n")
+
+ENDMACRO(MACRO_LOG_FEATURE)
+
+
+MACRO(MACRO_DISPLAY_FEATURE_LOG)
+
+ SET(_missingFile ${CMAKE_BINARY_DIR}/MissingRequirements.txt)
+ SET(_enabledFile ${CMAKE_BINARY_DIR}/EnabledFeatures.txt)
+ SET(_disabledFile ${CMAKE_BINARY_DIR}/DisabledFeatures.txt)
+
+ IF (EXISTS ${_missingFile} OR EXISTS ${_enabledFile} OR EXISTS ${_disabledFile})
+ SET(_printSummary TRUE)
+ ENDIF (EXISTS ${_missingFile} OR EXISTS ${_enabledFile} OR EXISTS ${_disabledFile})
+
+ IF(_printSummary)
+ SET(_missingDeps 0)
+ IF (EXISTS ${_enabledFile})
+ FILE(READ ${_enabledFile} _enabled)
+ FILE(REMOVE ${_enabledFile})
+ SET(_summary "${_summary}\n-----------------------------------------------------------------------------\n-- The following external packages were located on your system.\n-- This installation will have the extra features provided by these packages.\n-----------------------------------------------------------------------------\n${_enabled}")
+ ENDIF (EXISTS ${_enabledFile})
+
+
+ IF (EXISTS ${_disabledFile})
+ SET(_missingDeps 1)
+ FILE(READ ${_disabledFile} _disabled)
+ FILE(REMOVE ${_disabledFile})
+ SET(_summary "${_summary}\n-----------------------------------------------------------------------------\n-- The following OPTIONAL packages could NOT be located on your system.\n-- Consider installing them to enable more features from this software.\n-----------------------------------------------------------------------------\n${_disabled}")
+ ENDIF (EXISTS ${_disabledFile})
+
+
+ IF (EXISTS ${_missingFile})
+ SET(_missingDeps 1)
+ FILE(READ ${_missingFile} _requirements)
+ SET(_summary "${_summary}\n-----------------------------------------------------------------------------\n-- The following REQUIRED packages could NOT be located on your system.\n-- You must install these packages before continuing.\n-----------------------------------------------------------------------------\n${_requirements}")
+ FILE(REMOVE ${_missingFile})
+ SET(_haveMissingReq 1)
+ ENDIF (EXISTS ${_missingFile})
+
+
+ IF (NOT ${_missingDeps})
+ SET(_summary "${_summary}\n-----------------------------------------------------------------------------\n-- Congratulations! All external packages have been found.")
+ ENDIF (NOT ${_missingDeps})
+
+
+ MESSAGE(${_summary})
+ MESSAGE("-----------------------------------------------------------------------------\n")
+
+
+ IF(_haveMissingReq)
+ MESSAGE(FATAL_ERROR "Exiting: Missing Requirements")
+ ENDIF(_haveMissingReq)
+
+ ENDIF(_printSummary)
+
+ENDMACRO(MACRO_DISPLAY_FEATURE_LOG)
diff --git a/cmake/modules/TelepathyDefaults.cmake b/cmake/modules/TelepathyDefaults.cmake
new file mode 100644
index 0000000..1e70ef3
--- /dev/null
+++ b/cmake/modules/TelepathyDefaults.cmake
@@ -0,0 +1,137 @@
+# Enable testing using CTest
+enable_testing()
+
+# Always include srcdir and builddir in include path
+# This saves typing ${CMAKE_CURRENT_SOURCE_DIR} ${CMAKE_CURRENT_BINARY_DIR} in about every subdir
+set(CMAKE_INCLUDE_CURRENT_DIR ON)
+
+# put the include dirs which are in the source or build tree
+# before all other include dirs, so the headers in the sources
+# are prefered over the already installed ones
+set(CMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE ON)
+
+# Use colored output
+set(CMAKE_COLOR_MAKEFILE ON)
+
+# Set compiler flags
+if(CMAKE_COMPILER_IS_GNUCXX)
+ set(CMAKE_CXX_FLAGS_RELWITHDEBINFO "-O2 -ggdb")
+ set(CMAKE_CXX_FLAGS_RELEASE "-O2 -DNDEBUG")
+ set(CMAKE_CXX_FLAGS_DEBUG "-ggdb -O2 -fno-reorder-blocks -fno-schedule-insns -fno-inline")
+ set(CMAKE_CXX_FLAGS_DEBUGFULL "-O0 -g3 -ggdb -fno-inline")
+ set(CMAKE_CXX_FLAGS_PROFILE "-pg -g3 -ggdb -DNDEBUG")
+
+ set(CMAKE_C_FLAGS_RELWITHDEBINFO "-O2 -ggdb")
+ set(CMAKE_C_FLAGS_RELEASE "-O2 -DNDEBUG")
+ set(CMAKE_C_FLAGS_DEBUG "-ggdb -O2 -fno-reorder-blocks -fno-schedule-insns -fno-inline")
+ set(CMAKE_C_FLAGS_DEBUGFULL "-O0 -g3 -ggdb -fno-inline")
+ set(CMAKE_C_FLAGS_PROFILE "-pg -g3 -ggdb -DNDEBUG")
+
+ set(CMAKE_EXE_LINKER_FLAGS_PROFILE "-pg -ggdb")
+ set(CMAKE_SHARED_LINKER_FLAGS_PROFILE "-pg -ggdb")
+
+ set(DISABLE_WERROR 0 CACHE BOOL "compile without -Werror (normally enabled in development builds)")
+
+ include(CompilerWarnings)
+ include(TestCXXAcceptsFlag)
+
+ CHECK_CXX_ACCEPTS_FLAG("-fvisibility=hidden" CXX_FVISIBILITY_HIDDEN)
+ if (CXX_FVISIBILITY_HIDDEN)
+ set(VISIBILITY_HIDDEN_FLAGS "-fvisibility=hidden")
+ else (CXX_FVISIBILITY_HIDDEN)
+ set(VISIBILITY_HIDDEN_FLAGS)
+ endif (CXX_FVISIBILITY_HIDDEN)
+
+ CHECK_CXX_ACCEPTS_FLAG("-Wdeprecated-declarations" CXX_DEPRECATED_DECLARATIONS)
+ if (CXX_DEPRECATED_DECLARATIONS)
+ set(DEPRECATED_DECLARATIONS_FLAGS "-Wdeprecated-declarations")
+ else (CXX_DEPRECATED_DECLARATIONS)
+ set(DEPRECATED_DECLARATIONS_FLAGS)
+ endif (CXX_DEPRECATED_DECLARATIONS)
+
+ if(${CMAKE_BUILD_TYPE} STREQUAL Release)
+ set(NOT_RELEASE 0)
+ else(${CMAKE_BUILD_TYPE} STREQUAL Release)
+ set(NOT_RELEASE 1)
+ endif(${CMAKE_BUILD_TYPE} STREQUAL Release)
+
+ set(desired
+ all
+ extra
+ sign-compare
+ pointer-arith
+ format-security
+ init-self
+ non-virtual-dtor)
+ set(undesired
+ missing-field-initializers
+ unused-parameter)
+ compiler_warnings(CMAKE_CXX_FLAGS_WARNINGS cxx ${NOT_RELEASE} "${desired}" "${undesired}")
+ set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${CMAKE_CXX_FLAGS_WARNINGS}")
+
+ set(desired_c
+ all
+ extra
+ declaration-after-statement
+ shadow
+ strict-prototypes
+ missing-prototypes
+ sign-compare
+ nested-externs
+ pointer-arith
+ format-security
+ init-self)
+ set(undesired_c
+ missing-field-initializers
+ unused-parameter)
+ compiler_warnings(CMAKE_C_FLAGS_WARNINGS c ${NOT_RELEASE} "${desired_c}" "${undesired_c}")
+ set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} ${CMAKE_C_FLAGS_WARNINGS}")
+
+ if(CMAKE_SYSTEM_NAME MATCHES Linux)
+ add_definitions(-D_BSD_SOURCE)
+ endif(CMAKE_SYSTEM_NAME MATCHES Linux)
+
+ # Compiler coverage
+ set(ENABLE_COMPILER_COVERAGE OFF CACHE BOOL "Enables compiler coverage tests through lcov. Enabling this option will build the library as a static library.")
+
+ if (ENABLE_COMPILER_COVERAGE)
+ check_cxx_accepts_flag("-fprofile-arcs -ftest-coverage" CXX_FPROFILE_ARCS)
+ check_cxx_accepts_flag("-ftest-coverage" CXX_FTEST_COVERAGE)
+
+ if (CXX_FPROFILE_ARCS AND CXX_FTEST_COVERAGE)
+ find_program(LCOV lcov)
+ find_program(LCOV_GENHTML genhtml)
+ if (NOT LCOV OR NOT LCOV_GENHTML)
+ message(FATAL_ERROR "You chose to use compiler coverage tests, but lcov or genhtml could not be found in your PATH.")
+ else (NOT LCOV OR NOT LCOV_GENHTML)
+ message(STATUS "Compiler coverage tests enabled - the library will be compiled as a static library")
+ set(COMPILER_COVERAGE_FLAGS "-fprofile-arcs -ftest-coverage")
+ endif (NOT LCOV OR NOT LCOV_GENHTML)
+ else (CXX_FPROFILE_ARCS AND CXX_FTEST_COVERAGE)
+ message(FATAL_ERROR "You chose to use compiler coverage tests, but it appears your compiler is not able to support them.")
+ endif (CXX_FPROFILE_ARCS AND CXX_FTEST_COVERAGE)
+ else (ENABLE_COMPILER_COVERAGE)
+ set(COMPILER_COVERAGE_FLAGS)
+ endif (ENABLE_COMPILER_COVERAGE)
+
+ # gcc under Windows
+ if(MINGW)
+ set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} -Wl,--export-all-symbols -Wl,--disable-auto-import")
+ set(CMAKE_MODULE_LINKER_FLAGS "${CMAKE_MODULE_LINKER_FLAGS} -Wl,--export-all-symbols -Wl,--disable-auto-import")
+
+ # we always link against the release version of QT with mingw
+ # (even for debug builds). So we need to define QT_NO_DEBUG
+ # or else QPluginLoader rejects plugins because it thinks
+ # they're built against the wrong QT.
+ add_definitions(-DQT_NO_DEBUG)
+ endif(MINGW)
+endif(CMAKE_COMPILER_IS_GNUCXX)
+
+if(MSVC)
+ set(ESCAPE_CHAR ^)
+endif(MSVC)
+
+set(LIB_SUFFIX "" CACHE STRING "Define suffix of library directory name (32/64)" )
+set(LIB_INSTALL_DIR "lib${LIB_SUFFIX}" CACHE PATH "The subdirectory where libraries will be installed (default is ${CMAKE_INSTALL_PREFIX}/lib${LIB_SUFFIX})" FORCE)
+set(INCLUDE_INSTALL_DIR "include" CACHE PATH "The subdirectory where header files will be installed (default is ${CMAKE_INSTALL_PREFIX}/include)" FORCE)
+set(DATA_INSTALL_DIR "share/telepathy" CACHE PATH "The subdirectory where data files will be installed (default is ${CMAKE_INSTALL_PREFIX}/share/telepathy)" FORCE)
diff --git a/cmake/modules/TelepathyDist.cmake b/cmake/modules/TelepathyDist.cmake
new file mode 100644
index 0000000..d2cd475
--- /dev/null
+++ b/cmake/modules/TelepathyDist.cmake
@@ -0,0 +1,39 @@
+# setup make dist
+add_custom_command(OUTPUT ${CMAKE_BINARY_DIR}/${PACKAGE_NAME}-${PACKAGE_VERSION}.tar.gz
+ COMMAND git archive --format=tar --prefix=${PACKAGE_NAME}-${PACKAGE_VERSION}/ HEAD |
+ gzip > ${CMAKE_BINARY_DIR}/${PACKAGE_NAME}-${PACKAGE_VERSION}.tar.gz
+ WORKING_DIRECTORY ${CMAKE_SOURCE_DIR})
+
+add_custom_target(create-source-working-dir
+ rm -rf ${PACKAGE_NAME}-${PACKAGE_VERSION} &&
+ gzip -df ${PACKAGE_NAME}-${PACKAGE_VERSION}.tar.gz &&
+ tar -xf ${PACKAGE_NAME}-${PACKAGE_VERSION}.tar &&
+ rm ${PACKAGE_NAME}-${PACKAGE_VERSION}.tar* &&
+ cd ${PACKAGE_NAME}-${PACKAGE_VERSION}/ &&
+ rm -rf doc && mkdir doc && cp -R ${CMAKE_BINARY_DIR}/doc/html doc/
+
+ WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
+ DEPENDS ${CMAKE_BINARY_DIR}/${PACKAGE_NAME}-${PACKAGE_VERSION}.tar.gz
+ COMMENT "Generating working source dir for the dist tarball")
+add_dependencies(create-source-working-dir doxygen-doc)
+
+add_custom_target(dist-hook
+ chmod u+w ${CMAKE_BINARY_DIR}/${PACKAGE_NAME}-${PACKAGE_VERSION}/ChangeLog &&
+ git log --stat > ${CMAKE_BINARY_DIR}/${PACKAGE_NAME}-${PACKAGE_VERSION}/ChangeLog ||
+ git log > ${CMAKE_BINARY_DIR}/${PACKAGE_NAME}-${PACKAGE_VERSION}/ChangeLog
+
+ WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
+ COMMENT "Updating Changelog")
+add_dependencies(dist-hook create-source-working-dir)
+
+add_custom_target(dist tar --format=ustar -chf - ${PACKAGE_NAME}-${PACKAGE_VERSION} |
+ GZIP=--best gzip -c > ${PACKAGE_NAME}-${PACKAGE_VERSION}.tar.gz
+ WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
+ COMMENT "Generating dist tarball")
+add_dependencies(dist dist-hook)
+
+# setup make distcheck
+add_custom_target(distcheck rm -rf build && mkdir build && cd build && cmake .. && make && make check
+ WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/${PACKAGE_NAME}-${PACKAGE_VERSION}/
+ COMMENT "Testing successful tarball build")
+add_dependencies(distcheck dist)
diff --git a/cmake/modules/TpQt4Macros.cmake b/cmake/modules/TpQt4Macros.cmake
new file mode 100644
index 0000000..4f188ce
--- /dev/null
+++ b/cmake/modules/TpQt4Macros.cmake
@@ -0,0 +1,428 @@
+# - Common macros for Tp-Qt4
+
+# Copyright (c) 2010, Collabora Ltd. <http://www.collabora.co.uk/>
+#
+# Redistribution and use is allowed according to the terms of the BSD license.
+
+#
+# These macros/functions are not exported - they are meant for internal usage into Telepathy-Qt4's build system.
+#
+# Preamble: How dynamic generators are handled with the CMake build system.
+# Telepathy-Qt4 strongly relies upon lots of files generated at build time through some python programs, found
+# in tools/. To avoid developers the struggle of handling those manually, a set of convenience macros have been
+# created to handle them with the correct dependencies. Each of those macros takes a target name as a first argument
+# and creates a target with that exact name. In a similar fashion, in the last argument you can specify a list
+# of targets the generated target will depend on. This way, you can handle transparently dependencies between
+# generated files, while the dirty stuff is done for you in the background.
+#
+# macro TPQT4_EXTRACT_DEPENDS (tpqt4_other tpqt4_depends)
+# Internal macro used to extract arguments from ARGN
+#
+# function TPQT4_CREATE_MOC_COMMAND_TARGET_DEPS(inputfile outputfile moc_flags moc_options target_dependencies ...)
+# This function behaves exactly like qt4_create_moc_command, but creates a custom target for the
+# moc file generation, allowing to specify a list of targets the generated moc target will depend on.
+# Just like qt4_create_moc_command, it is an internal macro and it's not meant to be used explicitely.
+#
+# function TPQT4_GENERATE_MOC_I(inputfile outputfile)
+# This function behaves exactly like qt4_generate_moc, but it generates moc files with the -i option,
+# which disables the generation of an #include directive. This macro has to be used always when building
+# library internals due to the internal header files restrictions.
+#
+# function TPQT4_GENERATE_MOC_I_TARGET_DEPS(inputfile outputfile target_dependencies ...)
+# This function acts as an overload to QT4_GENERATE_MOC_I: it does exactly the same thing, but creates a
+# custom target for the moc file generation, and adds target_dependencies to it as dependencies.
+#
+# function TPQT4_GENERATE_MOCS(sourcefile ...)
+# Generates mocs from a list of header files. You usually want to use this function when building tests
+# or examples. Please remember the list of the header files passed to this function MUST be added to the
+# target's sources.
+#
+# function TPQT4_CLIENT_GENERATOR(spec_xml spec group real_include pretty_include namespace types_namespace must_define visibility [arguments] [DEPENDS dependencies ...])
+# This function takes care of invoking qt4-client-gen.py with the correct arguments, which generates
+# headers out of specs. spec is the name of the spec headers will be generated from, group represents
+# the spec's group, pretty_include is the name of the capitalized header (for example ClientGenerator),
+# namespace is the C++ namespace the generated header will belong to. This function also accepts
+# as an optional last argument a list of additional command line arguments which will be passed to
+# qt4-client-gen.py upon execution. After issuing DEPENDS in the last argument you can pass a list of targets
+# the generated target will depend on.
+#
+# function TPQT4_FUTURE_CLIENT_GENERATOR(future_spec_xml spec real_include pretty_include namespace types_namespace visibility [arguments] [DEPENDS dependencies ...])
+# Same as tpqt4_client_generator, but for future interfaces
+#
+# function TPQT4_GENERATE_MANAGER_FILE(MANAGER_FILE OUTPUT_FILENAME DEPEND_FILENAME)
+# This function takes care of invoking manager-file.py with the correct arguments. The first argument is the
+# path to the manager-file.py file which should be used, the second is the output filename of the manager,
+# and the third is the path to the file which depends on the generated manager file.
+#
+# function TPQT4_XINCLUDATOR (TARGET_NAME INPUT_FILE OUTPUT_FILE [additional_arguments ...] [DEPENDS dependencies ...])
+# This function takes care of invoking xincludator.py with the correct arguments. TARGET_NAME is the name of
+# the generated target (see preamble), INPUT_FILE is the input spec file, OUTPUT_FILE is the filename
+# the generated file will be saved to. This function also accepts as an optional last argument a list of
+# additional command line arguments which will be passed to xincludator upon execution.
+# After issuing DEPENDS in the last argument you can pass a list of targets the generated target will depend on.
+#
+# function TPQT4_CONSTANTS_GEN (TARGET_NAME SPEC_XML OUTPUT_FILE [additional_arguments ...] [DEPENDS dependencies ...])
+# This function takes care of invoking qt4-constants-gen.py with the correct arguments. TARGET_NAME is the name of
+# the generated target (see preamble), SPEC_XML is the spec input file, OUTPUT_FILE is the filename
+# the generated file will be saved to. This function also accepts as an optional last argument a list of
+# additional command line arguments which will be passed to qt4-constants-gen.py upon execution.
+# After issuing DEPENDS in the last argument you can pass a list of targets the generated target will depend on.
+#
+# function TPQT4_TYPES_GEN (TARGET_NAME SPEC_XML OUTFILE_DECL OUTFILE_IMPL NAMESPACE
+# REAL_INCLUDE PRETTY_INCLUDE [additional_arguments ...] [DEPENDS dependencies ...])
+# This function takes care of invoking qt4-types-gen.py with the correct arguments. TARGET_NAME is the name of
+# the generated target (see preamble), SPEC_XML is the input spec file, OUTFILE_DECL is the filename
+# the header of the generated file will be saved to, OUTFILE_IMPL is the filename the implementation of the
+# generated file will be saved to, NAMESPACE is the C++ namespace the generated header will belong to,
+# REAL_INCLUDE is the real include file you want to use, PRETTY_INCLUDE is the name of the capitalized header
+# (for example ClientGenerator).
+# This function also accepts as an optional last argument a list of additional command line arguments
+# which will be passed to qt4-constants-gen.py upon execution.
+# After issuing DEPENDS in the last argument you can pass a list of targets the generated target will depend on.
+#
+# macro TPQT4_ADD_GENERIC_UNIT_TEST (fancyName name [libraries ...])
+# This macro takes care of building and adding a generic unit test to the automatic CTest suite. The requirement
+# for using this macro is to have the unit test contained in a single source file named ${name}.cpp. fancyName will
+# be used as the test and target's name, and you can specify as a third and optional argument a set of additional
+# libraries the target will link to.
+#
+# macro TPQT4_ADD_DBUS_UNIT_TEST (fancyName name [libraries ...])
+# This macro takes care of building and adding an unit test requiring DBus emulation to the automatic
+# CTest suite. The requirement for using this macro is to have the unit test contained in a single
+# source file named ${name}.cpp. fancyName will be used as the test and target's name, and you can specify as a third
+# and optional argument a set of additional libraries the target will link to. Please remember that you need to
+# set up the DBus environment by calling TPQT4_SETUP_DBUS_TEST_ENVIRONMENT BEFORE you call this macro.
+#
+# macro _TPQT4_ADD_CHECK_TARGETS (fancyName name command [args])
+# This is an internal macro which is meant to be used by TPQT4_ADD_DBUS_UNIT_TEST and TPQT4_ADD_GENERIC_UNIT_TEST.
+# It takes care of generating a check target for each test method available (currently normal execution, valgrind and
+# callgrind). This macro accepts the same arguments as the add test macros, but accepts a command and a list of
+# arguments for running the test instead of the link libraries. However, you are not meant to call this macro from
+# your CMakeLists.txt files.
+#
+# function TPQT4_SETUP_DBUS_TEST_ENVIRONMENT ()
+# This function MUST be called before calling TPQT4_ADD_DBUS_UNIT_TEST. It takes care of preparing the test
+# environment for DBus tests and generating the needed files.
+#
+
+MACRO (TPQT4_EXTRACT_DEPENDS _tpqt4_other _tpqt4_depends)
+ SET(${_tpqt4_other})
+ SET(${_tpqt4_depends})
+ SET(_TPQT4_DOING_DEPENDS FALSE)
+ FOREACH(_currentArg ${ARGN})
+ IF ("${_currentArg}" STREQUAL "DEPENDS")
+ SET(_TPQT4_DOING_DEPENDS TRUE)
+ ELSE ("${_currentArg}" STREQUAL "DEPENDS")
+ IF(_TPQT4_DOING_DEPENDS)
+ LIST(APPEND ${_tpqt4_depends} "${_currentArg}")
+ ELSE(_TPQT4_DOING_DEPENDS)
+ LIST(APPEND ${_tpqt4_other} "${_currentArg}")
+ ENDIF(_TPQT4_DOING_DEPENDS)
+ ENDIF ("${_currentArg}" STREQUAL "DEPENDS")
+ ENDFOREACH(_currentArg)
+ENDMACRO (TPQT4_EXTRACT_DEPENDS)
+
+# helper function to set up a moc rule
+FUNCTION (TPQT4_CREATE_MOC_COMMAND_TARGET_DEPS infile outfile moc_flags moc_options)
+ # For Windows, create a parameters file to work around command line length limit
+ GET_FILENAME_COMPONENT(_moc_outfile_name "${outfile}" NAME)
+ IF (WIN32)
+ # Pass the parameters in a file. Set the working directory to
+ # be that containing the parameters file and reference it by
+ # just the file name. This is necessary because the moc tool on
+ # MinGW builds does not seem to handle spaces in the path to the
+ # file given with the @ syntax.
+ GET_FILENAME_COMPONENT(_moc_outfile_dir "${outfile}" PATH)
+ IF(_moc_outfile_dir)
+ SET(_moc_working_dir WORKING_DIRECTORY ${_moc_outfile_dir})
+ ENDIF(_moc_outfile_dir)
+ SET (_moc_parameters_file ${outfile}_parameters)
+ SET (_moc_parameters ${moc_flags} ${moc_options} -o "${outfile}" "${infile}")
+ FILE (REMOVE ${_moc_parameters_file})
+ FOREACH(arg ${_moc_parameters})
+ FILE (APPEND ${_moc_parameters_file} "${arg}\n")
+ ENDFOREACH(arg)
+ ADD_CUSTOM_COMMAND(OUTPUT ${outfile}
+ COMMAND ${QT_MOC_EXECUTABLE} @${_moc_outfile_name}_parameters
+ DEPENDS ${infile}
+ ${_moc_working_dir}
+ VERBATIM)
+ ELSE (WIN32)
+ ADD_CUSTOM_COMMAND(OUTPUT ${outfile}
+ COMMAND ${QT_MOC_EXECUTABLE}
+ ARGS ${moc_flags} ${moc_options} -o ${outfile} ${infile}
+ DEPENDS ${infile})
+ ENDIF (WIN32)
+
+ add_custom_target(moc-${_moc_outfile_name} DEPENDS ${outfile})
+ add_dependencies(moc-${_moc_outfile_name} ${ARGN})
+ENDFUNCTION (TPQT4_CREATE_MOC_COMMAND_TARGET_DEPS)
+
+# add the -i option to QT4_GENERATE_MOC
+function(TPQT4_GENERATE_MOC_I infile outfile)
+ qt4_get_moc_flags(moc_flags)
+ get_filename_component(abs_infile ${infile} ABSOLUTE)
+ qt4_create_moc_command(${abs_infile} ${outfile} "${moc_flags}" "-i")
+ set_source_files_properties(${outfile} PROPERTIES SKIP_AUTOMOC TRUE) # dont run automoc on this file
+endfunction(TPQT4_GENERATE_MOC_I)
+
+# same as tpqt4_generate_moc_i, but lets the caller specify a list of targets which the mocs should depend on
+function(TPQT4_GENERATE_MOC_I_TARGET_DEPS infile outfile)
+ qt4_get_moc_flags(moc_flags)
+ get_filename_component(abs_infile ${infile} ABSOLUTE)
+ tpqt4_create_moc_command_target_deps(${abs_infile} ${outfile} "${moc_flags}" "-i" ${ARGN})
+ set_source_files_properties(${outfile} PROPERTIES SKIP_AUTOMOC TRUE) # dont run automoc on this file
+endfunction(TPQT4_GENERATE_MOC_I_TARGET_DEPS)
+
+# generates mocs for the passed list. The list should be added to the target's sources
+function(tpqt4_generate_mocs)
+ file(MAKE_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/_gen" )
+ foreach(moc_src ${ARGN})
+ string(REPLACE ".h" ".moc.hpp" generated_file ${moc_src})
+ tpqt4_generate_moc_i(${CMAKE_CURRENT_SOURCE_DIR}/${moc_src} ${CMAKE_CURRENT_BINARY_DIR}/_gen/${generated_file})
+ macro_add_file_dependencies(${moc_src} ${CMAKE_CURRENT_BINARY_DIR}/_gen/${generated_file})
+ endforeach(moc_src ${ARGN})
+endfunction(tpqt4_generate_mocs)
+
+function(tpqt4_client_generator spec_xml spec group real_include pretty_include namespace types_namespace must_define visibility)
+ tpqt4_extract_depends(client_generator_args client_generator_depends ${ARGN})
+ set(ARGS
+ ${CMAKE_SOURCE_DIR}/tools/qt4-client-gen.py
+ --group=${group}
+ --namespace=${namespace}
+ --typesnamespace=${types_namespace}
+ --headerfile=${CMAKE_CURRENT_BINARY_DIR}/_gen/cli-${spec}.h
+ --implfile=${CMAKE_CURRENT_BINARY_DIR}/_gen/cli-${spec}-body.hpp
+ --realinclude=${real_include}
+ --prettyinclude=${pretty_include}
+ --specxml=${spec_xml}
+ --ifacexml=${CMAKE_CURRENT_BINARY_DIR}/_gen/spec-${spec}.xml
+ --extraincludes=${TYPES_INCLUDE}
+ --must-define=${must_define}
+ --visibility=${visibility}
+ ${client_generator_args})
+ add_custom_command(OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/_gen/cli-${spec}.h ${CMAKE_CURRENT_BINARY_DIR}/_gen/cli-${spec}-body.hpp
+ COMMAND ${PYTHON_EXECUTABLE}
+ ARGS ${ARGS}
+ WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+
+ DEPENDS ${CMAKE_SOURCE_DIR}/tools/libqt4codegen.py
+ ${CMAKE_SOURCE_DIR}/tools/qt4-client-gen.py)
+ add_custom_target(generate_cli-${spec}-body DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/_gen/cli-${spec}-body.hpp)
+
+ if (client_generator_depends)
+ add_dependencies(generate_cli-${spec}-body ${client_generator_depends})
+ endif (client_generator_depends)
+
+ tpqt4_generate_moc_i_target_deps(${CMAKE_CURRENT_BINARY_DIR}/_gen/cli-${spec}.h
+ ${CMAKE_CURRENT_BINARY_DIR}/_gen/cli-${spec}.moc.hpp
+ "generate_cli-${spec}-body")
+endfunction(tpqt4_client_generator spec_xml spec group real_include pretty_include namespace types_namespace must_define visibility)
+
+function(tpqt4_future_client_generator future_spec_xml spec real_include pretty_include namespace types_namespace visibility)
+ tpqt4_extract_depends(future_client_generator_args future_client_generator_depends ${ARGN})
+ set(ARGS
+ ${CMAKE_SOURCE_DIR}/tools/qt4-client-gen.py
+ --namespace=${namespace}
+ --typesnamespace=${types_namespace}
+ --headerfile=${CMAKE_CURRENT_BINARY_DIR}/_gen/future-${spec}.h
+ --implfile=${CMAKE_CURRENT_BINARY_DIR}/_gen/future-${spec}-body.hpp
+ --realinclude=${real_include}
+ --prettyinclude=${pretty_include}
+ --specxml=${future_spec_xml}
+ --ifacexml=${CMAKE_CURRENT_BINARY_DIR}/_gen/future-${spec}.xml
+ --extraincludes=${TYPES_INCLUDE}
+ --visibility=${visibility}
+ ${future_client_generator_args})
+ add_custom_command(OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/_gen/future-${spec}.h ${CMAKE_CURRENT_BINARY_DIR}/_gen/future-${spec}-body.hpp
+ COMMAND ${PYTHON_EXECUTABLE}
+ ARGS ${ARGS}
+ WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+
+ DEPENDS ${CMAKE_SOURCE_DIR}/tools/libqt4codegen.py
+ ${CMAKE_SOURCE_DIR}/tools/qt4-client-gen.py)
+ add_custom_target(generate_future-${spec}-body DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/_gen/future-${spec}-body.hpp)
+
+ if (future_client_generator_depends)
+ add_dependencies(generate_future-${spec}-body ${future_client_generator_depends})
+ endif (future_client_generator_depends)
+
+ tpqt4_generate_moc_i_target_deps(${CMAKE_CURRENT_BINARY_DIR}/_gen/future-${spec}.h
+ ${CMAKE_CURRENT_BINARY_DIR}/_gen/future-${spec}.moc.hpp
+ "generate_future-${spec}-body")
+endfunction(tpqt4_future_client_generator future_spec_xml spec real_include pretty_include namespace types_namespace visibility)
+
+# This function is used for generating CM in various examples
+function(tpqt4_generate_manager_file MANAGER_FILE OUTPUT_FILENAME DEPEND_FILENAME)
+ # make_directory is required, otherwise the command won't work!!
+ make_directory(${CMAKE_CURRENT_BINARY_DIR}/_gen)
+ add_custom_command(OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/_gen/param-spec-struct.h
+ ${CMAKE_CURRENT_BINARY_DIR}/_gen/${OUTPUT_FILENAME}
+
+ COMMAND ${PYTHON_EXECUTABLE}
+
+ ARGS ${CMAKE_SOURCE_DIR}/tools/manager-file.py
+ ${MANAGER_FILE}
+ _gen
+
+ DEPENDS ${CMAKE_SOURCE_DIR}/tools/manager-file.py)
+
+ set_source_files_properties(${DEPEND_FILENAME}
+ PROPERTIES OBJECT_DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/_gen/param-spec-struct.h)
+endfunction(tpqt4_generate_manager_file MANAGER_FILE)
+
+function(tpqt4_xincludator _TARGET_NAME _INPUT_FILE _OUTPUT_FILE)
+ tpqt4_extract_depends(xincludator_gen_args xincludator_gen_depends ${ARGN})
+ # Gather all .xml files in spec/ and make this target depend on those
+ file(GLOB depends_xml_files ${CMAKE_SOURCE_DIR}/spec/*.xml)
+
+ add_custom_command(OUTPUT ${_OUTPUT_FILE}
+
+ COMMAND ${PYTHON_EXECUTABLE}
+
+ ARGS ${CMAKE_SOURCE_DIR}/tools/xincludator.py
+ ${_INPUT_FILE}
+ ${xincludator_gen_args}
+ > ${_OUTPUT_FILE}
+
+ DEPENDS ${CMAKE_SOURCE_DIR}/tools/xincludator.py
+ ${_INPUT_FILE} ${depends_xml_files})
+ add_custom_target(${_TARGET_NAME} DEPENDS ${_OUTPUT_FILE})
+
+ if (xincludator_gen_depends)
+ add_dependencies(${_TARGET_NAME} ${xincludator_gen_depends})
+ endif (xincludator_gen_depends)
+endfunction(tpqt4_xincludator _TARGET_NAME _INPUT_FILE _OUTPUT_FILE)
+
+function(tpqt4_constants_gen _TARGET_NAME _SPEC_XML _OUTFILE)
+ tpqt4_extract_depends(constants_gen_args constants_gen_depends ${ARGN})
+ # Gather all .xml files in spec/ and make this target depend on those
+ file(GLOB depends_xml_files ${CMAKE_SOURCE_DIR}/spec/*.xml)
+
+ add_custom_command(OUTPUT ${_OUTFILE}
+
+ COMMAND ${PYTHON_EXECUTABLE}
+
+ ARGS ${CMAKE_SOURCE_DIR}/tools/qt4-constants-gen.py
+ ${constants_gen_args}
+ --specxml=${_SPEC_XML}
+ > ${_OUTFILE}
+
+ DEPENDS ${CMAKE_SOURCE_DIR}/tools/libqt4codegen.py
+ ${CMAKE_SOURCE_DIR}/tools/qt4-constants-gen.py
+ ${_SPEC_XML} ${depends_xml_files})
+ add_custom_target(${_TARGET_NAME} DEPENDS ${_OUTFILE})
+
+ if (constants_gen_depends)
+ add_dependencies(${_TARGET_NAME} ${constants_gen_depends})
+ endif (constants_gen_depends)
+endfunction (tpqt4_constants_gen _TARGET_NAME _SPEC_XML _OUTFILE)
+
+function(tpqt4_types_gen _TARGET_NAME _SPEC_XML _OUTFILE_DECL _OUTFILE_IMPL _NAMESPACE _REALINCLUDE _PRETTYINCLUDE)
+ tpqt4_extract_depends(types_gen_args types_gen_depends ${ARGN})
+ # Gather all .xml files in spec/ and make this target depend on those
+ file(GLOB depends_xml_files ${CMAKE_SOURCE_DIR}/spec/*.xml)
+
+ add_custom_command(OUTPUT ${_OUTFILE_DECL} ${_OUTFILE_IMPL}
+ COMMAND ${PYTHON_EXECUTABLE}
+ ARGS ${CMAKE_SOURCE_DIR}/tools/qt4-types-gen.py
+ --namespace=${_NAMESPACE}
+ --declfile=${_OUTFILE_DECL}
+ --implfile=${_OUTFILE_IMPL}
+ --realinclude=${_REALINCLUDE}
+ --prettyinclude=${_PRETTYINCLUDE}
+ ${types_gen_args}
+ --specxml=${_SPEC_XML}
+
+ DEPENDS ${CMAKE_SOURCE_DIR}/tools/libqt4codegen.py
+ ${CMAKE_SOURCE_DIR}/tools/qt4-types-gen.py
+ ${_SPEC_XML} ${depends_xml_files})
+ add_custom_target(${_TARGET_NAME} DEPENDS ${_OUTFILE_IMPL})
+
+ if (types_gen_depends)
+ add_dependencies(${_TARGET_NAME} ${types_gen_depends})
+ endif (types_gen_depends)
+endfunction(tpqt4_types_gen _TARGET_NAME _SPEC_XML _OUTFILE_DECL _OUTFILE_IMPL _NAMESPACE _REALINCLUDE _PRETTYINCLUDE)
+
+macro(tpqt4_add_generic_unit_test _fancyName _name)
+ tpqt4_generate_moc_i(${_name}.cpp ${CMAKE_CURRENT_BINARY_DIR}/_gen/${_name}.cpp.moc.hpp)
+ add_executable(test-${_name} ${_name}.cpp ${CMAKE_CURRENT_BINARY_DIR}/_gen/${_name}.cpp.moc.hpp)
+ target_link_libraries(test-${_name} ${QT_LIBRARIES} ${QT_QTTEST_LIBRARY} telepathy-qt4 ${ARGN})
+ add_test(${_fancyName} ${SH} ${CMAKE_CURRENT_BINARY_DIR}/runGenericTest.sh ${CMAKE_CURRENT_BINARY_DIR}/test-${_name})
+ list(APPEND tpqt4_test_cases test-${_name})
+
+ # Valgrind and Callgrind targets
+ _tpqt4_add_check_targets(${_fancyName} ${_name} ${CMAKE_CURRENT_BINARY_DIR}/runGenericTest.sh ${CMAKE_CURRENT_BINARY_DIR}/test-${_name})
+endmacro(tpqt4_add_generic_unit_test _fancyName _name)
+
+macro(tpqt4_add_dbus_unit_test _fancyName _name)
+ tpqt4_generate_moc_i(${_name}.cpp ${CMAKE_CURRENT_BINARY_DIR}/_gen/${_name}.cpp.moc.hpp)
+ add_executable(test-${_name} ${_name}.cpp ${CMAKE_CURRENT_BINARY_DIR}/_gen/${_name}.cpp.moc.hpp)
+ target_link_libraries(test-${_name} ${QT_LIBRARIES} ${QT_QTTEST_LIBRARY} telepathy-qt4 ${ARGN})
+ set(with_session_bus ${CMAKE_CURRENT_BINARY_DIR}/runDbusTest.sh)
+ add_test(${_fancyName} ${SH} ${with_session_bus} ${CMAKE_CURRENT_BINARY_DIR}/test-${_name})
+ list(APPEND tpqt4_test_cases test-${_name})
+
+ # Valgrind and Callgrind targets
+ _tpqt4_add_check_targets(${_fancyName} ${_name} ${with_session_bus} ${CMAKE_CURRENT_BINARY_DIR}/test-${_name})
+endmacro(tpqt4_add_dbus_unit_test _fancyName _name)
+
+macro(_tpqt4_add_check_targets _fancyName _name _runnerScript)
+ set_tests_properties(${_fancyName}
+ PROPERTIES
+ FAIL_REGULAR_EXPRESSION "^FAIL!")
+
+ # Standard check target
+ add_custom_target(check-${_fancyName} ${SH} ${_runnerScript} ${ARGN})
+ add_dependencies(check-${_fancyName} test-${_name})
+
+ # Lcov target
+ add_dependencies(lcov-check test-${_name})
+
+ # Valgrind target
+ add_custom_target(check-valgrind-${_fancyName})
+ add_dependencies(check-valgrind-${_fancyName} test-${_name})
+
+ add_custom_command(
+ TARGET check-valgrind-${_fancyName}
+ COMMAND G_SLICE=always-malloc ${SH} ${_runnerScript} /usr/bin/valgrind
+ --tool=memcheck
+ --leak-check=full
+ --leak-resolution=high
+ --child-silent-after-fork=yes
+ --num-callers=20
+ --gen-suppressions=all
+ --log-file=${CMAKE_CURRENT_BINARY_DIR}/test-${_fancyName}.memcheck.log
+ --suppressions=${CMAKE_SOURCE_DIR}/tools/telepathy-qt4.supp
+ --suppressions=${CMAKE_SOURCE_DIR}/tools/telepathy-glib.supp
+ ${ARGN}
+ WORKING_DIRECTORY
+ ${CMAKE_CURRENT_BINARY_DIR}
+ COMMENT "Running valgrind on test \"${_fancyName}\"")
+ add_dependencies(check-valgrind check-valgrind-${_fancyName})
+
+ # Callgrind target
+ add_custom_target(check-callgrind-${_fancyName})
+ add_dependencies(check-callgrind-${_fancyName} test-${_name})
+ add_custom_command(
+ TARGET check-callgrind-${_fancyName}
+ COMMAND ${SH} ${_runnerScript} /usr/bin/valgrind
+ --tool=callgrind
+ --dump-instr=yes
+ --log-file=${CMAKE_CURRENT_BINARY_DIR}/test-${_fancyName}.callgrind.log
+ --callgrind-out-file=${CMAKE_CURRENT_BINARY_DIR}/test-${_fancyName}.callgrind.out
+ ${ARGN}
+ WORKING_DIRECTORY
+ ${CMAKE_CURRENT_BINARY_DIR}
+ COMMENT
+ "Running callgrind on test \"${_fancyName}\"")
+ add_dependencies(check-callgrind check-callgrind-${_fancyName})
+endmacro(_tpqt4_add_check_targets _fancyName _name)
+
+function(tpqt4_setup_dbus_test_environment)
+ file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/runDbusTest.sh "
+${test_environment}
+sh ${CMAKE_SOURCE_DIR}/tools/with-session-bus.sh \\
+ --config-file=${CMAKE_BINARY_DIR}/tests/dbus-1/session.conf -- $@
+")
+endfunction(tpqt4_setup_dbus_test_environment)
diff --git a/cmake_uninstall.cmake.in b/cmake_uninstall.cmake.in
new file mode 100644
index 0000000..df95fb9
--- /dev/null
+++ b/cmake_uninstall.cmake.in
@@ -0,0 +1,21 @@
+IF(NOT EXISTS "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt")
+ MESSAGE(FATAL_ERROR "Cannot find install manifest: \"@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt\"")
+ENDIF(NOT EXISTS "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt")
+
+FILE(READ "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt" files)
+STRING(REGEX REPLACE "\n" ";" files "${files}")
+FOREACH(file ${files})
+ MESSAGE(STATUS "Uninstalling \"$ENV{DESTDIR}${file}\"")
+ IF(EXISTS "$ENV{DESTDIR}${file}")
+ EXEC_PROGRAM(
+ "@CMAKE_COMMAND@" ARGS "-E remove \"$ENV{DESTDIR}${file}\""
+ OUTPUT_VARIABLE rm_out
+ RETURN_VALUE rm_retval
+ )
+ IF(NOT "${rm_retval}" STREQUAL 0)
+ MESSAGE(FATAL_ERROR "Problem when removing \"$ENV{DESTDIR}${file}\"")
+ ENDIF(NOT "${rm_retval}" STREQUAL 0)
+ ELSE(EXISTS "$ENV{DESTDIR}${file}")
+ MESSAGE(STATUS "File \"$ENV{DESTDIR}${file}\" does not exist.")
+ ENDIF(EXISTS "$ENV{DESTDIR}${file}")
+ENDFOREACH(file)
diff --git a/config.h.in b/config.h.in
new file mode 100644
index 0000000..12e7929
--- /dev/null
+++ b/config.h.in
@@ -0,0 +1,2 @@
+#define PACKAGE_NAME "@PACKAGE_NAME@"
+#define PACKAGE_VERSION "@PACKAGE_VERSION@"
diff --git a/doxygen-footer.html b/doxygen-footer.html
new file mode 100644
index 0000000..5a64c84
--- /dev/null
+++ b/doxygen-footer.html
@@ -0,0 +1,7 @@
+<p /><address><hr /><div align="center">
+<table width="100%" cellspacing="0" border="0"><tr class="address">
+<td width="30%">Copyright &copy; 2008-2010 Collabora Ltd. and Nokia Corporation</td>
+<td width="30%" align="right"><div align="right">Telepathy-Qt4-Yell $projectnumber</div></td>
+</tr></table></div></address>
+</body>
+</html>
diff --git a/doxygen-header.html b/doxygen-header.html
new file mode 100644
index 0000000..e3e5630
--- /dev/null
+++ b/doxygen-header.html
@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE html
+ PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+ <title>$title</title>
+ <link href="doxygen.css" rel="stylesheet" type="text/css" />
+</head>
+<body>
+<table border="0" cellpadding="0" cellspacing="0" width="100%">
+<tr>
+<td width="1">&nbsp;&nbsp;</td>
+<td class="postheader" valign="center">
+<a href="index.html">
+<font color="#004faf">Home</font></a>&nbsp;&middot;
+<a href="classes.html">
+<font color="#004faf">All Classes</font></a>&nbsp;&middot;
+<a href="namespaces.html">
+<font color="#004faf">All Namespaces</font></a>&nbsp;&middot;
+<a href="modules.html">
+<font color="#004faf">Modules</font></a>&nbsp;&middot;
+<a href="functions.html">
+<font color="#004faf">Functions</font></a>&nbsp;&middot;
+<a href="files.html">
+<font color="#004faf">Files</font></a>
+</td>
+</tr>
+</table>
+</body>
+</html>
diff --git a/doxygen.cfg.in b/doxygen.cfg.in
new file mode 100644
index 0000000..5fcfd27
--- /dev/null
+++ b/doxygen.cfg.in
@@ -0,0 +1,1470 @@
+# This file describes the settings to be used by the documentation system
+# doxygen (www.doxygen.org) for a project
+#
+# All text after a hash (#) is considered a comment and will be ignored
+# The format is:
+# TAG = value [value, ...]
+# For lists items can also be appended using:
+# TAG += value [value, ...]
+# Values that contain spaces should be placed between quotes (" ")
+
+#---------------------------------------------------------------------------
+# Project related configuration options
+#---------------------------------------------------------------------------
+
+# This tag specifies the encoding used for all characters in the config file
+# that follow. The default is UTF-8 which is also the encoding used for all
+# text before the first occurrence of this tag. Doxygen uses libiconv (or the
+# iconv built into libc) for the transcoding. See
+# http://www.gnu.org/software/libiconv for the list of possible encodings.
+
+DOXYFILE_ENCODING = UTF-8
+
+# The PROJECT_NAME tag is a single word (or a sequence of words surrounded
+# by quotes) that should identify the project.
+
+PROJECT_NAME = ${PROJECT_NAME}
+
+# The PROJECT_NUMBER tag can be used to enter a project or revision number.
+# This could be handy for archiving the generated documentation or
+# if some version control system is used.
+
+PROJECT_NUMBER = ${PACKAGE_VERSION}
+
+# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute)
+# base path where the generated documentation will be put.
+# If a relative path is entered, it will be relative to the location
+# where doxygen was started. If left blank the current directory will be used.
+
+OUTPUT_DIRECTORY = ${abs_top_builddir}/doc
+
+
+# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create
+# 4096 sub-directories (in 2 levels) under the output directory of each output
+# format and will distribute the generated files over these directories.
+# Enabling this option can be useful when feeding doxygen a huge amount of
+# source files, where putting all generated files in the same directory would
+# otherwise cause performance problems for the file system.
+
+CREATE_SUBDIRS = NO
+
+# The OUTPUT_LANGUAGE tag is used to specify the language in which all
+# documentation generated by doxygen is written. Doxygen will use this
+# information to generate all constant output in the proper language.
+# The default language is English, other supported languages are:
+# Afrikaans, Arabic, Brazilian, Catalan, Chinese, Chinese-Traditional,
+# Croatian, Czech, Danish, Dutch, Farsi, Finnish, French, German, Greek,
+# Hungarian, Italian, Japanese, Japanese-en (Japanese with English messages),
+# Korean, Korean-en, Lithuanian, Norwegian, Macedonian, Persian, Polish,
+# Portuguese, Romanian, Russian, Serbian, Slovak, Slovene, Spanish, Swedish,
+# and Ukrainian.
+
+OUTPUT_LANGUAGE = English
+
+# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will
+# include brief member descriptions after the members that are listed in
+# the file and class documentation (similar to JavaDoc).
+# Set to NO to disable this.
+
+BRIEF_MEMBER_DESC = YES
+
+# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend
+# the brief description of a member or function before the detailed description.
+# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the
+# brief descriptions will be completely suppressed.
+
+REPEAT_BRIEF = YES
+
+# This tag implements a quasi-intelligent brief description abbreviator
+# that is used to form the text in various listings. Each string
+# in this list, if found as the leading text of the brief description, will be
+# stripped from the text and the result after processing the whole list, is
+# used as the annotated text. Otherwise, the brief description is used as-is.
+# If left blank, the following values are used ("$name" is automatically
+# replaced with the name of the entity): "The $name class" "The $name widget"
+# "The $name file" "is" "provides" "specifies" "contains"
+# "represents" "a" "an" "the"
+
+ABBREVIATE_BRIEF = "The \$name class" \
+ "The \$name file" \
+ is \
+ provides \
+ specifies \
+ contains \
+ represents \
+ a \
+ an \
+ the
+
+# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then
+# Doxygen will generate a detailed section even if there is only a brief
+# description.
+
+ALWAYS_DETAILED_SEC = YES
+
+# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all
+# inherited members of a class in the documentation of that class as if those
+# members were ordinary class members. Constructors, destructors and assignment
+# operators of the base classes will not be shown.
+
+INLINE_INHERITED_MEMB = NO
+
+# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full
+# path before files name in the file list and in the header files. If set
+# to NO the shortest path that makes the file name unique will be used.
+
+FULL_PATH_NAMES = NO
+
+# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag
+# can be used to strip a user-defined part of the path. Stripping is
+# only done if one of the specified strings matches the left-hand part of
+# the path. The tag can be used to show relative paths in the file list.
+# If left blank the directory from which doxygen is run is used as the
+# path to strip.
+
+STRIP_FROM_PATH = ${abs_top_srcdir}
+
+# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of
+# the path mentioned in the documentation of a class, which tells
+# the reader which header file to include in order to use a class.
+# If left blank only the name of the header file containing the class
+# definition is used. Otherwise one should specify the include paths that
+# are normally passed to the compiler using the -I flag.
+
+STRIP_FROM_INC_PATH = $abs_top_srcdir} ${abs_top_builddir}
+
+# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter
+# (but less readable) file names. This can be useful is your file systems
+# doesn't support long names like on DOS, Mac, or CD-ROM.
+
+SHORT_NAMES = YES
+
+# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen
+# will interpret the first line (until the first dot) of a JavaDoc-style
+# comment as the brief description. If set to NO, the JavaDoc
+# comments will behave just like regular Qt-style comments
+# (thus requiring an explicit @brief command for a brief description.)
+
+JAVADOC_AUTOBRIEF = NO
+
+# If the QT_AUTOBRIEF tag is set to YES then Doxygen will
+# interpret the first line (until the first dot) of a Qt-style
+# comment as the brief description. If set to NO, the comments
+# will behave just like regular Qt-style comments (thus requiring
+# an explicit \brief command for a brief description.)
+
+QT_AUTOBRIEF = NO
+
+# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen
+# treat a multi-line C++ special comment block (i.e. a block of //! or ///
+# comments) as a brief description. This used to be the default behaviour.
+# The new default is to treat a multi-line C++ comment block as a detailed
+# description. Set this tag to YES if you prefer the old behaviour instead.
+
+MULTILINE_CPP_IS_BRIEF = NO
+
+# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented
+# member inherits the documentation from any documented member that it
+# re-implements.
+
+INHERIT_DOCS = YES
+
+# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce
+# a new page for each member. If set to NO, the documentation of a member will
+# be part of the file/class/namespace that contains it.
+
+SEPARATE_MEMBER_PAGES = NO
+
+# The TAB_SIZE tag can be used to set the number of spaces in a tab.
+# Doxygen uses this value to replace tabs by spaces in code fragments.
+
+TAB_SIZE = 4
+
+# This tag can be used to specify a number of aliases that acts
+# as commands in the documentation. An alias has the form "name=value".
+# For example adding "sideeffect=\par Side Effects:\n" will allow you to
+# put the command \sideeffect (or @sideeffect) in the documentation, which
+# will result in a user-defined paragraph with heading "Side Effects:".
+# You can put \n's in the value part of an alias to insert newlines.
+
+ALIASES =
+
+# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C
+# sources only. Doxygen will then generate output that is more tailored for C.
+# For instance, some of the names that are used will be different. The list
+# of all members will be omitted, etc.
+
+OPTIMIZE_OUTPUT_FOR_C = NO
+
+# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java
+# sources only. Doxygen will then generate output that is more tailored for
+# Java. For instance, namespaces will be presented as packages, qualified
+# scopes will look different, etc.
+
+OPTIMIZE_OUTPUT_JAVA = NO
+
+# Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran
+# sources only. Doxygen will then generate output that is more tailored for
+# Fortran.
+
+OPTIMIZE_FOR_FORTRAN = NO
+
+# Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL
+# sources. Doxygen will then generate output that is tailored for
+# VHDL.
+
+OPTIMIZE_OUTPUT_VHDL = NO
+
+# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want
+# to include (a tag file for) the STL sources as input, then you should
+# set this tag to YES in order to let doxygen match functions declarations and
+# definitions whose arguments contain STL classes (e.g. func(std::string); v.s.
+# func(std::string) {}). This also make the inheritance and collaboration
+# diagrams that involve STL classes more complete and accurate.
+
+BUILTIN_STL_SUPPORT = YES
+
+# If you use Microsoft's C++/CLI language, you should set this option to YES to
+# enable parsing support.
+
+CPP_CLI_SUPPORT = NO
+
+# Set the SIP_SUPPORT tag to YES if your project consists of sip sources only.
+# Doxygen will parse them like normal C++ but will assume all classes use public
+# instead of private inheritance when no explicit protection keyword is present.
+
+SIP_SUPPORT = NO
+
+# For Microsoft's IDL there are propget and propput attributes to indicate getter
+# and setter methods for a property. Setting this option to YES (the default)
+# will make doxygen to replace the get and set methods by a property in the
+# documentation. This will only work if the methods are indeed getting or
+# setting a simple type. If this is not the case, or you want to show the
+# methods anyway, you should set this option to NO.
+
+IDL_PROPERTY_SUPPORT = NO
+
+# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC
+# tag is set to YES, then doxygen will reuse the documentation of the first
+# member in the group (if any) for the other members of the group. By default
+# all members of a group must be documented explicitly.
+
+DISTRIBUTE_GROUP_DOC = YES
+
+# Set the SUBGROUPING tag to YES (the default) to allow class member groups of
+# the same type (for instance a group of public functions) to be put as a
+# subgroup of that type (e.g. under the Public Functions section). Set it to
+# NO to prevent subgrouping. Alternatively, this can be done per class using
+# the \nosubgrouping command.
+
+SUBGROUPING = YES
+
+# When TYPEDEF_HIDES_STRUCT is enabled, a typedef of a struct, union, or enum
+# is documented as struct, union, or enum with the name of the typedef. So
+# typedef struct TypeS {} TypeT, will appear in the documentation as a struct
+# with name TypeT. When disabled the typedef will appear as a member of a file,
+# namespace, or class. And the struct will be named TypeS. This can typically
+# be useful for C code in case the coding convention dictates that all compound
+# types are typedef'ed and only the typedef is referenced, never the tag name.
+
+TYPEDEF_HIDES_STRUCT = NO
+
+#---------------------------------------------------------------------------
+# Build related configuration options
+#---------------------------------------------------------------------------
+
+# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in
+# documentation are documented, even if no documentation was available.
+# Private class members and static file members will be hidden unless
+# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES
+
+EXTRACT_ALL = YES
+
+# If the EXTRACT_PRIVATE tag is set to YES all private members of a class
+# will be included in the documentation.
+
+EXTRACT_PRIVATE = NO
+
+# If the EXTRACT_STATIC tag is set to YES all static members of a file
+# will be included in the documentation.
+
+EXTRACT_STATIC = NO
+
+# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs)
+# defined locally in source files will be included in the documentation.
+# If set to NO only classes defined in header files are included.
+
+EXTRACT_LOCAL_CLASSES = NO
+
+# This flag is only useful for Objective-C code. When set to YES local
+# methods, which are defined in the implementation section but not in
+# the interface are included in the documentation.
+# If set to NO (the default) only methods in the interface are included.
+
+EXTRACT_LOCAL_METHODS = NO
+
+# If this flag is set to YES, the members of anonymous namespaces will be
+# extracted and appear in the documentation as a namespace called
+# 'anonymous_namespace{file}', where file will be replaced with the base
+# name of the file that contains the anonymous namespace. By default
+# anonymous namespace are hidden.
+
+EXTRACT_ANON_NSPACES = NO
+
+# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all
+# undocumented members of documented classes, files or namespaces.
+# If set to NO (the default) these members will be included in the
+# various overviews, but no documentation section is generated.
+# This option has no effect if EXTRACT_ALL is enabled.
+
+HIDE_UNDOC_MEMBERS = NO
+
+# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all
+# undocumented classes that are normally visible in the class hierarchy.
+# If set to NO (the default) these classes will be included in the various
+# overviews. This option has no effect if EXTRACT_ALL is enabled.
+
+HIDE_UNDOC_CLASSES = NO
+
+# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all
+# friend (class|struct|union) declarations.
+# If set to NO (the default) these declarations will be included in the
+# documentation.
+
+HIDE_FRIEND_COMPOUNDS = YES
+
+# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any
+# documentation blocks found inside the body of a function.
+# If set to NO (the default) these blocks will be appended to the
+# function's detailed documentation block.
+
+HIDE_IN_BODY_DOCS = NO
+
+# The INTERNAL_DOCS tag determines if documentation
+# that is typed after a \internal command is included. If the tag is set
+# to NO (the default) then the documentation will be excluded.
+# Set it to YES to include the internal documentation.
+
+INTERNAL_DOCS = NO
+
+# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate
+# file names in lower-case letters. If set to YES upper-case letters are also
+# allowed. This is useful if you have classes or files whose names only differ
+# in case and if your file system supports case sensitive file names. Windows
+# and Mac users are advised to set this option to NO.
+
+CASE_SENSE_NAMES = YES
+
+# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen
+# will show members with their full class and namespace scopes in the
+# documentation. If set to YES the scope will be hidden.
+
+HIDE_SCOPE_NAMES = NO
+
+# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen
+# will put a list of the files that are included by a file in the documentation
+# of that file.
+
+SHOW_INCLUDE_FILES = YES
+
+# If the INLINE_INFO tag is set to YES (the default) then a tag [inline]
+# is inserted in the documentation for inline members.
+
+INLINE_INFO = YES
+
+# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen
+# will sort the (detailed) documentation of file and class members
+# alphabetically by member name. If set to NO the members will appear in
+# declaration order.
+
+SORT_MEMBER_DOCS = NO
+
+# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the
+# brief documentation of file, namespace and class members alphabetically
+# by member name. If set to NO (the default) the members will appear in
+# declaration order.
+
+SORT_BRIEF_DOCS = NO
+
+# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the
+# hierarchy of group names into alphabetical order. If set to NO (the default)
+# the group names will appear in their defined order.
+
+SORT_GROUP_NAMES = NO
+
+# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be
+# sorted by fully-qualified names, including namespaces. If set to
+# NO (the default), the class list will be sorted only by class name,
+# not including the namespace part.
+# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES.
+# Note: This option applies only to the class list, not to the
+# alphabetical list.
+
+SORT_BY_SCOPE_NAME = NO
+
+# The GENERATE_TODOLIST tag can be used to enable (YES) or
+# disable (NO) the todo list. This list is created by putting \todo
+# commands in the documentation.
+
+GENERATE_TODOLIST = YES
+
+# The GENERATE_TESTLIST tag can be used to enable (YES) or
+# disable (NO) the test list. This list is created by putting \test
+# commands in the documentation.
+
+GENERATE_TESTLIST = NO
+
+# The GENERATE_BUGLIST tag can be used to enable (YES) or
+# disable (NO) the bug list. This list is created by putting \bug
+# commands in the documentation.
+
+GENERATE_BUGLIST = NO
+
+# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or
+# disable (NO) the deprecated list. This list is created by putting
+# \deprecated commands in the documentation.
+
+GENERATE_DEPRECATEDLIST= YES
+
+# The ENABLED_SECTIONS tag can be used to enable conditional
+# documentation sections, marked by \if sectionname ... \endif.
+
+ENABLED_SECTIONS =
+
+# The MAX_INITIALIZER_LINES tag determines the maximum number of lines
+# the initial value of a variable or define consists of for it to appear in
+# the documentation. If the initializer consists of more lines than specified
+# here it will be hidden. Use a value of 0 to hide initializers completely.
+# The appearance of the initializer of individual variables and defines in the
+# documentation can be controlled using \showinitializer or \hideinitializer
+# command in the documentation regardless of this setting.
+
+MAX_INITIALIZER_LINES = 0
+
+# Set the SHOW_USED_FILES tag to NO to disable the list of files generated
+# at the bottom of the documentation of classes and structs. If set to YES the
+# list will mention the files that were used to generate the documentation.
+
+SHOW_USED_FILES = NO
+
+# If the sources in your project are distributed over multiple directories
+# then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy
+# in the documentation. The default is NO.
+
+SHOW_DIRECTORIES = NO
+
+# Set the SHOW_FILES tag to NO to disable the generation of the Files page.
+# This will remove the Files entry from the Quick Index and from the
+# Folder Tree View (if specified). The default is YES.
+
+SHOW_FILES = NO
+
+# Set the SHOW_NAMESPACES tag to NO to disable the generation of the
+# Namespaces page. This will remove the Namespaces entry from the Quick Index
+# and from the Folder Tree View (if specified). The default is YES.
+
+SHOW_NAMESPACES = YES
+
+# The FILE_VERSION_FILTER tag can be used to specify a program or script that
+# doxygen should invoke to get the current version for each file (typically from
+# the version control system). Doxygen will invoke the program by executing (via
+# popen()) the command <command> <input-file>, where <command> is the value of
+# the FILE_VERSION_FILTER tag, and <input-file> is the name of an input file
+# provided by doxygen. Whatever the program writes to standard output
+# is used as the file version. See the manual for examples.
+
+FILE_VERSION_FILTER =
+
+#---------------------------------------------------------------------------
+# configuration options related to warning and progress messages
+#---------------------------------------------------------------------------
+
+# The QUIET tag can be used to turn on/off the messages that are generated
+# by doxygen. Possible values are YES and NO. If left blank NO is used.
+
+QUIET = NO
+
+# The WARNINGS tag can be used to turn on/off the warning messages that are
+# generated by doxygen. Possible values are YES and NO. If left blank
+# NO is used.
+
+WARNINGS = YES
+
+# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings
+# for undocumented members. If EXTRACT_ALL is set to YES then this flag will
+# automatically be disabled.
+
+WARN_IF_UNDOCUMENTED = YES
+
+# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for
+# potential errors in the documentation, such as not documenting some
+# parameters in a documented function, or documenting parameters that
+# don't exist or using markup commands wrongly.
+
+WARN_IF_DOC_ERROR = YES
+
+# This WARN_NO_PARAMDOC option can be abled to get warnings for
+# functions that are documented, but have no documentation for their parameters
+# or return value. If set to NO (the default) doxygen will only warn about
+# wrong or incomplete parameter documentation, but not about the absence of
+# documentation.
+
+WARN_NO_PARAMDOC = YES
+
+# The WARN_FORMAT tag determines the format of the warning messages that
+# doxygen can produce. The string should contain the $file, $line, and $text
+# tags, which will be replaced by the file and line number from which the
+# warning originated and the warning text. Optionally the format may contain
+# $version, which will be replaced by the version of the file (if it could
+# be obtained via FILE_VERSION_FILTER)
+
+WARN_FORMAT = "\$file:\$line: \$text"
+
+# The WARN_LOGFILE tag can be used to specify a file to which warning
+# and error messages should be written. If left blank the output is written
+# to stderr.
+
+WARN_LOGFILE = doxygen.log
+
+#---------------------------------------------------------------------------
+# configuration options related to the input files
+#---------------------------------------------------------------------------
+
+# The INPUT tag can be used to specify the files and/or directories that contain
+# documented source files. You may enter file names like "myfile.cpp" or
+# directories like "/usr/src/myproject". Separate the files or directories
+# with spaces.
+
+INPUT = ${abs_top_srcdir}/TelepathyQt4Yell ${abs_top_builddir}/TelepathyQt4Yell
+
+# This tag can be used to specify the character encoding of the source files
+# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
+# also the default input encoding. Doxygen uses libiconv (or the iconv built
+# into libc) for the transcoding. See http://www.gnu.org/software/libiconv for
+# the list of possible encodings.
+
+INPUT_ENCODING = UTF-8
+
+# If the value of the INPUT tag contains directories, you can use the
+# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
+# and *.h) to filter out the source-files in the directories. If left
+# blank the following patterns are tested:
+# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx
+# *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.py *.f90
+
+FILE_PATTERNS = *.cpp \
+ *.cc \
+ *.cxx \
+ *.h \
+ *.hh \
+ *.hxx \
+ *.hpp \
+ *.dox
+
+# The RECURSIVE tag can be used to turn specify whether or not subdirectories
+# should be searched for input files as well. Possible values are YES and NO.
+# If left blank NO is used.
+
+RECURSIVE = YES
+
+# The EXCLUDE tag can be used to specify files and/or directories that should
+# excluded from the INPUT source files. This way you can easily exclude a
+# subdirectory from a directory tree whose root is specified with the INPUT tag.
+
+EXCLUDE =
+
+# The EXCLUDE_SYMLINKS tag can be used select whether or not files or
+# directories that are symbolic links (a Unix filesystem feature) are excluded
+# from the input.
+
+EXCLUDE_SYMLINKS = NO
+
+# If the value of the INPUT tag contains directories, you can use the
+# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude
+# certain files from those directories. Note that the wildcards are matched
+# against the file with absolute path, so to exclude all test directories
+# for example use the pattern */test/*
+
+EXCLUDE_PATTERNS = */.svn/* \
+ */.git/* \
+ */cmake/* \
+ *.moc.* \
+ */tests/* \
+ *-internal.* \
+ future*
+
+# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
+# (namespaces, classes, functions, etc.) that should be excluded from the
+# output. The symbol name can be a fully qualified name, a word, or if the
+# wildcard * is used, a substring. Examples: ANamespace, AClass,
+# AClass::ANamespace, ANamespace::*Test
+
+EXCLUDE_SYMBOLS =
+
+# The EXAMPLE_PATH tag can be used to specify one or more files or
+# directories that contain example code fragments that are included (see
+# the \include command).
+
+EXAMPLE_PATH = ${abs_top_srcdir}/examples
+
+# If the value of the EXAMPLE_PATH tag contains directories, you can use the
+# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
+# and *.h) to filter out the source-files in the directories. If left
+# blank all files are included.
+
+EXAMPLE_PATTERNS = *
+
+# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be
+# searched for input files to be used with the \include or \dontinclude
+# commands irrespective of the value of the RECURSIVE tag.
+# Possible values are YES and NO. If left blank NO is used.
+
+EXAMPLE_RECURSIVE = YES
+
+# The IMAGE_PATH tag can be used to specify one or more files or
+# directories that contain image that are included in the documentation (see
+# the \image command).
+
+IMAGE_PATH =
+
+# The INPUT_FILTER tag can be used to specify a program that doxygen should
+# invoke to filter for each input file. Doxygen will invoke the filter program
+# by executing (via popen()) the command <filter> <input-file>, where <filter>
+# is the value of the INPUT_FILTER tag, and <input-file> is the name of an
+# input file. Doxygen will then use the output that the filter program writes
+# to standard output. If FILTER_PATTERNS is specified, this tag will be
+# ignored.
+
+INPUT_FILTER =
+
+# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern
+# basis. Doxygen will compare the file name with each pattern and apply the
+# filter if there is a match. The filters are a list of the form:
+# pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further
+# info on how filters are used. If FILTER_PATTERNS is empty, INPUT_FILTER
+# is applied to all files.
+
+FILTER_PATTERNS =
+
+# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using
+# INPUT_FILTER) will be used to filter the input files when producing source
+# files to browse (i.e. when SOURCE_BROWSER is set to YES).
+
+FILTER_SOURCE_FILES = NO
+
+#---------------------------------------------------------------------------
+# configuration options related to source browsing
+#---------------------------------------------------------------------------
+
+# If the SOURCE_BROWSER tag is set to YES then a list of source files will
+# be generated. Documented entities will be cross-referenced with these sources.
+# Note: To get rid of all source code in the generated output, make sure also
+# VERBATIM_HEADERS is set to NO.
+
+SOURCE_BROWSER = NO
+
+# Setting the INLINE_SOURCES tag to YES will include the body
+# of functions and classes directly in the documentation.
+
+INLINE_SOURCES = NO
+
+# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct
+# doxygen to hide any special comment blocks from generated source code
+# fragments. Normal C and C++ comments will always remain visible.
+
+STRIP_CODE_COMMENTS = YES
+
+# If the REFERENCED_BY_RELATION tag is set to YES
+# then for each documented function all documented
+# functions referencing it will be listed.
+
+REFERENCED_BY_RELATION = NO
+
+# If the REFERENCES_RELATION tag is set to YES
+# then for each documented function all documented entities
+# called/used by that function will be listed.
+
+REFERENCES_RELATION = NO
+
+# If the REFERENCES_LINK_SOURCE tag is set to YES (the default)
+# and SOURCE_BROWSER tag is set to YES, then the hyperlinks from
+# functions in REFERENCES_RELATION and REFERENCED_BY_RELATION lists will
+# link to the source code. Otherwise they will link to the documentstion.
+
+REFERENCES_LINK_SOURCE = YES
+
+# If the USE_HTAGS tag is set to YES then the references to source code
+# will point to the HTML generated by the htags(1) tool instead of doxygen
+# built-in source browser. The htags tool is part of GNU's global source
+# tagging system (see http://www.gnu.org/software/global/global.html). You
+# will need version 4.8.6 or higher.
+
+USE_HTAGS = NO
+
+# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen
+# will generate a verbatim copy of the header file for each class for
+# which an include is specified. Set to NO to disable this.
+
+VERBATIM_HEADERS = YES
+
+#---------------------------------------------------------------------------
+# configuration options related to the alphabetical class index
+#---------------------------------------------------------------------------
+
+# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index
+# of all compounds will be generated. Enable this if the project
+# contains a lot of classes, structs, unions or interfaces.
+
+ALPHABETICAL_INDEX = NO
+
+# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then
+# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns
+# in which this list will be split (can be a number in the range [1..20])
+
+COLS_IN_ALPHA_INDEX = 5
+
+# In case all classes in a project start with a common prefix, all
+# classes will be put under the same header in the alphabetical index.
+# The IGNORE_PREFIX tag can be used to specify one or more prefixes that
+# should be ignored while generating the index headers.
+
+IGNORE_PREFIX =
+
+#---------------------------------------------------------------------------
+# configuration options related to the HTML output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_HTML tag is set to YES (the default) Doxygen will
+# generate HTML output.
+
+GENERATE_HTML = ${GENERATE_HTML}
+
+# The HTML_OUTPUT tag is used to specify where the HTML docs will be put.
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be
+# put in front of it. If left blank `html' will be used as the default path.
+
+HTML_OUTPUT = html
+
+# The HTML_FILE_EXTENSION tag can be used to specify the file extension for
+# each generated HTML page (for example: .htm,.php,.asp). If it is left blank
+# doxygen will generate files with .html extension.
+
+HTML_FILE_EXTENSION = .html
+
+# The HTML_HEADER tag can be used to specify a personal HTML header for
+# each generated HTML page. If it is left blank doxygen will generate a
+# standard header.
+
+HTML_HEADER = @abs_top_srcdir@/doxygen-header.html
+
+# The HTML_FOOTER tag can be used to specify a personal HTML footer for
+# each generated HTML page. If it is left blank doxygen will generate a
+# standard footer.
+
+HTML_FOOTER = @abs_top_srcdir@/doxygen-footer.html
+
+# The HTML_STYLESHEET tag can be used to specify a user-defined cascading
+# style sheet that is used by each HTML page. It can be used to
+# fine-tune the look of the HTML output. If the tag is left blank doxygen
+# will generate a default style sheet. Note that doxygen will try to copy
+# the style sheet file to the HTML output directory, so don't put your own
+# stylesheet in the HTML output directory as well, or it will be erased!
+
+HTML_STYLESHEET = @abs_top_srcdir@/doxygen.css
+
+# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes,
+# files or namespaces will be aligned in HTML using tables. If set to
+# NO a bullet list will be used.
+
+HTML_ALIGN_MEMBERS = NO
+
+# If the GENERATE_HTMLHELP tag is set to YES, additional index files
+# will be generated that can be used as input for tools like the
+# Microsoft HTML help workshop to generate a compiled HTML help file (.chm)
+# of the generated HTML documentation.
+
+GENERATE_HTMLHELP = ${GENERATE_CHM}
+
+# If the GENERATE_DOCSET tag is set to YES, additional index files
+# will be generated that can be used as input for Apple's Xcode 3
+# integrated development environment, introduced with OSX 10.5 (Leopard).
+# To create a documentation set, doxygen will generate a Makefile in the
+# HTML output directory. Running make will produce the docset in that
+# directory and running "make install" will install the docset in
+# ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find
+# it at startup.
+
+GENERATE_DOCSET = NO
+
+# When GENERATE_DOCSET tag is set to YES, this tag determines the name of the
+# feed. A documentation feed provides an umbrella under which multiple
+# documentation sets from a single provider (such as a company or product suite)
+# can be grouped.
+
+DOCSET_FEEDNAME = "Doxygen generated docs"
+
+# When GENERATE_DOCSET tag is set to YES, this tag specifies a string that
+# should uniquely identify the documentation set bundle. This should be a
+# reverse domain-name style string, e.g. com.mycompany.MyDocSet. Doxygen
+# will append .docset to the name.
+
+DOCSET_BUNDLE_ID = org.doxygen.Project
+
+# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML
+# documentation will contain sections that can be hidden and shown after the
+# page has loaded. For this to work a browser that supports
+# JavaScript and DHTML is required (for instance Mozilla 1.0+, Firefox
+# Netscape 6.0+, Internet explorer 5.0+, Konqueror, or Safari).
+
+HTML_DYNAMIC_SECTIONS = NO
+
+# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can
+# be used to specify the file name of the resulting .chm file. You
+# can add a path in front of the file if the result should not be
+# written to the html output directory.
+
+CHM_FILE = ../${PROJECT}.chm
+
+# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can
+# be used to specify the location (absolute path including file name) of
+# the HTML help compiler (hhc.exe). If non-empty doxygen will try to run
+# the HTML help compiler on the generated index.hhp.
+
+HHC_LOCATION = ${HHC_PATH}
+
+# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag
+# controls if a separate .chi index file is generated (YES) or that
+# it should be included in the master .chm file (NO).
+
+GENERATE_CHI = ${GENERATE_CHI}
+
+# If the GENERATE_HTMLHELP tag is set to YES, the CHM_INDEX_ENCODING
+# is used to encode HtmlHelp index (hhk), content (hhc) and project file
+# content.
+
+CHM_INDEX_ENCODING =
+
+# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag
+# controls whether a binary table of contents is generated (YES) or a
+# normal table of contents (NO) in the .chm file.
+
+BINARY_TOC = NO
+
+# The TOC_EXPAND flag can be set to YES to add extra items for group members
+# to the contents of the HTML help documentation and to the tree view.
+
+TOC_EXPAND = NO
+
+# The DISABLE_INDEX tag can be used to turn on/off the condensed index at
+# top of each HTML page. The value NO (the default) enables the index and
+# the value YES disables it.
+
+DISABLE_INDEX = YES
+
+# This tag can be used to set the number of enum values (range [1..20])
+# that doxygen will group on one line in the generated HTML documentation.
+
+ENUM_VALUES_PER_LINE = 4
+
+# The GENERATE_TREEVIEW tag is used to specify whether a tree-like index
+# structure should be generated to display hierarchical information.
+# If the tag value is set to FRAME, a side panel will be generated
+# containing a tree-like index structure (just like the one that
+# is generated for HTML Help). For this to work a browser that supports
+# JavaScript, DHTML, CSS and frames is required (for instance Mozilla 1.0+,
+# Netscape 6.0+, Internet explorer 5.0+, or Konqueror). Windows users are
+# probably better off using the HTML help feature. Other possible values
+# for this tag are: HIERARCHIES, which will generate the Groups, Directories,
+# and Class Hiererachy pages using a tree view instead of an ordered list;
+# ALL, which combines the behavior of FRAME and HIERARCHIES; and NONE, which
+# disables this behavior completely. For backwards compatibility with previous
+# releases of Doxygen, the values YES and NO are equivalent to FRAME and NONE
+# respectively.
+
+GENERATE_TREEVIEW = NO
+
+# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be
+# used to set the initial width (in pixels) of the frame in which the tree
+# is shown.
+
+TREEVIEW_WIDTH = 250
+
+# Use this tag to change the font size of Latex formulas included
+# as images in the HTML documentation. The default is 10. Note that
+# when you change the font size after a successful doxygen run you need
+# to manually remove any form_*.png images from the HTML output directory
+# to force them to be regenerated.
+
+FORMULA_FONTSIZE = 10
+
+#---------------------------------------------------------------------------
+# configuration options related to the LaTeX output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will
+# generate Latex output.
+
+GENERATE_LATEX = ${GENERATE_LATEX}
+
+# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put.
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be
+# put in front of it. If left blank `latex' will be used as the default path.
+
+LATEX_OUTPUT = latex
+
+# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be
+# invoked. If left blank `latex' will be used as the default command name.
+
+LATEX_CMD_NAME = latex
+
+# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to
+# generate index for LaTeX. If left blank `makeindex' will be used as the
+# default command name.
+
+MAKEINDEX_CMD_NAME = makeindex
+
+# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact
+# LaTeX documents. This may be useful for small projects and may help to
+# save some trees in general.
+
+COMPACT_LATEX = NO
+
+# The PAPER_TYPE tag can be used to set the paper type that is used
+# by the printer. Possible values are: a4, a4wide, letter, legal and
+# executive. If left blank a4wide will be used.
+
+PAPER_TYPE = ${PAPER_SIZE}
+
+# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX
+# packages that should be included in the LaTeX output.
+
+EXTRA_PACKAGES =
+
+# The LATEX_HEADER tag can be used to specify a personal LaTeX header for
+# the generated latex document. The header should contain everything until
+# the first chapter. If it is left blank doxygen will generate a
+# standard header. Notice: only use this tag if you know what you are doing!
+
+LATEX_HEADER =
+
+# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated
+# is prepared for conversion to pdf (using ps2pdf). The pdf file will
+# contain links (just like the HTML output) instead of page references
+# This makes the output suitable for online browsing using a pdf viewer.
+
+PDF_HYPERLINKS = NO
+
+# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of
+# plain latex in the generated Makefile. Set this option to YES to get a
+# higher quality PDF documentation.
+
+USE_PDFLATEX = NO
+
+# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode.
+# command to the generated LaTeX files. This will instruct LaTeX to keep
+# running if errors occur, instead of asking the user for help.
+# This option is also used when generating formulas in HTML.
+
+LATEX_BATCHMODE = YES
+
+# If LATEX_HIDE_INDICES is set to YES then doxygen will not
+# include the index chapters (such as File Index, Compound Index, etc.)
+# in the output.
+
+LATEX_HIDE_INDICES = NO
+
+#---------------------------------------------------------------------------
+# configuration options related to the RTF output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output
+# The RTF output is optimized for Word 97 and may not look very pretty with
+# other RTF readers or editors.
+
+GENERATE_RTF = ${GENERATE_RTF}
+
+# The RTF_OUTPUT tag is used to specify where the RTF docs will be put.
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be
+# put in front of it. If left blank `rtf' will be used as the default path.
+
+RTF_OUTPUT = rtf
+
+# If the COMPACT_RTF tag is set to YES Doxygen generates more compact
+# RTF documents. This may be useful for small projects and may help to
+# save some trees in general.
+
+COMPACT_RTF = NO
+
+# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated
+# will contain hyperlink fields. The RTF file will
+# contain links (just like the HTML output) instead of page references.
+# This makes the output suitable for online browsing using WORD or other
+# programs which support those fields.
+# Note: wordpad (write) and others do not support links.
+
+RTF_HYPERLINKS = NO
+
+# Load stylesheet definitions from file. Syntax is similar to doxygen's
+# config file, i.e. a series of assignments. You only have to provide
+# replacements, missing definitions are set to their default value.
+
+RTF_STYLESHEET_FILE =
+
+# Set optional variables used in the generation of an rtf document.
+# Syntax is similar to doxygen's config file.
+
+RTF_EXTENSIONS_FILE =
+
+#---------------------------------------------------------------------------
+# configuration options related to the man page output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_MAN tag is set to YES (the default) Doxygen will
+# generate man pages
+
+GENERATE_MAN = ${GENERATE_MAN}
+
+# The MAN_OUTPUT tag is used to specify where the man pages will be put.
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be
+# put in front of it. If left blank `man' will be used as the default path.
+
+MAN_OUTPUT = man
+
+# The MAN_EXTENSION tag determines the extension that is added to
+# the generated man pages (default is the subroutine's section .3)
+
+MAN_EXTENSION = .1
+
+# If the MAN_LINKS tag is set to YES and Doxygen generates man output,
+# then it will generate one additional man file for each entity
+# documented in the real man page(s). These additional files
+# only source the real man page, but without them the man command
+# would be unable to find the correct page. The default is NO.
+
+MAN_LINKS = NO
+
+#---------------------------------------------------------------------------
+# configuration options related to the XML output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_XML tag is set to YES Doxygen will
+# generate an XML file that captures the structure of
+# the code including all documentation.
+
+GENERATE_XML = ${GENERATE_XML}
+
+# The XML_OUTPUT tag is used to specify where the XML pages will be put.
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be
+# put in front of it. If left blank `xml' will be used as the default path.
+
+XML_OUTPUT = xml
+
+# The XML_SCHEMA tag can be used to specify an XML schema,
+# which can be used by a validating XML parser to check the
+# syntax of the XML files.
+
+XML_SCHEMA =
+
+# The XML_DTD tag can be used to specify an XML DTD,
+# which can be used by a validating XML parser to check the
+# syntax of the XML files.
+
+XML_DTD =
+
+# If the XML_PROGRAMLISTING tag is set to YES Doxygen will
+# dump the program listings (including syntax highlighting
+# and cross-referencing information) to the XML output. Note that
+# enabling this will significantly increase the size of the XML output.
+
+XML_PROGRAMLISTING = YES
+
+#---------------------------------------------------------------------------
+# configuration options for the AutoGen Definitions output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will
+# generate an AutoGen Definitions (see autogen.sf.net) file
+# that captures the structure of the code including all
+# documentation. Note that this feature is still experimental
+# and incomplete at the moment.
+
+GENERATE_AUTOGEN_DEF = NO
+
+#---------------------------------------------------------------------------
+# configuration options related to the Perl module output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_PERLMOD tag is set to YES Doxygen will
+# generate a Perl module file that captures the structure of
+# the code including all documentation. Note that this
+# feature is still experimental and incomplete at the
+# moment.
+
+GENERATE_PERLMOD = NO
+
+# If the PERLMOD_LATEX tag is set to YES Doxygen will generate
+# the necessary Makefile rules, Perl scripts and LaTeX code to be able
+# to generate PDF and DVI output from the Perl module output.
+
+PERLMOD_LATEX = NO
+
+# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be
+# nicely formatted so it can be parsed by a human reader. This is useful
+# if you want to understand what is going on. On the other hand, if this
+# tag is set to NO the size of the Perl module output will be much smaller
+# and Perl will parse it just the same.
+
+PERLMOD_PRETTY = YES
+
+# The names of the make variables in the generated doxyrules.make file
+# are prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX.
+# This is useful so different doxyrules.make files included by the same
+# Makefile don't overwrite each other's variables.
+
+PERLMOD_MAKEVAR_PREFIX =
+
+#---------------------------------------------------------------------------
+# Configuration options related to the preprocessor
+#---------------------------------------------------------------------------
+
+# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will
+# evaluate all C-preprocessor directives found in the sources and include
+# files.
+
+ENABLE_PREPROCESSING = YES
+
+# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro
+# names in the source code. If set to NO (the default) only conditional
+# compilation will be performed. Macro expansion can be done in a controlled
+# way by setting EXPAND_ONLY_PREDEF to YES.
+
+MACRO_EXPANSION = NO
+
+# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES
+# then the macro expansion is limited to the macros specified with the
+# PREDEFINED and EXPAND_AS_DEFINED tags.
+
+MACRO_EXPANSION = YES
+EXPAND_ONLY_PREDEF = NO
+
+# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files
+# in the INCLUDE_PATH (see below) will be search if a #include is found.
+
+SEARCH_INCLUDES = YES
+
+# The INCLUDE_PATH tag can be used to specify one or more directories that
+# contain include files that are not input files but should be processed by
+# the preprocessor.
+
+INCLUDE_PATH = ${abs_top_srcdir} ${abs_top_builddir}
+
+# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard
+# patterns (like *.h and *.hpp) to filter out the header-files in the
+# directories. If left blank, the patterns specified with FILE_PATTERNS will
+# be used.
+
+INCLUDE_FILE_PATTERNS = *
+
+# The PREDEFINED tag can be used to specify one or more macro names that
+# are defined before the preprocessor is started (similar to the -D option of
+# gcc). The argument of the tag is a list of macros of the form: name
+# or name=definition (no spaces). If the definition and the = are
+# omitted =1 is assumed. To prevent a macro definition from being
+# undefined via #undef or recursively expanded use the := operator
+# instead of the = operator.
+
+PREDEFINED =
+
+# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then
+# this tag can be used to specify a list of macro names that should be expanded.
+# The macro definition that is found in the sources will be used.
+# Use the PREDEFINED tag if you want to use a different macro definition.
+
+EXPAND_AS_DEFINED =
+
+# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then
+# doxygen's preprocessor will remove all function-like macros that are alone
+# on a line, have an all uppercase name, and do not end with a semicolon. Such
+# function macros are typically used for boiler-plate code, and will confuse
+# the parser if not removed.
+
+SKIP_FUNCTION_MACROS = YES
+
+#---------------------------------------------------------------------------
+# Configuration::additions related to external references
+#---------------------------------------------------------------------------
+
+# The TAGFILES option can be used to specify one or more tagfiles.
+# Optionally an initial location of the external documentation
+# can be added for each tagfile. The format of a tag file without
+# this location is as follows:
+# TAGFILES = file1 file2 ...
+# Adding location for the tag files is done as follows:
+# TAGFILES = file1=loc1 "file2 = loc2" ...
+# where "loc1" and "loc2" can be relative or absolute paths or
+# URLs. If a location is present for each tag, the installdox tool
+# does not have to be run to correct the links.
+# Note that each tag file must have a unique name
+# (where the name does NOT include the path)
+# If a tag file is not located in the directory in which doxygen
+# is run, you must also specify the path to the tagfile here.
+
+TAGFILES =
+
+# When a file name is specified after GENERATE_TAGFILE, doxygen will create
+# a tag file that is based on the input files it reads.
+
+GENERATE_TAGFILE = ${abs_top_builddir}/doc/${PROJECT}.tag
+
+# If the ALLEXTERNALS tag is set to YES all external classes will be listed
+# in the class index. If set to NO only the inherited external classes
+# will be listed.
+
+ALLEXTERNALS = NO
+
+# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed
+# in the modules index. If set to NO, only the current project's groups will
+# be listed.
+
+EXTERNAL_GROUPS = YES
+
+# The PERL_PATH should be the absolute path and name of the perl script
+# interpreter (i.e. the result of `which perl').
+
+PERL_PATH = ${PERL_PATH}
+
+#---------------------------------------------------------------------------
+# Configuration options related to the dot tool
+# Configuration options related to the dot tool
+#---------------------------------------------------------------------------
+
+# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will
+# generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base
+# or super classes. Setting the tag to NO turns the diagrams off. Note that
+# this option is superseded by the HAVE_DOT option below. This is only a
+# fallback. It is recommended to install and use dot, since it yields more
+# powerful graphs.
+
+CLASS_DIAGRAMS = NO
+
+# You can define message sequence charts within doxygen comments using the \msc
+# command. Doxygen will then run the mscgen tool (see
+# http://www.mcternan.me.uk/mscgen/) to produce the chart and insert it in the
+# documentation. The MSCGEN_PATH tag allows you to specify the directory where
+# the mscgen tool resides. If left empty the tool is assumed to be found in the
+# default search path.
+
+MSCGEN_PATH =
+
+# If set to YES, the inheritance and collaboration graphs will hide
+# inheritance and usage relations if the target is undocumented
+# or is not a class.
+
+HIDE_UNDOC_RELATIONS = YES
+
+# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is
+# available from the path. This tool is part of Graphviz, a graph visualization
+# toolkit from AT&T and Lucent Bell Labs. The other options in this section
+# have no effect if this option is set to NO (the default)
+
+HAVE_DOT = ${HAVE_DOT}
+
+# By default doxygen will write a font called FreeSans.ttf to the output
+# directory and reference it in all dot files that doxygen generates. This
+# font does not include all possible unicode characters however, so when you need
+# these (or just want a differently looking font) you can specify the font name
+# using DOT_FONTNAME. You need need to make sure dot is able to find the font,
+# which can be done by putting it in a standard location or by setting the
+# DOTFONTPATH environment variable or by setting DOT_FONTPATH to the directory
+# containing the font.
+
+DOT_FONTNAME = FreeSans
+
+# By default doxygen will tell dot to use the output directory to look for the
+# FreeSans.ttf font (which doxygen will put there itself). If you specify a
+# different font using DOT_FONTNAME you can set the path where dot
+# can find it using this tag.
+
+DOT_FONTPATH =
+
+# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen
+# will generate a graph for each documented class showing the direct and
+# indirect inheritance relations. Setting this tag to YES will force the
+# the CLASS_DIAGRAMS tag to NO.
+
+CLASS_GRAPH = YES
+
+# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen
+# will generate a graph for each documented class showing the direct and
+# indirect implementation dependencies (inheritance, containment, and
+# class references variables) of the class with other documented classes.
+
+COLLABORATION_GRAPH = NO
+
+# If the GROUP_GRAPHS and HAVE_DOT tags are set to YES then doxygen
+# will generate a graph for groups, showing the direct groups dependencies
+
+GROUP_GRAPHS = YES
+
+# If the UML_LOOK tag is set to YES doxygen will generate inheritance and
+# collaboration diagrams in a style similar to the OMG's Unified Modeling
+# Language.
+
+UML_LOOK = NO
+
+# If set to YES, the inheritance and collaboration graphs will show the
+# relations between templates and their instances.
+
+TEMPLATE_RELATIONS = NO
+
+# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT
+# tags are set to YES then doxygen will generate a graph for each documented
+# file showing the direct and indirect include dependencies of the file with
+# other documented files.
+
+INCLUDE_GRAPH = YES
+
+# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and
+# HAVE_DOT tags are set to YES then doxygen will generate a graph for each
+# documented header file showing the documented files that directly or
+# indirectly include this file.
+
+INCLUDED_BY_GRAPH = YES
+
+# If the CALL_GRAPH and HAVE_DOT options are set to YES then
+# doxygen will generate a call dependency graph for every global function
+# or class method. Note that enabling this option will significantly increase
+# the time of a run. So in most cases it will be better to enable call graphs
+# for selected functions only using the \callgraph command.
+
+CALL_GRAPH = NO
+
+# If the CALLER_GRAPH and HAVE_DOT tags are set to YES then
+# doxygen will generate a caller dependency graph for every global function
+# or class method. Note that enabling this option will significantly increase
+# the time of a run. So in most cases it will be better to enable caller
+# graphs for selected functions only using the \callergraph command.
+
+CALLER_GRAPH = NO
+
+# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen
+# will graphical hierarchy of all classes instead of a textual one.
+
+GRAPHICAL_HIERARCHY = YES
+
+# If the DIRECTORY_GRAPH, SHOW_DIRECTORIES and HAVE_DOT tags are set to YES
+# then doxygen will show the dependencies a directory has on other directories
+# in a graphical way. The dependency relations are determined by the #include
+# relations between the files in the directories.
+
+DIRECTORY_GRAPH = YES
+
+# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images
+# generated by dot. Possible values are png, jpg, or gif
+# If left blank png will be used.
+
+DOT_IMAGE_FORMAT = png
+
+# The tag DOT_PATH can be used to specify the path where the dot tool can be
+# found. If left blank, it is assumed the dot tool can be found in the path.
+
+DOT_PATH = ${DOT_PATH}
+
+# The DOTFILE_DIRS tag can be used to specify one or more directories that
+# contain dot files that are included in the documentation (see the
+# \dotfile command).
+
+DOTFILE_DIRS =
+
+# The DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of
+# nodes that will be shown in the graph. If the number of nodes in a graph
+# becomes larger than this value, doxygen will truncate the graph, which is
+# visualized by representing a node as a red box. Note that doxygen if the
+# number of direct children of the root node in a graph is already larger than
+# DOT_GRAPH_MAX_NODES then the graph will not be shown at all. Also note
+# that the size of a graph can be further restricted by MAX_DOT_GRAPH_DEPTH.
+
+DOT_GRAPH_MAX_NODES = 50
+
+# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the
+# graphs generated by dot. A depth value of 3 means that only nodes reachable
+# from the root by following a path via at most 3 edges will be shown. Nodes
+# that lay further from the root node will be omitted. Note that setting this
+# option to 1 or 2 may greatly reduce the computation time needed for large
+# code bases. Also note that the size of a graph can be further restricted by
+# DOT_GRAPH_MAX_NODES. Using a depth of 0 means no depth restriction.
+
+MAX_DOT_GRAPH_DEPTH = 0
+
+# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent
+# background. This is enabled by default, which results in a transparent
+# background. Warning: Depending on the platform used, enabling this option
+# may lead to badly anti-aliased labels on the edges of a graph (i.e. they
+# become hard to read).
+
+DOT_TRANSPARENT = YES
+
+# Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output
+# files in one run (i.e. multiple -o and -T options on the command line). This
+# makes dot run faster, but since only newer versions of dot (>1.8.10)
+# support this, this feature is disabled by default.
+
+DOT_MULTI_TARGETS = NO
+
+# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will
+# generate a legend page explaining the meaning of the various boxes and
+# arrows in the dot generated graphs.
+
+GENERATE_LEGEND = YES
+
+# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will
+# remove the intermediate dot files that are used to generate
+# the various graphs.
+
+DOT_CLEANUP = YES
+
+#---------------------------------------------------------------------------
+# Configuration::additions related to the search engine
+#---------------------------------------------------------------------------
+# The SEARCHENGINE tag specifies whether or not a search engine should be
+# used. If set to NO the values of all tags below this one will be ignored.
+SEARCHENGINE = NO
+
+GENERATE_QHP = ${GENERATE_QHP}
+QHP_NAMESPACE = "org.freedesktop.Telepathy.Qt4.Yell"
+QHP_VIRTUAL_FOLDER = "${PROJECT_NAME}-${PACKAGE_VERSION}"
+QCH_FILE = ${abs_top_builddir}/doc/help/telepathy-qt4-yell.qch
+QHG_LOCATION = ${QHELPGENERATOR_EXECUTABLE}"
+
+### TelepathyQt4Yell Settings
+ALIASES = \
+ "intern=\par<b>Internal use only.</b>" \
+ "reimp=\par<b>Reimplemented from superclass.</b>" \
+ "obsolete=@deprecated" \
+ "feature=\xrefitem features \"Feature(s)\" \"Features\"" \
+ "maintainer=\xrefitem maintainers \"Maintainer(s)\" \"Maintainers\"" \
+ "unmaintained=\xrefitem unmaintained \"Unmaintained\" \"Unmaintained\"" \
+ "requirement=\xrefitem requirements \"Requirement(s)\" \"Requirements\"" \
+ "faq=\xrefitem FAQ \"F.A.Q.\" \"F.A.Q.\"" \
+ "authors=\xrefitem authors \"Author(s)\" \"Authors\"" \
+ "maintainers=\xrefitem maintainers \"Maintainer(s)\" \"Maintainers\"" \
+ "glossary=\xrefitem glossary \"TelepathyQt4Yell Glossary\" \"TelepathyQt4Yell Glossary\"" \
+ "acronym=\b "\
+ "licenses=\xrefitem licenses \"License(s)\" \"Licenses\"" \
+ "short=@brief "\
+ "FIXME=\xrefitem fixme \"Fixme\" \"Fixme\"" \
+ "bc=\xrefitem bc \"Binary Compatible\" \"Binary Compatible\"" \
+ "telepathy=<a href=\"http://telepathy.freedesktop.org\">Telepathy</a>" \
+ "dbus=<a href=\"http://dbus.freedesktop.org\">D-Bus</a>" \
+ "artistic=<a href=\"http://www.opensource.org/licenses/artistic-license.php\">Artistic</a>" \
+ "bsd=<a href=\"http://www.xfree86.org/3.3.6/COPYRIGHT2.html#5\">BSD</a>" \
+ "x11=<a href=\"http://www.xfree86.org/3.3.6/COPYRIGHT2.html#3\">X11</a>" \
+ "gpl=<a href=\"http://www.fsf.org/licensing/licenses/gpl.html#SEC1\">GPL</a>" \
+ "lgpl=<a href=\"http://www.fsf.org/licensing/licenses/lgpl.html#SEC1\">LGPL</a>" \
+ "qpl=<a href=\"http://www.trolltech.com/products/qt/licenses\">QPL</a>"
+
+PREDEFINED = DOXYGEN_SHOULD_SKIP_THIS \
+ TELEPATHY_QT4_YELL_EXPORT="" \
+ TELEPATHY_QT4_YELL_NO_EXPORT="" \
+ Q_SLOTS="slots" \
+ Q_SIGNALS="signals"
diff --git a/doxygen.css b/doxygen.css
new file mode 100644
index 0000000..04977c2
--- /dev/null
+++ b/doxygen.css
@@ -0,0 +1,434 @@
+body, table, div, p, dl {
+ font-family: Lucida Grande, Verdana, Geneva, Arial, sans-serif;
+ font-size: 12px;
+}
+
+/* @group Heading Levels */
+
+h1 {
+ text-align: center;
+ font-size: 150%;
+}
+
+h2 {
+ font-size: 110%;
+ font-weight: bold;
+}
+
+h3 {
+ font-size: 100%;
+}
+
+h3.version {
+ font-size: 100%;
+ text-align: center;
+}
+
+/* @end */
+
+caption {
+ font-weight: bold;
+}
+
+div.qindex, div.navtab{
+ background-color: #e8eef2;
+ border: 1px solid #84b0c7;
+ text-align: center;
+ margin: 2px;
+ padding: 2px;
+}
+
+div.qindex, div.navpath {
+ width: 100%;
+ line-height: 140%;
+}
+
+div.navtab {
+ margin-right: 15px;
+}
+
+/* @group Link Styling */
+
+a {
+ color: #153788;
+ font-weight: normal;
+ text-decoration: none;
+}
+
+.contents a:visited {
+ color: #1b77c5;
+}
+
+a:hover {
+ text-decoration: underline;
+}
+
+a.qindex {
+ font-weight: bold;
+}
+
+a.qindexHL {
+ font-weight: bold;
+ background-color: #6666cc;
+ color: #ffffff;
+ border: 1px double #9295C2;
+}
+
+.contents a.qindexHL:visited {
+ color: #ffffff;
+}
+
+a.el {
+}
+
+a.elRef {
+}
+
+a.code {
+}
+
+a.codeRef {
+}
+
+/* @end */
+
+dl.el {
+ margin-left: -1cm;
+}
+
+.fragment {
+ font-family: monospace, fixed;
+ font-size: 100%;
+}
+
+pre.fragment {
+ border: 1px solid #CCCCCC;
+ background-color: #f5f5f5;
+ padding: 4px 6px;
+ margin: 4px 8px 4px 2px;
+}
+
+div.ah {
+ background-color: black;
+ font-weight: bold;
+ color: #ffffff;
+ margin-bottom: 3px;
+ margin-top: 3px
+}
+
+div.groupHeader {
+ margin-left: 16px;
+ margin-top: 12px;
+ margin-bottom: 6px;
+ font-weight: bold;
+}
+
+div.groupText {
+ margin-left: 16px;
+ font-style: italic;
+}
+
+body {
+ background: white;
+ color: black;
+ margin-right: 20px;
+ margin-left: 20px;
+}
+
+td.indexkey {
+ background-color: #e8eef2;
+ font-weight: bold;
+ border: 1px solid #CCCCCC;
+ margin: 2px 0px 2px 0;
+ padding: 2px 10px;
+}
+
+td.indexvalue {
+ background-color: #e8eef2;
+ border: 1px solid #CCCCCC;
+ padding: 2px 10px;
+ margin: 2px 0px;
+}
+
+tr.memlist {
+ background-color: #f0f0f0;
+}
+
+p.formulaDsp {
+ text-align: center;
+}
+
+img.formulaDsp {
+
+}
+
+img.formulaInl {
+ vertical-align: middle;
+}
+
+/* @group Code Colorization */
+
+span.keyword {
+ color: #008000
+}
+
+span.keywordtype {
+ color: #604020
+}
+
+span.keywordflow {
+ color: #e08000
+}
+
+span.comment {
+ color: #800000
+}
+
+span.preprocessor {
+ color: #806020
+}
+
+span.stringliteral {
+ color: #002080
+}
+
+span.charliteral {
+ color: #008080
+}
+
+span.vhdldigit {
+ color: #ff00ff
+}
+
+span.vhdlchar {
+ color: #000000
+}
+
+span.vhdlkeyword {
+ color: #700070
+}
+
+span.vhdllogic {
+ color: #ff0000
+}
+
+/* @end */
+
+.search {
+ color: #003399;
+ font-weight: bold;
+}
+
+form.search {
+ margin-bottom: 0px;
+ margin-top: 0px;
+}
+
+input.search {
+ font-size: 75%;
+ color: #000080;
+ font-weight: normal;
+ background-color: #e8eef2;
+}
+
+td.tiny {
+ font-size: 75%;
+}
+
+.dirtab {
+ padding: 4px;
+ border-collapse: collapse;
+ border: 1px solid #84b0c7;
+}
+
+th.dirtab {
+ background: #e8eef2;
+ font-weight: bold;
+}
+
+hr {
+ height: 0;
+ border: none;
+ border-top: 1px solid #666;
+}
+
+/* @group Member Descriptions */
+
+.mdescLeft, .mdescRight,
+.memItemLeft, .memItemRight,
+.memTemplItemLeft, .memTemplItemRight, .memTemplParams {
+ background-color: #FAFAFA;
+ border: none;
+ margin: 4px;
+ padding: 1px 0 0 8px;
+}
+
+.mdescLeft, .mdescRight {
+ padding: 0px 8px 4px 8px;
+ color: #555;
+}
+
+.memItemLeft, .memItemRight, .memTemplParams {
+ border-top: 1px solid #ccc;
+}
+
+.memTemplParams {
+ color: #606060;
+}
+
+/* @end */
+
+/* @group Member Details */
+
+/* Styles for detailed member documentation */
+
+.memtemplate {
+ font-size: 80%;
+ color: #606060;
+ font-weight: normal;
+ margin-left: 3px;
+}
+
+.memnav {
+ background-color: #e8eef2;
+ border: 1px solid #84b0c7;
+ text-align: center;
+ margin: 2px;
+ margin-right: 15px;
+ padding: 2px;
+}
+
+.memitem {
+ padding: 0;
+}
+
+.memname {
+ white-space: nowrap;
+ font-weight: bold;
+}
+
+.memproto {
+ padding: 0;
+ background-color: #d5e1e8;
+ font-weight: bold;
+ border: 1px solid #84b0c7;
+}
+
+.memdoc {
+ padding: 2px 5px;
+ border-top-width: 0;
+}
+
+.paramkey {
+ text-align: right;
+}
+
+.paramtype {
+ white-space: nowrap;
+}
+
+.paramname {
+ color: #602020;
+ white-space: nowrap;
+}
+.paramname em {
+ font-style: normal;
+}
+
+/* @end */
+
+/* @group Directory (tree) */
+
+/* for the tree view */
+
+.ftvtree {
+ font-family: sans-serif;
+ margin: 0.5em;
+}
+
+/* these are for tree view when used as main index */
+
+.directory {
+ font-size: 9pt;
+ font-weight: bold;
+}
+
+.directory h3 {
+ margin: 0px;
+ margin-top: 1em;
+ font-size: 11pt;
+}
+
+/*
+The following two styles can be used to replace the root node title
+with an image of your choice. Simply uncomment the next two styles,
+specify the name of your image and be sure to set 'height' to the
+proper pixel height of your image.
+*/
+
+/*
+.directory h3.swap {
+ height: 61px;
+ background-repeat: no-repeat;
+ background-image: url("yourimage.gif");
+}
+.directory h3.swap span {
+ display: none;
+}
+*/
+
+.directory > h3 {
+ margin-top: 0;
+}
+
+.directory p {
+ margin: 0px;
+ white-space: nowrap;
+}
+
+.directory div {
+ display: none;
+ margin: 0px;
+}
+
+.directory img {
+ vertical-align: -30%;
+}
+
+/* these are for tree view when not used as main index */
+
+.directory-alt {
+ font-size: 100%;
+ font-weight: bold;
+}
+
+.directory-alt h3 {
+ margin: 0px;
+ margin-top: 1em;
+ font-size: 11pt;
+}
+
+.directory-alt > h3 {
+ margin-top: 0;
+}
+
+.directory-alt p {
+ margin: 0px;
+ white-space: nowrap;
+}
+
+.directory-alt div {
+ display: none;
+ margin: 0px;
+}
+
+.directory-alt img {
+ vertical-align: -30%;
+}
+
+/* @end */
+
+address {
+ font-style: normal;
+ color: #333;
+}
diff --git a/spec/Account.xml b/spec/Account.xml
new file mode 100644
index 0000000..acd8c30
--- /dev/null
+++ b/spec/Account.xml
@@ -0,0 +1,733 @@
+<?xml version="1.0" ?>
+<node name="/Account"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+<p>This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.</p>
+
+<p>This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+Lesser General Public License for more details.</p>
+
+<p>You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+</p>
+ </tp:license>
+ <interface name="org.freedesktop.Telepathy.Account">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An Account object encapsulates the necessary details to make a
+ Telepathy connection.</p>
+
+ <p>Accounts are uniquely identified by object path. The object path
+ of an Account MUST take the form
+ <code>/org/freedesktop/Telepathy/Account/<em>cm</em>/<em>proto</em>/<em>acct</em></code>, where:</p>
+
+ <ul>
+ <li><em>cm</em> is the same <tp:type>Connection_Manager_Name</tp:type>
+ that appears in the connection manager's well-known bus name and
+ object path</li>
+ <li><em>proto</em> is the <tp:type>Protocol</tp:type> name as seen in
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ConnectionManager.ListProtocols</tp:dbus-ref>,
+ but with "-" replaced with "_"
+ (i.e. the same as in the object-path of a <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>)</li>
+ <li><em>acct</em> is an arbitrary string of ASCII letters, digits
+ and underscores, starting with a letter or underscore, which
+ uniquely identifies this account</li>
+ <li>Clients SHOULD parse the object path to discover the
+ connection manager and protocol</li>
+ <li>Clients MUST NOT attempt to parse <em>acct</em></li>
+ <li>Clients MUST NOT assume that <em>acct</em> matches
+ the connection-specific part of a Connection's object-path and
+ bus name</li>
+ <li>The account manager SHOULD choose <em>acct</em> such that if
+ an account is deleted, its object path will be re-used if and only
+ if the new account is in some sense "the same"
+ (incorporating the 'account' parameter in some way is
+ recommended)</li>
+ </ul>
+
+ <tp:rationale>
+ <p>This API avoids specifying the "profiles" used in Mission Control
+ 4.x or the "presets" that have been proposed to replace them. An
+ optional interface will be provided for AM implementations
+ that want to provide presets.</p>
+
+ <p>There is deliberately no functionality here for opening channels;
+ we intend to provide that in the channel dispatcher.</p>
+
+ <p>Other missing features which would be better in their own
+ interfaces:</p>
+
+ <ul>
+ <li>dynamic parameter-providing (aka provisioning)</li>
+ <li>saved server capabilities</li>
+ <li>account conditions</li>
+ <li>account grouping</li>
+ </ul>
+ </tp:rationale>
+
+ </tp:docstring>
+ <tp:added version="0.17.2"/>
+ <tp:changed version="0.17.6">moved the Avatar property to a separate
+ interface</tp:changed>
+
+ <!-- Missing functionality compared with NMC 4.x account + profile,
+ apart from as listed above:
+
+ * vCard field, + default profile for each vCard field
+ (vCard field is per protocol and should be chosen by the
+ Telepathy <-> address-book bridge?; default profile is now
+ meaningless)
+
+ * "normalized name" (normalized handle?)
+
+ * branding icon (what's this and how does it differ from the icon?)
+
+ * configuration UI (not our problem - perhaps the UI could special-case
+ by cm,protocol,preset tuples?)
+
+ * default account domain (somewhat meaningless in general; specialized
+ account config UI can hard-code this)
+
+ * SPLIT_ACCOUNT (pseudo-capability - this is a property of the protocol,
+ not the profile, and in any case only the account config UI cares)
+
+ Missing functionality compared with Decibel accounts:
+
+ * we don't really know, they take arbitrary key/value pairs...
+ but display name, protocol, presence/message, current, autoreconnect
+ are the ones given special status by the source, and we have all of them
+ -->
+
+ <property name="Interfaces" tp:name-for-bindings="Interfaces"
+ type="as" tp:type="DBus_Interface[]" access="read">
+ <tp:docstring>
+ A list of the extra interfaces provided by this account.
+ </tp:docstring>
+ </property>
+
+ <method name="Remove" tp:name-for-bindings="Remove">
+ <tp:docstring>Delete the account.</tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
+ </tp:possible-errors>
+ </method>
+
+ <signal name="Removed" tp:name-for-bindings="Removed">
+ <tp:docstring>
+ This account has been removed.
+
+ <tp:rationale>
+ This is redundant with <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.AccountManager">AccountRemoved</tp:dbus-ref>,
+ but it's still worth having,
+ to avoid having to bind to AccountManager.AccountRemoved to tell
+ you whether your Account is valid — ideally, an account-editing UI
+ should only care about a single Account.
+ </tp:rationale>
+ </tp:docstring>
+ </signal>
+
+ <signal name="AccountPropertyChanged"
+ tp:name-for-bindings="Account_Property_Changed">
+ <tp:docstring>
+ The values of one or more properties on this interface (that do not
+ specify that this signal does not apply to them) may have changed.
+ This does not cover properties of other interfaces, which must
+ provide their own change notification if appropriate.
+ </tp:docstring>
+
+ <arg name="Properties" type="a{sv}">
+ <tp:docstring>
+ A map from property names in this namespace (e.g.
+ <tp:member-ref>Nickname</tp:member-ref>) to
+ values. Properties whose values have not changed SHOULD be
+ omitted, but this need not be done.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <property name="DisplayName" type="s" access="readwrite"
+ tp:name-for-bindings="Display_Name">
+ <tp:docstring>
+ The user-visible name of this account. This SHOULD be chosen by the
+ user at account creation time. The account creation user interface
+ is responsible for setting a reasonable default value in the user's
+ locale; something like "Jabber (bob@example.com)" would be sensible.
+
+ <tp:rationale>
+ This approximately corresponds to "display name" in NMC 4.x and
+ Decibel.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="Icon" tp:name-for-bindings="Icon"
+ type="s" access="readwrite">
+ <tp:docstring>
+ The name of an icon in the system's icon theme, such as "im-msn",
+ or the empty string to not specify an icon. If the icon is set to
+ an empty string, the account manager or any client MAY derive a
+ default icon, for instance from the protocol.
+
+ <tp:rationale>
+ This approximately corresponds to mc_profile_get_icon_name
+ (or possibly mc_profile_get_branding_icon_name) in NMC 4.x.
+ It's accessed via the account rather than the profile because
+ we no longer have profiles as a core concept.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="Valid" tp:name-for-bindings="Valid"
+ type="b" access="read">
+ <tp:docstring>
+ If true, this account is considered by the account manager to be
+ complete and usable. If false, user action is required to make it
+ usable, and it will never attempt to connect (for instance, this
+ might be caused by the absence of a required parameter).
+
+ <tp:rationale>
+ For connection managers with a plugin architecture, like
+ telepathy-haze, we have little or no control over the parameters
+ offered; for platforms with package management, we have little or
+ no control over the CMs offered. NMC 4.x would just pretend the
+ account didn't exist in these circumstances, but silent data loss
+ is bad, and UIs with CM-specific knowledge (or a user filling in
+ newly-required parameters) might be able to rescue a broken account.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="Enabled" tp:name-for-bindings="Enabled"
+ type="b" access="readwrite">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This property gives the users the possibility to prevent an account
+ from being used. This flag does not change the validity of the
+ account.</p>
+
+ <p>A disabled account can never be put online.</p>
+
+ <tp:rationale>
+ <p>Use cases:</p>
+
+ <ul>
+ <li>user has two or more accounts capable of calling contact X, but
+ he doesn't want the UI to prompt him everytime about which one he
+ wants to use for the call. He can then disable all the equivalent
+ accounts but one.</li>
+
+ <li>There is some temporary server error and the user doesn't want
+ to be be bother by error messages, or change the account
+ configuration: temporarily disabling the account is quicker.</li>
+ </ul>
+ </tp:rationale>
+
+ <p>The AccountManager SHOULD allow this property to be set on invalid
+ accounts, but MUST NOT attempt to put invalid accounts online
+ even if they become Enabled.</p>
+
+ <tp:rationale>
+ <p>There doesn't seem to be any good reason not to allow this.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="Nickname" tp:name-for-bindings="Nickname"
+ type="s" access="readwrite">
+ <tp:docstring>
+ The nickname to set on this account for display to other contacts,
+ as set by the user. When the account becomes connected, the
+ account manager SHOULD set this as the user's alias using <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Aliasing">SetAliases</tp:dbus-ref>
+ if appropriate.
+
+ <tp:rationale>
+ In a later specification revision, we plan to separate the concepts
+ of a contact's nickname as set by themselves, and the local
+ name for them in our contact list (a "handle" or "pet name" as
+ described in XEP-0165 and its references). The terminology change
+ from alias to nickname here is a step in that direction.
+ This corresponds to NMC 4.x mc_account_get_alias.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="Service" tp:name-for-bindings="Service" type="s"
+ access="readwrite">
+ <tp:added version="0.19.8"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Some protocols, like XMPP and SIP, are used by various different
+ user-recognised brands, such as <i>Google Talk</i> and <i>Ovi by
+ Nokia</i>. On accounts for such services, this property SHOULD be
+ set to a string describing the service, which MUST consist only of
+ ASCII letters, numbers and hyphen/minus signs, and start with a
+ letter (matching the requirements for <tp:type>Protocol</tp:type>).
+ For the <tt>jabber</tt> protocol, one of the following service names
+ should be used if possible:</p>
+
+ <ul>
+ <li><tt>google-talk</tt> (for <a
+ href="http://www.google.com/talk/">Google's IM service</a>)</li>
+ <li><tt>ovi-chat</tt> (for <a href="http://www.ovi.com/">Ovi</a>'s IM
+ service)</li>
+ <li><tt>facebook</tt> (for <a
+ href="http://www.facebook.com/sitetour/chat.php">Facebook's IM
+ service</a>)</li>
+ <li><tt>lj-talk</tt> (for <a
+ href="http://www.livejournal.com/chat/">LiveJournal's IM
+ service</a>)</li>
+
+ </ul>
+
+ <p>The <tp:member-ref>Icon</tp:member-ref> property SHOULD be set to a
+ corresponding brand-specific icon name, if possible. In the future,
+ this property may be used as an index into additional
+ service-specific customizations. If this property is the empty string
+ (or missing), the service is determined by the protocol name (either
+ because this is a single-service protocol like <tt>msn</tt>, or
+ because this is just a generic <tt>jabber</tt> or <tt>sip</tt>
+ account without specific branding).</p>
+
+ <p>This property MAY be set, if appropriate, when calling
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.AccountManager"
+ >CreateAccount</tp:dbus-ref>. Updating this property will fail on
+ externally-stored accounts whose <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account.Interface.Storage"
+ >StorageRestrictions</tp:dbus-ref> include
+ <code>Cannot_Set_Service</code>.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="Parameters" tp:name-for-bindings="Parameters"
+ type="a{sv}" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A map from connection manager parameter names (as in the
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ConnectionManager</tp:dbus-ref>
+ interface) to their values. This property includes
+ only those parameters that are stored for this account, and SHOULD
+ only include those parameters that the user has explicitly set.
+ </p>
+ <p>This property cannot be altered using Set() - use
+ <tp:member-ref>UpdateParameters</tp:member-ref> instead.</p>
+ </tp:docstring>
+ </property>
+
+ <method name="UpdateParameters" tp:name-for-bindings="Update_Parameters">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Change the value of the <tp:member-ref>Parameters</tp:member-ref>
+ property.</p>
+
+ <p>If any of the changed parameters'
+ <tp:type>Conn_Mgr_Param_Flags</tp:type> include
+ <code>DBus_Property</code>, the change will be applied immediately to
+ the
+ corresponding D-Bus Property on the active
+ <tp:member-ref>Connection</tp:member-ref>, if there is one. Changes to
+ other parameters will not take effect until the next time the account
+ is disconnected and reconnected.</p>
+
+ <tp:rationale>
+ <p>In general, reconnecting is a destructive operation that shouldn't
+ happen as a side-effect. In particular, migration tools that
+ twiddle the settings of all accounts shouldn't cause an automatic
+ disconnect and reconnect.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <tp:changed version="0.17.16">
+ parameters which are also D-Bus properties can and should be updated on
+ existing Connections
+ </tp:changed>
+
+ <tp:changed version="0.17.24">
+ return an array of the parameters that won't change until the account
+ is reconnected
+ </tp:changed>
+
+ <arg name="Set" type="a{sv}" direction="in">
+ <tp:docstring>
+ A mapping from parameter names to their values. These parameters
+ should be stored for future use.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Unset" type="as" direction="in">
+ <tp:docstring>
+ A list of the names of parameters to be removed from the set of
+ stored values, allowing the default values to be used.
+ If the given parameters were not, in fact, stored, or even if they
+ do not exist at all, the account manager MUST accept this without
+ error.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Reconnect_Required" type="as" direction="out">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If all of the parameters had the <code>DBus_Property</code> flag,
+ the empty list, signifying that no reconnection is required for the
+ new parameters to take effect. For example, if the only parameter
+ updated is <tt>...Cellular.<tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Cellular">MessageValidityPeriod</tp:dbus-ref></tt>,
+ the new value can be applied immediately to the connection.</p>
+
+ <p>Otherwise, a list of the names of parameters with changes that
+ will not take effect until the account is reconnected. User
+ interfaces that require "instant apply" semantics MAY call
+ <tp:member-ref>Reconnect</tp:member-ref> in response to receiving a
+ non-empty list. For example, if the caller updates both
+ <tt>...Anonymity.<tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Anonymity">AnonymityMandatory</tp:dbus-ref></tt>
+ and <tt>require-encryption</tt>, the former can be applied to the
+ current connection, but the latter needs a reconnect to take
+ effect, so this method should return
+ <code>["require-encryption"]</code>.</p>
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
+ </tp:possible-errors>
+ </method>
+
+ <property name="AutomaticPresence" type="(uss)" access="readwrite"
+ tp:type="Simple_Presence" tp:name-for-bindings="Automatic_Presence">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The presence status that this account should have if it is brought
+ online.</p>
+
+ <tp:rationale>
+ In ITOS2007 and ITOS2008 this is a global preference, not visible
+ on D-Bus (the "default presence"). "Automatic presence" better
+ describes when it is used.
+ </tp:rationale>
+
+ <p>Setting this property MUST NOT actually change the account's
+ status until the next time it is (re)connected for some reason.</p>
+
+ <p>The value of this property MUST be one that would be acceptable
+ for <tp:member-ref>RequestedPresence</tp:member-ref>,
+ with the additional restriction that the
+ <tp:type>Connection_Presence_Type</tp:type> MUST NOT be Offline.</p>
+
+ <tp:rationale>
+ <p>Otherwise, it would not be possible to use this presence to bring
+ the account online for a channel request.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="ConnectAutomatically" type="b" access="readwrite"
+ tp:name-for-bindings="Connect_Automatically">
+ <tp:docstring>
+ If true, the account manager SHOULD attempt to put this account
+ online with the <tp:member-ref>AutomaticPresence</tp:member-ref>
+ whenever possible (in the base
+ Account interface this is deliberately left vague). If false,
+ it MUST NOT put the account online automatically in response to,
+ for instance, connectivity changes, but SHOULD still put the account
+ online with the <tp:member-ref>AutomaticPresence</tp:member-ref> if
+ requested by the user (for
+ instance, if the user tries to start a conversation using this
+ account).
+
+ <tp:rationale>
+ This approximately corresponds to NMC 4.x "enabled" and Decibel
+ "autoreconnect".
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="Connection" tp:name-for-bindings="Connection"
+ type="o" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Either the object path of the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> to
+ this account, or the special value <code>'/'</code> if there is no
+ connection.</p>
+
+ <p>If this object path is not '/', the Connection's well-known bus
+ name can be derived from this object path by removing the first '/'
+ and replacing subsequent '/' characters with '.'.</p>
+
+ <tp:rationale>
+ Object paths aren't nullable, so we can't use an empty string.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="ConnectionStatus" type="u" tp:type="Connection_Status"
+ access="read" tp:name-for-bindings="Connection_Status">
+ <tp:docstring>
+ If the <tp:member-ref>Connection</tp:member-ref> property is non-empty,
+ the status of that connection.
+ If the Connection property is the empty string, this property may
+ either be Disconnected (indicating that the account manager is not
+ attempting to bring it online), or Connecting (indicating that the
+ account manager is attempting to connect).
+ The account manager is expected to set this by observing signals
+ from the Connection.
+
+ <tp:rationale>
+ If the AM is doing some sort of backoff/delay on reconnection
+ attempts, the account's status is conceptually "Connecting" even
+ though there is no Connection. This vaguely corresponds to
+ GetCurrentStatus in NMC 4.x.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="ConnectionStatusReason" type="u"
+ tp:type="Connection_Status_Reason" access="read"
+ tp:name-for-bindings="Connection_Status_Reason">
+ <tp:docstring>
+ The reason for the last change to
+ <tp:member-ref>ConnectionStatus</tp:member-ref>.
+ The account manager is expected to set this by observing signals
+ from the Connection.
+
+ <tp:rationale>
+ If you weren't watching the Connection at the time it failed,
+ you can't tell why - unless the AM can tell you. This is part
+ of GetCurrentStatus in NMC 4.x.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="ConnectionError" tp:name-for-bindings="Connection_Error"
+ access="read" type="s" tp:type="DBus_Error_Name">
+ <tp:added version="0.19.7"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If the last connection to this account failed with an error,
+ the D-Bus error name of that error; otherwise, the empty string.
+ The account manager is expected to set this by observing the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+ >Connection.ConnectionError</tp:dbus-ref> and
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+ >Connection.StatusChanged</tp:dbus-ref>
+ signals.</p>
+
+ <p>If ConnectionError is received before the connection disconnects,
+ its first argument should be used to set this property;
+ otherwise, the Reason argument of StatusChanged should be converted
+ to a suitable D-Bus error name.</p>
+
+ <p>Whenever the Connection connects successfully, this property should
+ be reset to the empty string.</p>
+
+ <tp:rationale>
+ <p>This combines the state-recoverability of
+ <tp:member-ref>ConnectionStatusReason</tp:member-ref> with the
+ extensibility of Connection.ConnectionError.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="ConnectionErrorDetails"
+ tp:name-for-bindings="Connection_Error_Details"
+ access="read" type="a{sv}" tp:type="String_Variant_Map">
+ <tp:added version="0.19.7"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If the last connection to this account failed with an error,
+ a mapping representing any additional information about the last
+ disconnection; otherwise, the empty map. The keys and values are
+ the same as for the second argument of
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+ >Connection.ConnectionError</tp:dbus-ref>.</p>
+
+ <p>Whenever the Connection connects successfully, this property should
+ be reset to the empty map.</p>
+
+ <tp:rationale>
+ <p>This combines the state-recoverability of
+ <tp:member-ref>ConnectionStatusReason</tp:member-ref> with the
+ extensibility of Connection.ConnectionError.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="CurrentPresence" type="(uss)" access="read"
+ tp:type="Simple_Presence" tp:name-for-bindings="Current_Presence">
+ <tp:docstring>
+ The actual presence. If the connection is not online, the
+ <tp:type>Connection_Presence_Type</tp:type> SHOULD be
+ Connection_Presence_Type_Offline.
+ If the connection is online but does not support the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence</tp:dbus-ref>
+ interface, the type SHOULD be Connection_Presence_Type_Unset.
+ The account manager is expected to set this by observing signals
+ from the Connection.
+
+ <tp:rationale>
+ This corresponds to GetPresenceActual in NMC 4.x.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="RequestedPresence" type="(uss)" access="readwrite"
+ tp:type="Simple_Presence" tp:name-for-bindings="Requested_Presence">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The requested presence for this account. When this is changed, the
+ account manager should attempt to manipulate the connection manager to
+ make <tp:member-ref>CurrentPresence</tp:member-ref> match
+ <tp:member-ref>RequestedPresence</tp:member-ref> as closely as
+ possible. It should not be saved to any sort of persistent
+ storage.</p>
+
+ <p>When the account manager automatically connects an account,
+ it must signal this by setting the RequestedPresence to the same
+ thing as the <tp:member-ref>AutomaticPresence</tp:member-ref>.</p>
+
+ <tp:rationale>
+ This corresponds to e.g. GetPresence and GetPresenceMessage
+ in NMC 4.x.
+ </tp:rationale>
+
+ <p>The <tp:type>Connection_Presence_Type</tp:type> in this property
+ MUST NOT be Unset, Unknown or Error.</p>
+
+ <tp:rationale>
+ <p>Requesting those presence types doesn't make sense.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="ChangingPresence" tp:name-for-bindings="Changing_Presence"
+ type="b" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If true, a change to the presence of this account is
+ in progress.</p>
+
+ <p>Whenever <tp:member-ref>RequestedPresence</tp:member-ref> is set on
+ an account that could go online, or whenever an account with a
+ non-offline <tp:member-ref>RequestedPresence</tp:member-ref> becomes
+ able to go online (for instance because
+ <tp:member-ref>Enabled</tp:member-ref> or
+ <tp:member-ref>Valid</tp:member-ref> changes to True),
+ ChangingPresence MUST change to True, and the two property changes MUST
+ be emitted in the same
+ <tp:member-ref>AccountPropertyChanged</tp:member-ref> signal, before the
+ Set method returns.</p>
+
+ <p>When the account manager succeeds or fails in changing the presence,
+ or the connection disconnects due to an error, ChangingPresence MUST
+ change to False as part of the same
+ <tp:member-ref>AccountPropertyChanged</tp:member-ref> signal.</p>
+
+ <tp:rationale>
+ <p>This allows UIs to indicate that a presence change is in progress
+ or has finished, even if the change was initiated by a different
+ UI.</p>
+
+ <p>For instance, Maemo 5 and Empathy indicate a presence change by
+ having the presence indicator alternate between the
+ <tp:member-ref>RequestedPresence</tp:member-ref>
+ and the <tp:member-ref>CurrentPresence</tp:member-ref>; they should
+ start blinking when ChangingPresence becomes true, and stop when it
+ becomes false.</p>
+ </tp:rationale>
+
+ </tp:docstring>
+ </property>
+
+ <method name="Reconnect" tp:name-for-bindings="Reconnect">
+ <tp:added version="0.17.24"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Re-connect this account. If the account is currently disconnected
+ and the requested presence is offline, or if the account
+ is not <tp:member-ref>Enabled</tp:member-ref> or not
+ <tp:member-ref>Valid</tp:member-ref>, this does nothing.</p>
+
+ <p>If the account is disconnected and the requested presence is not
+ offline, this forces an attempt to connect with the requested
+ presence immediately.</p>
+
+ <p>If the account is connecting or connected, this is equivalent to
+ remembering the current value of
+ <tp:member-ref>RequestedPresence</tp:member-ref>, setting its value
+ to (OFFLINE, "offline", ""), waiting for the change to take effect,
+ then setting its value to the value that was previously
+ remembered.</p>
+
+ <tp:rationale>
+ <p>Clients desiring "instant apply" semantics for CM parameters MAY
+ call this method to achieve that.</p>
+ </tp:rationale>
+
+ <p>In particular, if the account's
+ <tp:member-ref>Connection</tp:member-ref> is in the Connecting
+ state, calling this method causes the attempt to connect to be
+ aborted and re-tried.</p>
+
+ <tp:rationale>
+ <p>This is necessary to ensure that the new parameters are
+ picked up.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </method>
+
+ <property name="NormalizedName" type="s" access="read"
+ tp:name-for-bindings="Normalized_Name">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The normalized user ID of the local user on this account (i.e. the
+ string returned when the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>
+ method is called on the
+ result of <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection">GetSelfHandle</tp:dbus-ref>
+ for an active connection).</p>
+
+ <p>It is unspecified whether this user ID is globally unique.</p>
+
+ <tp:rationale>
+ <p>As currently implemented, IRC user IDs are only unique within
+ the same IRCnet. On some saner protocols, the user ID includes a
+ DNS name which provides global uniqueness.</p>
+ </tp:rationale>
+
+ <p>If this value is not known yet (which will always be the case for
+ accounts that have never been online), it will be an empty
+ string.</p>
+
+ <p>It is possible that this value will change if the connection
+ manager's normalization algorithm changes, although this SHOULD
+ be avoided.</p>
+
+ <tp:rationale>
+ <p>It's not always completely clear what normalization algorithm
+ should be used; for instance, in Gabble, we currently use JIDs,
+ but it would also have been reasonable to use xmpp URIs.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="HasBeenOnline" tp:name-for-bindings="Has_Been_Online"
+ type="b" access="read">
+ <tp:docstring>
+ If true, this account has successfully been put online at some point
+ in the past.
+
+ <tp:rationale>
+ UIs could apply a policy that the 'account' parameter can only be
+ edited in accounts that have never been online, or that
+ ConnectAutomatically cannot be set on such accounts. The account
+ manager should not enforce such policies, but it can expose enough
+ information to UIs that the UI can decide what to do.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Account_Interface_Addressing.xml b/spec/Account_Interface_Addressing.xml
new file mode 100644
index 0000000..4b2846b
--- /dev/null
+++ b/spec/Account_Interface_Addressing.xml
@@ -0,0 +1,76 @@
+<?xml version="1.0" ?>
+<node name="/Account_Interface_Addressing" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2010 Collabora Ltd</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.</p>
+
+<p>This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+Lesser General Public License for more details.</p>
+
+<p>You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
+ </tp:license>
+ <interface name="org.freedesktop.Telepathy.Account.Interface.Addressing">
+ <tp:requires interface="org.freedesktop.Telepathy.Account"/>
+ <tp:added version="0.21.5">(as stable API)</tp:added>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Some accounts can be used for multiple protocols; for instance, SIP
+ and Skype accounts can often be used to contact the PSTN, MSN and
+ Yahoo accounts can contact each other, and XMPP accounts can
+ potentially contact many protocols via a transport.</p>
+ <p>However, if the user does not intend to make use of this functionality,
+ user interfaces can improve clarity by not displaying it: for instance,
+ if a user prefers to call phone numbers via a particular SIP account,
+ when an address book displays a contact with a phone number, it is
+ desirable to display a "call with SIP" button for that account, but
+ avoid displaying similar buttons for any other configured SIP or
+ Skype accounts.</p>
+ <p>The purpose of this interface is to allow this "for use with" information
+ to be recorded and retrieved.</p>
+ </tp:docstring>
+
+ <property name="URISchemes" type="as" access="read"
+ tp:name-for-bindings="URI_Schemes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A list of fields indicating the type of URI addressing scheme
+ the the account should be used for (eg 'tel') indicating the
+ account is intended for use by applications offering a telephony
+ UI, or 'sip' or 'xmpp' for those protocols</p>
+ <p>Note that these fields signify intent, not ability: It is
+ entirely possible that an account which can be used for a
+ given URI scheme is not wanted for it by the user, and
+ therefore not flagged as such in this field.</p>
+ </tp:docstring>
+ </property>
+
+ <method name="SetURISchemeAssociation"
+ tp:name-for-bindings="Set_URI_Scheme_Association">
+ <tp:docstring>
+ <p>Associate (or disassociate) an account with a particular
+ URI addressing scheme, (such as 'tel' for telephony)</p>
+ </tp:docstring>
+
+ <arg name="URI_Scheme" direction="in" type="s">
+ <tp:docstring>
+ <p>URI scheme to associate/disassociate the account with/from</p>
+ </tp:docstring>
+ </arg>
+
+ <arg name="Association" direction="in" type="b">
+ <tp:docstring>
+ <p>True to associate this account with a given addressing scheme</p>
+ <p>False if the account should not be associated with said scheme</p>
+ </tp:docstring>
+ </arg>
+
+ </method>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Account_Interface_Avatar.xml b/spec/Account_Interface_Avatar.xml
new file mode 100644
index 0000000..6c85b8e
--- /dev/null
+++ b/spec/Account_Interface_Avatar.xml
@@ -0,0 +1,76 @@
+<?xml version="1.0" ?>
+<node name="/Account_Interface_Avatar"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+<p>This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.</p>
+
+<p>This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+Lesser General Public License for more details.</p>
+
+<p>You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+</p>
+ </tp:license>
+ <interface name="org.freedesktop.Telepathy.Account.Interface.Avatar">
+ <tp:requires interface="org.freedesktop.Telepathy.Account"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This interface extends the core Account interface to provide a
+ user-settable avatar image.</p>
+
+ <tp:rationale>
+ <p>The avatar could have been a property on the core Account interface,
+ but was moved to a separate interface because it is likely to be
+ large. This means that clients can safely use GetAll to get
+ properties on the core Account interface without flooding the
+ session bus with large images.</p>
+ </tp:rationale>
+
+ </tp:docstring>
+ <tp:added version="0.17.6"/>
+
+ <tp:struct name="Avatar">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A struct containing avatar data marked with its MIME type.</p>
+ </tp:docstring>
+ <tp:member type="ay" name="Avatar_Data"/>
+ <tp:member type="s" name="MIME_Type"/>
+ </tp:struct>
+
+ <property name="Avatar" tp:name-for-bindings="Avatar"
+ type="(ays)" tp:type="Avatar" access="readwrite">
+ <tp:docstring>
+ The avatar to set on this account for display to other contacts,
+ represented as a structure containing the bytes of the avatar,
+ and the MIME type as a string; may be set to an empty byte-array and
+ an empty string to indicate no avatar. When the account becomes
+ connected, the account manager SHOULD set this avatar using SetAvatar
+ if appropriate.
+
+ <tp:rationale>
+ This corresponds to NMC 4.x mc_account_get_avatar.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <signal name="AvatarChanged" tp:name-for-bindings="Avatar_Changed">
+ <tp:docstring>
+ Emitted when the Avatar property changes.
+
+ <tp:rationale>The avatar itself is deliberately not included in this
+ signal, to reduce bus traffic in the (likely common) case where no
+ running application cares about the user's own avatar.</tp:rationale>
+ </tp:docstring>
+ </signal>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Account_Interface_Storage.xml b/spec/Account_Interface_Storage.xml
new file mode 100644
index 0000000..4e3ba5d
--- /dev/null
+++ b/spec/Account_Interface_Storage.xml
@@ -0,0 +1,169 @@
+<?xml version="1.0" ?>
+<node name="/Account_Interface_Storage"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright (C) 2010 Collabora Ltd.</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+<p>This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.</p>
+
+<p>This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+Lesser General Public License for more details.</p>
+
+<p>You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+</p>
+ </tp:license>
+ <interface name="org.freedesktop.Telepathy.Account.Interface.Storage">
+ <tp:requires interface="org.freedesktop.Telepathy.Account"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>
+ This interface extends the core Account interface to specify details
+ regarding the storage of this account.
+ </p>
+
+ <tp:rationale>
+ <p>
+ Single-sign-on systems do not generally have directly user-editable
+ properties for Accounts, and require the user to visit a specific UI
+ to alter their account properties. User interfaces should know not to
+ expose these account properties as user-editable, and instead
+ redirect the user to the appropriate interface.
+ </p>
+ </tp:rationale>
+
+ </tp:docstring>
+ <tp:added version="0.19.8"/>
+
+ <property name="StorageProvider" tp:name-for-bindings="Storage_Provider"
+ type="s" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>
+ The name of the account storage implementation, which SHOULD start
+ with a reversed domain name in the same way as D-Bus interface names.
+ When this is the empty string the account is internally stored.
+ </p>
+ <p>
+ This property cannot change once an Account has been created.
+ </p>
+ </tp:docstring>
+ </property>
+
+ <property name="StorageIdentifier"
+ tp:name-for-bindings="Storage_Identifier" type="v" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>
+ Unique identification of the account within the storage backend.
+ The contents of the variant are defined by the
+ <tp:member-ref>StorageProvider</tp:member-ref>.
+ </p>
+ <p>
+ This property cannot change once an Account has been created.
+ </p>
+ <tp:rationale>
+ <p>
+ Different storage systems will have their own way of uniquely
+ identifying an account, typically an integer or a string.
+ Given that all users of this property should have direct knowledge
+ of the backend they should know what types to expect and how to
+ handle it.
+ </p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="StorageSpecificInformation"
+ tp:name-for-bindings="Storage_Specific_Information" type="a{sv}"
+ access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>
+ Map containing information specific to the storage backend. The keys
+ and the types of their values are defined by the
+ <tp:member-ref>StorageProvider</tp:member-ref>, and are not
+ interpreted by the AccountManager implementation.
+ </p>
+ <p>
+ As the values in this map may change at any time (due to an external
+ application manipulating the storage provider directly), this
+ property should not be cached; it should instead be retrieved each
+ time it is needed.
+ </p>
+
+ <tp:rationale>
+ <p>
+ This can be used to provide additional hints to user interfaces
+ aware of a specific storage provider, without requiring those user
+ interfaces to use the
+ <tp:member-ref>StorageIdentifier</tp:member-ref> to query the
+ storage provider directly.
+ </p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="StorageRestrictions"
+ tp:name-for-bindings="Storage_Restrictions" type="u"
+ tp:type="Storage_Restriction_Flags"
+ access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>
+ Bitfield which defines what restrictions this Storage method has.
+ </p>
+ <p>
+ This property cannot change once an Account has been created.
+ </p>
+ </tp:docstring>
+ </property>
+
+ <tp:flags name="Storage_Restriction_Flags"
+ value-prefix="Storage_Restriction_Flag" type="u">
+ <tp:docstring>
+ Flags indicating restrictions imposed on an Account by its storage
+ method.
+ </tp:docstring>
+
+ <tp:flag suffix="Cannot_Set_Parameters" value="1">
+ <tp:docstring>
+ The account's <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account"
+ >Parameters</tp:dbus-ref> property can't be changed by calling
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Account"
+ >UpdateParameters</tp:dbus-ref>.
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="Cannot_Set_Enabled" value="2">
+ <tp:docstring>
+ The account can't be enabled/disabled by setting the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account"
+ >Enabled</tp:dbus-ref> property.
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="Cannot_Set_Presence" value="4">
+ <tp:docstring>
+ The account's presence can't be changed by setting the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account"
+ >RequestedPresence</tp:dbus-ref> and <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account"
+ >AutomaticPresence</tp:dbus-ref> properties.
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="Cannot_Set_Service" value="8">
+ <tp:docstring>
+ The account's <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">Service</tp:dbus-ref>
+ property cannot be changed.
+ </tp:docstring>
+ </tp:flag>
+ </tp:flags>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Account_Manager.xml b/spec/Account_Manager.xml
new file mode 100644
index 0000000..cd82e7f
--- /dev/null
+++ b/spec/Account_Manager.xml
@@ -0,0 +1,296 @@
+<?xml version="1.0" ?>
+<node name="/Account_Manager"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+<p>This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.</p>
+
+<p>This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+Lesser General Public License for more details.</p>
+
+<p>You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+</p>
+ </tp:license>
+ <interface name="org.freedesktop.Telepathy.AccountManager">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The account manager is a central service used to store account
+ details.</p>
+
+ <p>The current account manager is defined to be the process that owns
+ the well-known bus name org.freedesktop.Telepathy.AccountManager on
+ the session bus. This process must export an
+ /org/freedesktop/Telepathy/AccountManager object with the
+ AccountManager interface.</p>
+
+ <p>Until a mechanism exists for making a reasonable automatic choice
+ of AccountManager implementation, implementations SHOULD NOT
+ register as an activatable service for the AccountManager's
+ well-known bus name. Instead, it is RECOMMENDED that some component
+ of the user's session will select and activate a particular
+ implementation, and that other Telepathy-enabled programs can
+ detect whether Telepathy is in use by checking whether the
+ AccountManager's well-known name is in use at runtime.</p>
+ </tp:docstring>
+ <tp:added version="0.17.2"/>
+
+ <!-- Missing functionality compared with NMC 4.x:
+ * look up accounts by conditions (can be done client-side, less
+ efficiently, so not a blocker)
+ * global presence/... changes (can be done client-side, less efficiently -
+ we should add this)
+ * count used channels (what's this for?)
+ * get "average" status (not well-defined, UIs can do this)
+ * request channels (out of scope: Channel Dispatcher will do this)
+ * register filters (completely out of scope: Channel Dispatcher again)
+ -->
+
+ <property name="Interfaces" tp:name-for-bindings="Interfaces"
+ type="as" tp:type="DBus_Interface[]" access="read">
+ <tp:docstring>
+ A list of the interfaces provided by the account manager object.
+ </tp:docstring>
+ </property>
+
+ <property name="ValidAccounts" type="ao" access="read"
+ tp:name-for-bindings="Valid_Accounts">
+ <tp:docstring>
+ A list of the valid (complete, usable) <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>s. Change
+ notification is via
+ <tp:member-ref>AccountValidityChanged</tp:member-ref>.
+
+ <tp:rationale>
+ This split between valid and invalid accounts makes it easy to
+ ignore the invalid ones. The only things that should be manipulating
+ invalid accounts are account-editing UIs, which might be able to
+ rescue them.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="InvalidAccounts" type="ao" access="read"
+ tp:name-for-bindings="Invalid_Accounts">
+ <tp:docstring>
+ A list of incomplete or otherwise unusable <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>s. Change
+ notification is via
+ <tp:member-ref>AccountValidityChanged</tp:member-ref>.
+ </tp:docstring>
+ </property>
+
+ <signal name="AccountRemoved" tp:name-for-bindings="Account_Removed">
+ <tp:docstring>
+ The given account has been removed.
+
+ <tp:rationale>
+ This is effectively change notification for the valid and invalid
+ accounts lists. On emission of this signal, the Account indicated
+ will no longer be present in either of the lists.
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg name="Account" type="o">
+ <tp:docstring>
+ An Account, which must not be used any more.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <signal name="AccountValidityChanged"
+ tp:name-for-bindings="Account_Validity_Changed">
+ <tp:docstring>
+ The validity of the given account has changed. New accounts are
+ also indicated by this signal, as an account validity change
+ (usually to True) on an account that did not previously exist.
+
+ <tp:rationale>
+ This is effectively change notification for the valid and invalid
+ accounts lists.
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg name="Account" type="o">
+ <tp:docstring>
+ An <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Valid" type="b">
+ <tp:docstring>
+ True if the account is now valid.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <property name="SupportedAccountProperties"
+ tp:name-for-bindings="Supported_Account_Properties"
+ type="as" tp:type="DBus_Qualified_Member[]" access="read">
+ <tp:added version="0.17.24"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A list of the fully qualified names of properties that can be set
+ via the Properties argument to
+ <tp:member-ref>CreateAccount</tp:member-ref> when an account is
+ created.</p>
+
+ <tp:rationale>
+ <p>Examples of good properties to support here include
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">Icon</tp:dbus-ref>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">Enabled</tp:dbus-ref>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">Nickname</tp:dbus-ref>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">AutomaticPresence</tp:dbus-ref>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">ConnectAutomatically</tp:dbus-ref>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">RequestedPresence</tp:dbus-ref>
+ and
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account.Interface.Avatar">Avatar</tp:dbus-ref>.
+ </p>
+
+ <p>Examples of properties that would make no sense here include
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">Valid</tp:dbus-ref>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">Connection</tp:dbus-ref>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">ConnectionStatus</tp:dbus-ref>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">ConnectionStatusReason</tp:dbus-ref>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">CurrentPresence</tp:dbus-ref>
+ and
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">NormalizedName</tp:dbus-ref>.
+ </p>
+ </tp:rationale>
+
+ <p>This property MUST NOT include include the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">DisplayName</tp:dbus-ref>
+ and <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">Parameters</tp:dbus-ref>
+ properties, which are set using separate arguments.</p>
+
+ <p>This property MAY include the names of properties that, after
+ account creation, will be read-only: this indicates that the property
+ can be set at account creation but not changed later.</p>
+
+ <tp:rationale>
+ <p>For example, an account manager might support migration tools that
+ use this to preserve the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">HasBeenOnline</tp:dbus-ref>
+ property, even though that property is usually read-only.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <method name="CreateAccount" tp:name-for-bindings="Create_Account">
+ <tp:docstring>
+ Request the creation of a new <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>. The
+ account manager SHOULD NOT allow invalid accounts to be created.
+ </tp:docstring>
+ <tp:changed version="0.17.24">added the Properties argument</tp:changed>
+
+ <arg name="Connection_Manager" direction="in" type="s"
+ tp:type="Connection_Manager_Name">
+ <tp:docstring>
+ The name of the connection manager, e.g. "salut".
+ </tp:docstring>
+ </arg>
+
+ <arg name="Protocol" direction="in" type="s"
+ tp:type="Protocol">
+ <tp:docstring>The protocol, e.g. "local-xmpp".</tp:docstring>
+ </arg>
+
+ <arg name="Display_Name" direction="in" type="s">
+ <tp:docstring>The initial value of the new account's <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">DisplayName</tp:dbus-ref>
+ property. The account manager SHOULD modify this to make it unique if
+ an Account already exists with the same display name, for instance by
+ appending a number or the 'account' parameter. Account manager
+ implementations SHOULD accept an empty string, but account editing
+ user interfaces should avoid passing an empty string for this
+ parameter.
+
+ <tp:rationale>
+ <p>The account creation UI may ask the user for a name for the new
+ account. If the author of the UI chooses not to do this, the
+ account creation UI is better able to suggest a default display
+ name because it has protocol-specific knowledge which the account
+ manager does not.</p>
+
+ <p>The account manager always knows the complete list of accounts so
+ it can easily tell whether it should append something to the
+ display name to avoid presenting two identically-named accounts to
+ the user.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </arg>
+
+ <arg name="Parameters" direction="in" type="a{sv}">
+ <tp:docstring>Initial parameter values, as would be passed to
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.ConnectionManager">RequestConnection</tp:dbus-ref>.</tp:docstring>
+ </arg>
+
+ <arg name="Properties" direction="in" type="a{sv}"
+ tp:type="Qualified_Property_Value_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The values of any other properties to be set immediately on the
+ new Account.</p>
+
+ <p>Only the properties mentioned in
+ <tp:member-ref>SupportedAccountProperties</tp:member-ref> are
+ acceptable here. In particular, the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">DisplayName</tp:dbus-ref>
+ and <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Account">Parameters</tp:dbus-ref>
+ properties are never allowed here, since they are set using the other
+ arguments to this method.</p>
+
+ <p>Account manager implementations SHOULD support creating accounts
+ with an empty value for this argument.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg name="Account" direction="out" type="o">
+ <tp:docstring>The new <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>.</tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The Connection_Manager is not installed or does not
+ implement the given Protocol, or one of the properties in the
+ Properties argument is unsupported.</p>
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The Parameters provided omit a required parameter
+ or provide unsupported parameter, or the type of one
+ of the Parameters or Properties is inappropriate.</p>
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
+
diff --git a/spec/Authentication_TLS_Certificate.xml b/spec/Authentication_TLS_Certificate.xml
new file mode 100644
index 0000000..db1d76f
--- /dev/null
+++ b/spec/Authentication_TLS_Certificate.xml
@@ -0,0 +1,305 @@
+<?xml version="1.0" ?>
+<node name="/Authentication_TLS_Certificate" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2010 Collabora Limited</tp:copyright>
+ <tp:license>
+ This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.
+
+This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ </tp:license>
+
+ <interface name="org.freedesktop.Telepathy.Authentication.TLSCertificate">
+ <tp:added version="0.19.13">(as stable API)</tp:added>
+
+ <tp:docstring>
+ This object represents a TLS certificate.
+ </tp:docstring>
+
+ <tp:simple-type name="Certificate_Data" array-name="Certificate_Data_List"
+ type="ay">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The raw data contained in a TLS certificate.</p>
+
+ <p>For X.509 certificates (<tp:member-ref>CertificateType</tp:member-ref>
+ = "x509"), this MUST be in DER format, as defined by the
+ <a href="http://www.itu.int/ITU-T/studygroups/com17/languages/X.690-0207.pdf">X.690</a>
+ ITU standard.</p>
+
+ <p>For PGP certificates (<tp:member-ref>CertificateType</tp:member-ref>
+ = "pgp"), this MUST be a binary OpenPGP key as defined by section 11.1
+ of <a href="http://www.rfc-editor.org/rfc/4880.txt">RFC 4880</a>.</p>
+ </tp:docstring>
+ </tp:simple-type>
+
+ <tp:struct name="TLS_Certificate_Rejection" array-name="TLS_Certificate_Rejection_List">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Struct representing one reason why a TLS certificate was rejected.</p>
+ <p>Since there can be multiple things wrong with a TLS certificate,
+ arrays of this type are used to represent lists of reasons for
+ rejection. In that case, the most important reason SHOULD be placed
+ first in the list.</p>
+ </tp:docstring>
+
+ <tp:member name="Reason" type="u"
+ tp:type="TLS_Certificate_Reject_Reason">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The value of the TLS_Certificate_Reject_Reason enumeration for
+ this certificate rejection.
+ <tp:rationale>
+ Clients that do not understand the <code>Error</code> member,
+ which may be implementation-specific, can use this property to
+ classify rejection reasons into common categories.
+ </tp:rationale>
+ </p>
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member name="Error" type="s"
+ tp:type="DBus_Error_Name">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The DBus error name for this certificate rejection.</p>
+ <p>This MAY correspond to the value of the <code>Reason</code> member,
+ or MAY be a more specific D-Bus error name, perhaps implementation-specific.</p>
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member name="Details" type="a{sv}"
+ tp:type="String_Variant_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Additional information about why the certificate was rejected.
+ This MAY also include one or more of the following well-known keys:</p>
+ <p>
+ <dl>
+ <dt>user-requested (b)</dt>
+ <dd>True if the error was due to an user-requested rejection of
+ the certificate; False if there was an unrecoverable error in the
+ verification process.</dd>
+ <dt>expected-hostname (s)</dt>
+ <dd>If the rejection reason is Hostname_Mismatch, the hostname that
+ the server certificate was expected to have.</dd>
+ <dt>certificate-hostname (s)</dt>
+ <dd>If the rejection reason is Hostname_Mismatch, the hostname of
+ the certificate that was presented.
+ <tp:rationale>
+ <p>For instance, if you try to connect to gmail.com but are presented
+ with a TLS certificate issued to evil.example.org, the error details
+ for Hostname_Mismatch MAY include:</p>
+ <pre>
+ {
+ 'expected-hostname': 'gmail.com',
+ 'certificate-hostname': 'evil.example.org',
+ }
+ </pre>
+ </tp:rationale>
+ </dd>
+ <dt>debug-message (s)</dt>
+ <dd>Debugging information on the error, corresponding to the
+ message part of a D-Bus error message, which SHOULD NOT be
+ displayed to users under normal circumstances</dd>
+ </dl>
+ </p>
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <tp:enum type="u" name="TLS_Certificate_State">
+ <tp:docstring>
+ The possible states for a <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Authentication">TLSCertificate</tp:dbus-ref>
+ object.
+ </tp:docstring>
+
+ <tp:enumvalue suffix="Pending" value="0">
+ <tp:docstring>
+ The certificate is currently waiting to be accepted or rejected.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Accepted" value="1">
+ <tp:docstring>
+ The certificate has been verified.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Rejected" value="2">
+ <tp:docstring>
+ The certificate has been rejected.
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <tp:enum type="u" name="TLS_Certificate_Reject_Reason">
+ <tp:docstring>
+ Possible reasons to reject a TLS certificate.
+ </tp:docstring>
+
+ <tp:enumvalue suffix="Unknown" value="0">
+ <tp:docstring>
+ The certificate has been rejected for another reason
+ not listed in this enumeration.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Untrusted" value="1">
+ <tp:docstring>
+ The certificate is not trusted.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Expired" value="2">
+ <tp:docstring>
+ The certificate is expired.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Not_Activated" value="3">
+ <tp:docstring>
+ The certificate is not active yet.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Fingerprint_Mismatch" value="4">
+ <tp:docstring>
+ The certificate provided does not have the expected
+ fingerprint.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Hostname_Mismatch" value="5">
+ <tp:docstring>
+ The hostname certified does not match the provided one.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Self_Signed" value="6">
+ <tp:docstring>
+ The certificate is self-signed.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Revoked" value="7">
+ <tp:docstring>
+ The certificate has been revoked.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Insecure" value="8">
+ <tp:docstring>
+ The certificate uses an insecure cipher algorithm, or is
+ cryptographically weak.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Limit_Exceeded" value="9">
+ <tp:docstring>
+ The length in bytes of the certificate, or the depth of the
+ certificate chain exceed the limits imposed by the crypto
+ library.
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <property name="State" type="u" access="read"
+ tp:type="TLS_Certificate_State"
+ tp:name-for-bindings="State">
+ <tp:docstring>
+ The current state of this certificate.
+ State change notifications happen by means of the
+ <tp:member-ref>Accepted</tp:member-ref> and
+ <tp:member-ref>Rejected</tp:member-ref> signals.
+ </tp:docstring>
+ </property>
+
+ <property name="Rejections" type="a(usa{sv})" access="read"
+ tp:type="TLS_Certificate_Rejection[]" tp:name-for-bindings="Rejections">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If the <tp:member-ref>State</tp:member-ref> is Rejected,
+ an array of <tp:type>TLS_Certificate_Rejection</tp:type>
+ structures containing the reason why the certificate is rejected.</p>
+ <p>If the <tp:member-ref>State</tp:member-ref> is not Rejected,
+ this property is not meaningful, and SHOULD be set to an empty
+ array.</p>
+ <p>The first rejection in the list MAY be assumed to be
+ the most important; if the array contains more than one
+ element, the CM MAY either use the values after the first,
+ or ignore them.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="CertificateType" type="s" access="read"
+ tp:name-for-bindings="Certificate_Type">
+ <tp:docstring>
+ The type of this TLS certificate (e.g. 'x509' or 'pgp').
+ <p>This property is immutable</p>
+ </tp:docstring>
+ </property>
+
+ <property name="CertificateChainData" type="aay" access="read"
+ tp:type="Certificate_Data[]" tp:name-for-bindings="Certificate_Chain_Data">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>One or more TLS certificates forming a trust chain, each encoded as
+ specified by <tp:type>Certificate_Data</tp:type>.</p>
+ <p>The first certificate in the chain MUST be the server certificate,
+ followed by the issuer's certificate, followed by the issuer's issuer
+ and so on.</p>
+ </tp:docstring>
+ </property>
+
+ <signal name="Accepted"
+ tp:name-for-bindings="Accepted">
+ <tp:docstring>
+ The <tp:member-ref>State</tp:member-ref> of this certificate has changed to Accepted.
+ </tp:docstring>
+ </signal>
+
+ <signal name="Rejected"
+ tp:name-for-bindings="Rejected">
+ <tp:docstring>
+ The <tp:member-ref>State</tp:member-ref> of this certificate has changed to Rejected.
+ </tp:docstring>
+ <arg name="Rejections" type="a(usa{sv})" tp:type="TLS_Certificate_Rejection[]">
+ <tp:docstring>
+ The new value of the <tp:member-ref>Rejections</tp:member-ref> property.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <method name="Accept" tp:name-for-bindings="Accept">
+ <tp:docstring>
+ Accepts this certificate, i.e. marks it as verified.
+ </tp:docstring>
+ </method>
+
+ <method name="Reject" tp:name-for-bindings="Reject">
+ <tp:docstring>
+ Rejects this certificate.
+ </tp:docstring>
+ <arg direction="in" type="a(usa{sv})" name="Rejections"
+ tp:type="TLS_Certificate_Rejection[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The new value of the <tp:member-ref>Rejections</tp:member-ref> property.</p>
+ <p>This MUST NOT be an empty array.</p>
+ </tp:docstring>
+ </arg>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ Raised when the method is called on an object whose <tp:member-ref>State</tp:member-ref>
+ is not <code>Pending</code>, or when the provided rejection list is empty.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Call_Content.xml b/spec/Call_Content.xml
new file mode 100644
index 0000000..17ed710
--- /dev/null
+++ b/spec/Call_Content.xml
@@ -0,0 +1,291 @@
+<?xml version="1.0" ?>
+<node name="/Call_Content"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2009-2010 Nokia Corporation</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ License as published by the Free Software Foundation; either
+ version 2.1 of the License, or (at your option) any later version.</p>
+
+ <p>This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.</p>
+
+ <p>You should have received a copy of the GNU Lesser General Public
+ License along with this library; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+ 02110-1301, USA.</p>
+ </tp:license>
+
+ <interface name="org.freedesktop.Telepathy.Call.Content.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.19.0">(draft 1)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ This object represents one Content inside a <tp:dbus-ref
+ namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref>. For
+ example, in an audio/video call there would be one audio content
+ and one video content. Each content has one or more <tp:dbus-ref
+ namespace="ofdT.Call">Stream.DRAFT</tp:dbus-ref> objects which
+ represent the actual transport to one or more remote contacts.
+ </tp:docstring>
+
+ <tp:enum name="Content_Removal_Reason" type="u">
+ <tp:added version="0.21.2"/>
+ <tp:docstring>
+ A representation of the reason for a content to be removed,
+ which may be used by simple clients, or used as a fallback
+ when the DBus_Reason is not understood. This enum will be
+ extended with future reasons as and when appropriate, so
+ clients SHOULD keep up to date with its values, but also be
+ happy to fallback to the Unknown value when an unknown value
+ is encountered.
+ </tp:docstring>
+
+ <tp:enumvalue suffix="Unknown" value="0">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ We just don't know. Unknown values of this enum SHOULD also be
+ treated like this.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="User_Requested" value="1">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The local user requests that this content is removed
+ from the call.</p>
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Error" value="2">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>There is an error with the content which means that it
+ has to be removed from the call.</p>
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Unsupported" value="3">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Some aspect of the content is unsupported so has to be
+ removed from the call.</p>
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <method name="Remove" tp:name-for-bindings="Remove">
+ <tp:changed version="0.21.2">previously there were no
+ arguments</tp:changed>
+ <tp:docstring>
+ Remove the content from the call.
+ </tp:docstring>
+
+ <arg direction="in" name="Reason" type="u"
+ tp:type="Content_Removal_Reason">
+ <tp:docstring>
+ A generic hangup reason.
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="Detailed_Removal_Reason" type="s"
+ tp:type="DBus_Error_Name">
+ <tp:docstring>
+ A more specific reason for the content removal, if one is
+ available, or an empty string.
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="Message" type="s">
+ <tp:docstring>
+ A human-readable message for the reason of removing the
+ content, such as "Fatal streaming failure" or "no codec
+ intersection". This property can be left empty if no reason
+ is to be given.
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError" />
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ Raised when a Call doesn't support removing contents
+ (e.g. a Google Talk video call).
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <signal name="Removed" tp:name-for-bindings="Removed">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when the content is removed from the call. This
+ is the same as the <tp:dbus-ref
+ namespace="ofdT.Channel.Type">Call.DRAFT.ContentRemoved</tp:dbus-ref>
+ signal.</p>
+ </tp:docstring>
+ </signal>
+
+ <property name="Interfaces" tp:name-for-bindings="Interfaces"
+ type="as" tp:type="DBus_Interface[]" access="read" tp:immutable="yes">
+ <tp:added version="0.19.11"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Extra interfaces provided by this content, such as <tp:dbus-ref
+ namespace="ofdT.Call">Content.Interface.Media.DRAFT</tp:dbus-ref> or
+ <tp:dbus-ref namespace="ofdT.Call">Content.Interface.Mute.DRAFT</tp:dbus-ref>.
+ This SHOULD NOT include the Content interface itself, and cannot
+ change once the content has been created.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="Name" tp:name-for-bindings="Name" type="s" access="read"
+ tp:immutable="yes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The name of the content.</p>
+
+ <tp:rationale>
+ The content name property should be meaningful, so should be
+ given a name which is significant to the user. The name
+ could be the "audio" or "video" string localized, or perhaps
+ include some string identifying the source, such as a webcam
+ identifier.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="Type" tp:name-for-bindings="Type"
+ type="u" tp:type="Media_Stream_Type" access="read" tp:immutable="yes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The media type of this content.</p>
+ </tp:docstring>
+ </property>
+
+ <tp:enum name="Call_Content_Disposition" type="u">
+ <tp:docstring>
+ The disposition of this content, which defines whether to
+ automatically start sending data on the streams when
+ <tp:dbus-ref
+ namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref> is
+ called on the channel.
+ </tp:docstring>
+
+ <tp:enumvalue suffix="None" value="0">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ The content has no specific disposition
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Initial" value="1">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The content was initially part of the call. When
+ <tp:dbus-ref
+ namespace="ofdT.Channel.Type.Call.DRAFT">Accept</tp:dbus-ref>
+ is called on the channel, all streams of this content with
+ <tp:dbus-ref
+ namespace="ofdT.Call.Stream.DRAFT">LocalSendingState</tp:dbus-ref>
+ set to <tp:type>Sending_State</tp:type>_Pending_Send will be
+ moved to <tp:type>Sending_State</tp:type>_Sending as if
+ <tp:dbus-ref
+ namespace="ofdT.Call.Stream.DRAFT">SetSending</tp:dbus-ref>
+ (True) had been called.</p>
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <property name="Disposition" tp:name-for-bindings="Disposition"
+ type="u" tp:type="Call_Content_Disposition" access="read"
+ tp:immutable="yes">
+ <tp:docstring>
+ The disposition of this content.
+ </tp:docstring>
+ </property>
+
+ <signal name="StreamsAdded" tp:name-for-bindings="Streams_Added">
+ <tp:changed version="0.21.2">plural version, renamed from
+ StreamAdded</tp:changed>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when streams are added to a call.</p>
+ </tp:docstring>
+ <arg name="Streams" type="ao">
+ <tp:docstring>
+ The <tp:dbus-ref
+ namespace="ofdT.Call">Stream.DRAFT</tp:dbus-ref>s which were
+ added.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <signal name="StreamsRemoved" tp:name-for-bindings="Streams_Removed">
+ <tp:changed version="0.21.2">plural version, renamed from
+ StreamRemoved</tp:changed>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when streams are removed from a call</p>
+ </tp:docstring>
+ <arg name="Streams" type="ao">
+ <tp:docstring>
+ The <tp:dbus-ref
+ namespace="ofdT.Call">Stream.DRAFT</tp:dbus-ref>s which were
+ removed.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <property name="Streams" tp:name-for-bindings="Streams"
+ type="ao" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The list of <tp:dbus-ref namespace="ofdT.Call"
+ >Stream.DRAFT</tp:dbus-ref> objects that exist in this
+ content.</p>
+
+ <tp:rationale>
+ In a conference call multiple parties can share one media
+ content (say, audio), but the streaming of that media can
+ either be shared or separate. For example, in a multicast
+ conference all contacts would share one stream, while in a
+ Muji conference there would be a stream for each
+ participant.
+ </tp:rationale>
+
+ <p>Change notification is through the
+ <tp:member-ref>StreamsAdded</tp:member-ref> and
+ <tp:member-ref>StreamsRemoved</tp:member-ref> signals.</p>
+ </tp:docstring>
+ </property>
+
+ <tp:enum name="Call_Content_Packetization_Type" type="u">
+ <tp:added version="0.21.2"/>
+ <tp:docstring>
+ A packetization method that can be used for a content.
+ </tp:docstring>
+
+ <tp:enumvalue suffix="RTP" value="0">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ Real-time Transport Protocol, as documented by RFC 3550.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Raw" value="1">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ Raw media.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="MSN_Webcam" value="2">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ MSN webcam. This is the video-only one-way type which was
+ used in earlier versions of WLM. Although no longer used,
+ modern WLM clients still support the MSN webcam protocol.
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <property name="Packetization" tp:name-for-bindings="Packetization"
+ type="u" tp:type="Call_Content_Packetization_Type" access="read"
+ tp:immutable="yes">
+ <tp:added version="0.21.2"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The packetization method in use for this content.</p>
+ </tp:docstring>
+ </property>
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Call_Content_Codec_Offer.xml b/spec/Call_Content_Codec_Offer.xml
new file mode 100644
index 0000000..f88143f
--- /dev/null
+++ b/spec/Call_Content_Codec_Offer.xml
@@ -0,0 +1,87 @@
+<?xml version="1.0" ?>
+<node name="/Call_Content_Codec_Offer"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2009-2010 Nokia Corporation</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ License as published by the Free Software Foundation; either
+ version 2.1 of the License, or (at your option) any later version.</p>
+
+ <p>This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.</p>
+
+ <p>You should have received a copy of the GNU Lesser General Public
+ License along with this library; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+ 02110-1301, USA.</p>
+ </tp:license>
+
+ <interface name="org.freedesktop.Telepathy.Call.Content.CodecOffer.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.19.0">(draft 1)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ This object represents an offer of a Codec payload mapping.
+ </tp:docstring>
+
+ <method name="Accept" tp:name-for-bindings="Accept">
+ <arg name="Codecs" direction="in"
+ type="a(usuua{ss})" tp:type="Codec[]">
+ <tp:docstring>
+ The local codec mapping to send to the remote contacts and
+ to use in the <tp:dbus-ref
+ namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref>.
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Accept the updated Codec mapping and update the local mapping.
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The codecs given as the argument are invalid in some way.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="Reject" tp:name-for-bindings="Reject">
+ <tp:docstring>
+ Reject the proposed update to the codecs
+ FIXME add error codes and strings here
+ </tp:docstring>
+ </method>
+
+ <property name="Interfaces" tp:name-for-bindings="Interfaces"
+ type="as" tp:type="DBus_Interface[]" access="read" tp:immutable="yes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Extra interfaces provided by this codec offer. This SHOULD
+ NOT include the CodecOffer interface itself, and cannot change
+ once the content has been created.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="RemoteContactCodecs"
+ tp:name-for-bindings="Remote_Contact_Codecs"
+ type="a(usuua{ss})" tp:type="Codec[]" access="read"
+ tp:immutable="yes">
+ <tp:docstring>
+ A list of codecs the remote contact supports.
+ </tp:docstring>
+ </property>
+
+ <property name="RemoteContact" tp:name-for-bindings="Remote_Contact"
+ type="u" tp:type="Contact_Handle" access="read" tp:immutable="yes">
+ <tp:docstring>
+ The contact handle that this codec offer applies to.
+ </tp:docstring>
+ </property>
+
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Call_Content_Interface_Media.xml b/spec/Call_Content_Interface_Media.xml
new file mode 100644
index 0000000..274d8b2
--- /dev/null
+++ b/spec/Call_Content_Interface_Media.xml
@@ -0,0 +1,331 @@
+<?xml version="1.0" ?>
+<node name="/Call_Content_Interface_Media"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2009-2010 Nokia Corporation</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ License as published by the Free Software Foundation; either
+ version 2.1 of the License, or (at your option) any later version.</p>
+
+ <p>This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.</p>
+
+ <p>You should have received a copy of the GNU Lesser General Public
+ License along with this library; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+ 02110-1301, USA.</p>
+ </tp:license>
+
+ <interface name="org.freedesktop.Telepathy.Call.Content.Interface.Media.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.19.0">(draft 1)</tp:added>
+ <tp:requires interface="org.freedesktop.Telepathy.Call.Content.DRAFT"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Interface to use by a software implementation of media
+ streaming. The reason behind splitting the members of this
+ interface out from the main <tp:dbus-ref
+ namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref> interface is
+ that the software is not necessarily what controls the
+ media. An example of this is in GSM phones, where the CM just
+ tells the phone to dial a number and it does the audio routing
+ in a device specific hardware way and the CM does not need
+ to concern itself with codecs.</p>
+
+ <h4>Codec negotiation</h4>
+
+ <p>When a new <tp:dbus-ref
+ namespace="ofdT.Channel.Type">Call.DRAFT</tp:dbus-ref> channel
+ appears, whether it was requested or not, a <tp:dbus-ref
+ namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref>
+ will either be waiting in the
+ <tp:member-ref>CodecOffer</tp:member-ref> property, or will
+ appear at some point via the
+ <tp:member-ref>NewCodecOffer</tp:member-ref> signal.</p>
+
+ <p>The <tp:dbus-ref
+ namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref>
+ property on the codec offer lists the codecs which are
+ supported by the remote contact, and so will determine the
+ codecs that should be proposed by the local user's streaming
+ implementation. An empty list means all codecs can be proposed.</p>
+
+ <p>For incoming calls on protocols where codecs are proposed when
+ starting the call (for example, <a
+ href="http://xmpp.org/extensions/xep-0166.html">Jingle</a>),
+ the <tp:dbus-ref
+ namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref>
+ will contain information on the codecs that have already been
+ proposed by the remote contact, otherwise the codec map will
+ be the empty list.</p>
+
+ <p>The streaming implementation should look at the remote codec
+ map and the codecs known by the local user and call
+ <tp:dbus-ref
+ namespace="ofdT.Call.Content">CodecOffer.DRAFT.Accept</tp:dbus-ref>
+ on the intersection of these two codec lists.</p>
+
+ <p>This means that in practice, outgoing calls will have a codec
+ offer pop up with no information in the <tp:dbus-ref
+ namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref>,
+ so the local user will call <tp:dbus-ref
+ namespace="ofdT.Call.Content.CodecOffer.DRAFT">Accept</tp:dbus-ref>
+ with the list of all codecs supported. If this codec offer is
+ accepted, then <tp:member-ref>CodecsChanged</tp:member-ref>
+ will fire with the details of the codecs passed into
+ <tp:dbus-ref
+ namespace="ofdT.Call.Content.CodecOffer.DRAFT">Accept</tp:dbus-ref>. If
+ the call is incoming, then the <tp:dbus-ref
+ namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref>
+ will contain details of the remote contact's codecs and the
+ local user will call <tp:dbus-ref
+ namespace="ofdT.Call.Content.CodecOffer.DRAFT">Accept</tp:dbus-ref>
+ with the codecs that both sides understand. After the codec
+ set is accepted, <tp:member-ref>CodecsChanged</tp:member-ref>
+ will fire to signal this change.</p>
+
+ <h4>Protocols without codec negotiation</h4>
+
+ <p>For protocols where the codecs are not negotiable, instead of
+ popping up the initial content's <tp:dbus-ref
+ namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref>
+ object with an empty <tp:dbus-ref
+ namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref>,
+ the CM should set the supported codec values to known codec
+ values in the said object's codec map.</p>
+
+ <h4>Changing codecs mid-call</h4>
+
+ <p>To update the codec list used mid-call, the
+ <tp:member-ref>UpdateCodecs</tp:member-ref> method should be
+ called with details of the new codec list. If this is
+ accepted, then <tp:member-ref>CodecsChanged</tp:member-ref>
+ will be emitted with the new codec set.</p>
+
+ <p>If the other side decides to update his or her codec list
+ during a call, a new <tp:dbus-ref
+ namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref>
+ object will appear through
+ <tp:member-ref>NewCodecOffer</tp:member-ref> which should be
+ acted on as documented above.</p>
+
+ </tp:docstring>
+
+ <tp:struct name="Codec" array-name="Codec_List">
+ <tp:docstring>
+ A description of a codec.
+ </tp:docstring>
+ <tp:member name="Identifier" type="u">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ Numeric identifier for the codec. This will be used as the PT in the
+ SDP or content description.
+ </tp:docstring>
+ </tp:member>
+ <tp:member name="Name" type="s">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ The name of the codec.
+ </tp:docstring>
+ </tp:member>
+ <tp:member name="Clockrate" type="u">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ The clockrate of the codec.
+ </tp:docstring>
+ </tp:member>
+ <tp:member name="Channels" type="u">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ Number of channels of the codec if applicable, otherwise 0.
+ </tp:docstring>
+ </tp:member>
+ <tp:member name="Parameters" type="a{ss}" tp:type="String_String_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ Extra parameters for this codec.
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <tp:mapping name="Contact_Codec_Map">
+ <tp:docstring>
+ A map from contact to the list of codecs he or she supports.
+ </tp:docstring>
+ <tp:member name="Handle" type="u" tp:type="Contact_Handle">
+ <tp:docstring>
+ A contact handle.
+ </tp:docstring>
+ </tp:member>
+ <tp:member name="Codecs" type="a(usuua{ss})" tp:type="Codec[]">
+ <tp:docstring>
+ The codecs that the contact supports.
+ </tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <tp:struct name="Codec_Offering">
+ <tp:docstring>
+ A codec offer and its corresponding remote contact codec map.
+ </tp:docstring>
+ <tp:member name="Codec_Offer" type="o">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ The object path to the <tp:dbus-ref namespace="ofdT.Call.Content"
+ >CodecOffer.DRAFT</tp:dbus-ref>
+ </tp:docstring>
+ </tp:member>
+ <tp:member name="Remote_Contact" type="u" tp:type="Contact_Handle">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ The contact handle that this codec offer applies to.
+ </tp:docstring>
+ </tp:member>
+ <tp:member name="Remote_Contact_Codecs" type="a(usuua{ss})"
+ tp:type="Codec[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ The <tp:dbus-ref namespace="ofdT.Call.Content"
+ >CodecOffer.DRAFT.RemoteContactCodecs</tp:dbus-ref> property
+ of the codec offer.
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <signal name="CodecsChanged" tp:name-for-bindings="Codecs_Changed">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when the codecs in use change.</p>
+
+ <p>As well as acting as change notification for the
+ <tp:member-ref>ContactCodecMap</tp:member-ref>, emission of this
+ signal implies that the <tp:member-ref>CodecOffer</tp:member-ref>
+ property has changed to <code>('/', {})</code>.</p>
+ </tp:docstring>
+ <arg name="Updated_Codecs" type="a{ua(usuua{ss})}"
+ tp:type="Contact_Codec_Map">
+ <tp:docstring>
+ A map from contact to his or her codecs. Each pair in this
+ map is added to the
+ <tp:member-ref>ContactCodecMap</tp:member-ref> property,
+ replacing any previous pair with that key.
+ </tp:docstring>
+ </arg>
+ <arg name="Removed_Contacts" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ A list of keys which were removed from the
+ <tp:member-ref>ContactCodecMap</tp:member-ref>, probably because
+ those contacts left the call.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <method name="UpdateCodecs" tp:name-for-bindings="Update_Codecs">
+ <tp:docstring>
+ Update the local codec mapping. This method should only be
+ used during an existing call to update the codec mapping.
+ </tp:docstring>
+ <arg name="Codecs" direction="in"
+ type="a(usuua{ss})" tp:type="Codec[]">
+ <tp:docstring>
+ The codecs now supported by the local user.
+ </tp:docstring>
+ </arg>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ Raised when a <tp:dbus-ref
+ namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref>
+ object exists and is referred to in the
+ <tp:member-ref>CodecOffer</tp:member-ref> property which
+ should be used instead of calling this method, or before
+ the content's initial <tp:dbus-ref
+ namespace="ofdT.Call.Content">CodecOffer.DRAFT</tp:dbus-ref>
+ object has appeared.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <property name="ContactCodecMap" tp:name-for-bindings="Contact_Codec_Map"
+ type="a{ua(usuua{ss})}" tp:type="Contact_Codec_Map" access="read">
+ <tp:docstring>
+ <p>A map from contact handles (including the local user's own handle)
+ to the codecs supported by that contact.</p>
+
+ <p>Change notification is via the
+ <tp:member-ref>CodecsChanged</tp:member-ref> signal.</p>
+ </tp:docstring>
+ </property>
+
+ <signal name="NewCodecOffer" tp:name-for-bindings="New_Codec_Offer">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when a new <tp:dbus-ref namespace="ofdT.Call.Content"
+ >CodecOffer.DRAFT</tp:dbus-ref> appears. The streaming
+ implementation MUST respond by calling the <tp:dbus-ref
+ namespace="ofdT.Call.Content.CodecOffer.DRAFT"
+ >Accept</tp:dbus-ref> or <tp:dbus-ref
+ namespace="ofdT.Call.Content.CodecOffer.DRAFT"
+ >Reject</tp:dbus-ref> method on the codec offer object.</p>
+
+ <p>Emission of this signal indicates that the
+ <tp:member-ref>CodecOffer</tp:member-ref> property has changed to
+ <code>(Contact, Offer, Codecs)</code>.</p>
+ </tp:docstring>
+ <arg name="Contact" type="u">
+ <tp:docstring>
+ The contact the codec offer belongs to.
+ </tp:docstring>
+ </arg>
+ <arg name="Offer" type="o">
+ <tp:docstring>
+ The object path of the new codec offer. This replaces any previous
+ codec offer.
+ </tp:docstring>
+ </arg>
+ <arg name="Codecs" type="a(usuua{ss})" tp:type="Codec[]">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The <tp:dbus-ref namespace="ofdT.Call.Content"
+ >CodecOffer.DRAFT.RemoteContactCodecs</tp:dbus-ref> property
+ of the codec offer.</p>
+
+ <tp:rationale>
+ Having the <tp:dbus-ref
+ namespace="ofdT.Call.Content.CodecOffer.DRAFT">RemoteContactCodecs</tp:dbus-ref>
+ property here saves a D-Bus round-trip - it shouldn't be
+ necessary to get the property from the CodecOffer object, in
+ practice.
+ </tp:rationale>
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <property name="CodecOffer" tp:name-for-bindings="Codec_Offer"
+ type="(oua(usuua{ss}))" tp:type="Codec_Offering" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The object path to the current
+ <tp:dbus-ref namespace="ofdT.Call.Content"
+ >CodecOffer.DRAFT</tp:dbus-ref> object, its
+ <tp:dbus-ref namespace="ofdT.Call.Content"
+ >CodecOffer.DRAFT.RemoteContact</tp:dbus-ref> and
+ <tp:dbus-ref namespace="ofdT.Call.Content"
+ >CodecOffer.DRAFT.RemoteContactCodecs</tp:dbus-ref> properties.
+ If the object path is "/" then there isn't an outstanding
+ codec offer, and the mapping MUST be empty.</p>
+
+ <tp:rationale>
+ Having the <tp:dbus-ref
+ namespace="ofdT.Call.Content.CodecOffer.DRAFT"
+ >RemoteContact</tp:dbus-ref> and
+ <tp:dbus-ref namespace="ofdT.Call.Content.CodecOffer.DRAFT"
+ >RemoteContactCodecs</tp:dbus-ref>
+ properties here saves a D-Bus round-trip - it shouldn't be
+ necessary to get these properties from the CodecOffer object, in
+ practice.
+ </tp:rationale>
+
+ <p>Change notification is via the
+ <tp:member-ref>NewCodecOffer</tp:member-ref> (which replaces the
+ value of this property with a new codec offer), and
+ <tp:member-ref>CodecsChanged</tp:member-ref> (which implies that
+ there is no longer any active codec offer) signals.</p>
+ </tp:docstring>
+ </property>
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Call_Content_Interface_Mute.xml b/spec/Call_Content_Interface_Mute.xml
new file mode 100644
index 0000000..f926e03
--- /dev/null
+++ b/spec/Call_Content_Interface_Mute.xml
@@ -0,0 +1,85 @@
+<?xml version="1.0" ?>
+<node name="/Call_Content_Interface_Mute" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright> Copyright © 2005-2010 Nokia Corporation </tp:copyright>
+ <tp:copyright> Copyright © 2005-2010 Collabora Ltd </tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.
+
+This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ </tp:license>
+
+ <interface name="org.freedesktop.Telepathy.Call.Content.Interface.Mute.DRAFT" tp:causes-havoc="experimental">
+ <tp:added version="0.19.6">(draft version, not API-stable)</tp:added>
+ <tp:requires interface="org.freedesktop.Telepathy.Call.Content.DRAFT"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Interface for calls which may be muted. This only makes sense
+ for channels where audio or video is streaming between members.</p>
+
+ <p>Muting a call content indicates that the user does not wish to send
+ outgoing audio or video.</p>
+
+ <p>Although it's client's responsibility to actually mute the microphone
+ or turn off the camera, using this interface the client can also
+ inform the CM and other clients of that fact.</p>
+
+ <tp:rationale>
+ For some protocols, the fact that the content is muted needs
+ to be transmitted to the peer; for others, the notification
+ to the peer is only informational (eg. XMPP), and some
+ protocols may have no notion of muting at all.
+ </tp:rationale>
+ </tp:docstring>
+
+ <signal name="MuteStateChanged" tp:name-for-bindings="Mute_State_Changed">
+ <tp:docstring>
+ Emitted to indicate that the mute state has changed for this call content.
+ This may occur as a consequence of the client calling
+ <tp:member-ref>SetMuted</tp:member-ref>, or as an indication that another
+ client has (un)muted the content.
+ </tp:docstring>
+ <arg name="MuteState" type="b">
+ <tp:docstring>
+ True if the content is now muted.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <property name="MuteState" type="b"
+ access="read" tp:name-for-bindings="Mute_State">
+ <tp:docstring>
+ True if the content is muted.
+ </tp:docstring>
+ </property>
+
+ <method name="SetMuted" tp:name-for-bindings="Set_Muted">
+ <tp:changed version="0.21.2">renamed from SetMuted to Mute</tp:changed>
+ <tp:changed version="0.21.3">renamed back from Mute to SetMuted</tp:changed>
+ <arg direction="in" name="Muted" type="b">
+ <tp:docstring>
+ True if the client has muted the content.
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ <p>Inform the CM that the call content has been muted or unmuted by
+ the client.</p>
+
+ <p>It is the client's responsibility to actually mute or unmute the
+ microphone or camera used for the content. However, the client
+ MUST call this whenever it mutes or unmutes the content.</p>
+ </tp:docstring>
+ </method>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Call_Stream.xml b/spec/Call_Stream.xml
new file mode 100644
index 0000000..1d7b281
--- /dev/null
+++ b/spec/Call_Stream.xml
@@ -0,0 +1,261 @@
+<?xml version="1.0" ?>
+<node name="/Call_Stream"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2009-2010 Nokia Corporation</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ License as published by the Free Software Foundation; either
+ version 2.1 of the License, or (at your option) any later version.</p>
+
+ <p>This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.</p>
+
+ <p>You should have received a copy of the GNU Lesser General Public
+ License along with this library; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+ 02110-1301, USA.</p>
+ </tp:license>
+
+ <interface name="org.freedesktop.Telepathy.Call.Stream.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.19.0">(draft 1)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ One stream inside a <tp:dbus-ref
+ namespace="ofdT.Call">Content.DRAFT</tp:dbus-ref>.
+ </tp:docstring>
+
+ <method name="SetSending" tp:name-for-bindings="Set_Sending">
+ <tp:docstring>
+ Set the stream to start or stop sending media from the local
+ user to other contacts.
+ </tp:docstring>
+
+ <arg name="Send" type="b" direction="in">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If True, the
+ <tp:member-ref>LocalSendingState</tp:member-ref> should
+ change to <tp:type>Sending_State</tp:type>_Sending, if it isn't
+ already.</p>
+
+ <p>If False, the
+ <tp:member-ref>LocalSendingState</tp:member-ref> should
+ change to <tp:type>Sending_State</tp:type>_None, if it isn't
+ already.</p>
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented" />
+ </tp:possible-errors>
+ </method>
+
+ <method name="RequestReceiving" tp:name-for-bindings="Request_Receiving">
+ <tp:docstring>
+ <p>Request that a remote contact stops or starts sending on
+ this stream.</p>
+
+ <p>The <tp:member-ref>CanRequestReceiving</tp:member-ref>
+ property defines whether the protocol allows the local user to
+ request the other side start sending on this stream.</p>
+ </tp:docstring>
+
+ <arg name="Contact" type="u" tp:type="Contact_Handle" direction="in">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Contact from which sending is requested</p>
+ </tp:docstring>
+ </arg>
+
+ <arg name="Receive" type="b" direction="in">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If true, request that the given contact starts to send media.
+ If false, request that the given contact stops sending media.</p>
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The request contact is valid but is not involved in this
+ stream.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ The protocol does not allow the local user to request the
+ other side starts sending on this stream.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <signal name="RemoteMembersChanged"
+ tp:name-for-bindings="Remote_Members_Changed">
+ <tp:changed version="0.21.2">renamed from SendersChanged to MembersChanged</tp:changed>
+ <tp:changed version="0.21.3">renamed from MembersChanged to RemoteMembersChanged</tp:changed>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ Emitted when <tp:member-ref>RemoteMembers</tp:member-ref> changes.
+ </tp:docstring>
+
+ <arg name="Updates" type="a{uu}" tp:type="Contact_Sending_State_Map">
+ <tp:docstring>
+ A mapping from channel-specific handles to their updated sending
+ state, whose keys include at least the members who were added,
+ and the members whose states changed.
+ </tp:docstring>
+ </arg>
+ <arg name="Removed" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ The channel-specific handles that were removed from the keys
+ of the <tp:member-ref>RemoteMembers</tp:member-ref>
+ property, as a result of the contact leaving this stream
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <signal name="LocalSendingStateChanged"
+ tp:name-for-bindings="Local_Sending_State_Changed">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ Emitted when <tp:member-ref>LocalSendingState</tp:member-ref> changes.
+ </tp:docstring>
+
+ <arg name="State" type="u" tp:type="Sending_State">
+ <tp:docstring>
+ The new value of
+ <tp:member-ref>LocalSendingState</tp:member-ref>.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <tp:enum name="Sending_State" type="u">
+ <tp:docstring>
+ Enum indicating whether a contact is sending media.
+ </tp:docstring>
+
+ <tp:enumvalue suffix="None" value="0">
+ <tp:docstring>
+ The contact is not sending media and has not been asked to
+ do so.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Pending_Send" value="1">
+ <tp:docstring>
+ The contact has been asked to start sending media.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Sending" value="2">
+ <tp:docstring>
+ The contact is sending media.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue suffix="Pending_Stop_Sending" value="3">
+ <tp:docstring>
+ The contact has been asked to stop sending media.
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <tp:mapping name="Contact_Sending_State_Map">
+ <tp:docstring>
+ A map from a contact to his or her sending state.
+ </tp:docstring>
+ <tp:member name="Contact" type="u" tp:type="Contact_Handle">
+ <tp:docstring>
+ The contact handle.
+ </tp:docstring>
+ </tp:member>
+ <tp:member name="Sending" type="u" tp:type="Sending_State">
+ <tp:docstring>
+ The sending state of the contact.
+ </tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <property name="Interfaces" tp:name-for-bindings="Interfaces"
+ type="as" tp:type="DBus_Interface[]" access="read" tp:immutable="yes">
+ <tp:added version="0.19.11"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Extra interfaces provided by this stream, such as <tp:dbus-ref
+ namespace="ofdT.Call">Stream.Interface.Media.DRAFT</tp:dbus-ref>.
+ This SHOULD NOT include the Stream interface itself, and cannot
+ change once the stream has been created.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="RemoteMembers" tp:name-for-bindings="Remote_Members"
+ type="a{uu}" access="read" tp:type="Contact_Sending_State_Map">
+ <tp:changed version="0.21.2">renamed from Senders</tp:changed>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A map from remote contacts to their sending state. The
+ local user's sending state is shown in
+ <tp:member-ref>LocalSendingState</tp:member-ref>.</p>
+
+ <p><tp:type>Sending_State</tp:type>_Pending_Send indicates
+ that another contact has asked the local user to send
+ media.</p>
+
+ <p>Other contacts' handles in this map indicate whether they are
+ sending media to the contacts in this stream.
+ Sending_State_Pending_Send indicates contacts who are not sending but
+ have been asked to do so.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="LocalSendingState" tp:name-for-bindings="Local_Sending_State"
+ type="u" access="read" tp:type="Sending_State">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The local user's sending state. Media sent on this stream
+ should be assumed to be received, directly or indirectly, by
+ every other contact in the
+ <tp:member-ref>RemoteMembers</tp:member-ref> mapping. Change
+ notification is given via the
+ <tp:member-ref>LocalSendingStateChanged</tp:member-ref>
+ signal.</p>
+
+ <tp:rationale>
+ Implementations of the first Call draft had the self handle
+ in the <tp:member-ref>RemoteMembers</tp:member-ref> (then
+ called Members) map and this showed that it's annoying
+ having to keep track of the self handle so that it can be
+ special-cased.
+ </tp:rationale>
+
+ <p>A value of <tp:type>Sending_State</tp:type>_Pending_Send for
+ this property indicates that the other side requested the
+ local user start sending media, which can be done by calling
+ <tp:member-ref>SetSending</tp:member-ref>. When a call is
+ accepted, all initial contents with streams that have a
+ local sending state of
+ <tp:type>Sending_State</tp:type>_Pending_Send are
+ automatically set to sending. For example, on an incoming
+ call it means you need to <tp:dbus-ref
+ namespace="ofdT.Channel.Type.Call.DRAFT">Accept</tp:dbus-ref>
+ to start the actual call, on an outgoing call it might mean
+ you need to call <tp:dbus-ref
+ namespace="ofdT.Channel.Type.Call.DRAFT">Accept</tp:dbus-ref>
+ before actually starting the call.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="CanRequestReceiving" tp:name-for-bindings="Can_Request_Receiving"
+ type="b" access="read" tp:immutable="yes">
+ <tp:added version="0.21.2"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If true, the user can request that a remote contact starts
+ sending on this stream.</p>
+
+ <tp:rationale>Not all protocols allow the user to ask the
+ other side to start sending media.</tp:rationale>
+ </tp:docstring>
+ </property>
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Call_Stream_Endpoint.xml b/spec/Call_Stream_Endpoint.xml
new file mode 100644
index 0000000..4818168
--- /dev/null
+++ b/spec/Call_Stream_Endpoint.xml
@@ -0,0 +1,182 @@
+<?xml version="1.0" ?>
+<node name="/Call_Stream_Endpoint"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2009-2010 Nokia Corporation</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ License as published by the Free Software Foundation; either
+ version 2.1 of the License, or (at your option) any later version.</p>
+
+ <p>This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.</p>
+
+ <p>You should have received a copy of the GNU Lesser General Public
+ License along with this library; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+ 02110-1301, USA.</p>
+ </tp:license>
+
+ <interface name="org.freedesktop.Telepathy.Call.Stream.Endpoint.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.19.0">(draft 1)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This object represents an endpoint for a stream. In a one-to-one
+ call, there will be one (bidirectional) stream per content and
+ one endpoint per stream (as there is only one remote
+ contact). In a multi-user call there is a stream for each remote
+ contact and each stream has one endpoint as it refers to the one
+ physical machine on the other end of the stream.</p>
+
+ <p>The multiple endpoint use case appears when SIP call forking
+ is used. Unlike jingle call forking (which is just making
+ multiple jingle calls to different resources appear as one
+ call), SIP call forking is actually done at the server so you
+ have one stream to the remote contact and then and endpoint for
+ each SIP client to be called.</p>
+ </tp:docstring>
+
+ <property name="RemoteCredentials"
+ tp:name-for-bindings="Remote_Credentials"
+ type="(ss)" tp:type="Stream_Credentials" access="read">
+ <tp:docstring>
+ The ICE credentials used for all candidates. If each candidate
+ has different credentials, then this property SHOULD be ("",
+ ""). Per-candidate credentials are set in the
+ <tp:type>Candidate</tp:type>'s
+ <tp:type>Candidate_Info</tp:type> a{sv}.
+ </tp:docstring>
+ </property>
+
+ <signal name="RemoteCredentialsSet"
+ tp:name-for-bindings="Remote_Credentials_Set">
+ <arg name="Username" type="s">
+ <tp:docstring>
+ The username set.
+ </tp:docstring>
+ </arg>
+ <arg name="Password" type="s">
+ <tp:docstring>
+ The password set.
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Emitted when the remote ICE credentials for the endpoint are
+ set. If each candidate has different credentials, then this
+ signal will never be fired.
+ </tp:docstring>
+ </signal>
+
+ <property name="RemoteCandidates" tp:name-for-bindings="Remote_Candidates"
+ type="a(usqa{sv})" tp:type="Candidate[]" access="read">
+ <tp:docstring>
+ A list of candidates for this endpoint.
+ </tp:docstring>
+ </property>
+
+ <signal name="RemoteCandidatesAdded"
+ tp:name-for-bindings="Remote_Candidates_Added">
+ <tp:docstring>
+ Emitted when remote candidates are added to the
+ <tp:member-ref>RemoteCandidates</tp:member-ref> property.
+ </tp:docstring>
+ <arg name="Candidates"
+ type="a(usqa{sv})" tp:type="Candidate[]">
+ <tp:docstring>
+ The candidates that were added.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <signal name="CandidateSelected"
+ tp:name-for-bindings="Candidate_Selected">
+ <tp:docstring>
+ Emitted when a candidate is selected for use in the stream.
+ </tp:docstring>
+ <arg name="Candidate"
+ type="(usqa{sv})" tp:type="Candidate">
+ <tp:docstring>
+ The candidate that has been selected.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <property name="SelectedCandidate"
+ tp:name-for-bindings="Selected_Candidate"
+ type="(usqa{sv})" tp:type="Candidate" access="read">
+ <tp:docstring>
+ The candidate that has been selected for use to stream packets
+ to the remote contact. Change notification is given via the
+ the <tp:member-ref>CandidateSelected</tp:member-ref> signal.
+ </tp:docstring>
+ </property>
+
+ <method name="SetSelectedCandidate"
+ tp:name-for-bindings="Set_Selected_Candidate">
+ <tp:docstring>
+ Set the value of
+ <tp:member-ref>CandidateSelected</tp:member-ref>.
+ </tp:docstring>
+ <arg name="Candidate"
+ type="(usqa{sv})" tp:type="Candidate" direction="in">
+ <tp:docstring>
+ The candidate that has been selected.
+ </tp:docstring>
+ </arg>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
+ </tp:possible-errors>
+ </method>
+
+ <property name="StreamState" tp:name-for-bindings="Stream_State"
+ type="u" tp:type="Media_Stream_State"
+ access="read">
+ <tp:docstring>
+ The stream state of the endpoint.
+ </tp:docstring>
+ </property>
+
+ <signal name="StreamStateChanged"
+ tp:name-for-bindings="Stream_State_Changed">
+ <tp:docstring>
+ Emitted when the <tp:member-ref>StreamState</tp:member-ref>
+ property changes.
+ </tp:docstring>
+ <arg name="state" type="u" tp:type="Media_Stream_State">
+ <tp:docstring>
+ The new <tp:member-ref>StreamState</tp:member-ref> value.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <method name="SetStreamState"
+ tp:name-for-bindings="Set_Stream_State">
+ <tp:docstring>
+ Change the <tp:member-ref>StreamState</tp:member-ref> of the
+ endpoint.
+ </tp:docstring>
+ <arg direction="in" name="State" type="u" tp:type="Media_Stream_State">
+ <tp:docstring>
+ The requested stream state.
+ </tp:docstring>
+ </arg>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
+ </tp:possible-errors>
+ </method>
+
+ <property name="Transport" tp:name-for-bindings="Transport"
+ type="u" tp:type="Stream_Transport_Type" access="read">
+ <tp:docstring>
+ The transport type for the stream endpoint.
+ </tp:docstring>
+ </property>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Call_Stream_Interface_Media.xml b/spec/Call_Stream_Interface_Media.xml
new file mode 100644
index 0000000..9e62c87
--- /dev/null
+++ b/spec/Call_Stream_Interface_Media.xml
@@ -0,0 +1,447 @@
+<?xml version="1.0" ?>
+<node name="/Call_Stream_Interface_Media"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2009-2010 Nokia Corporation</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ License as published by the Free Software Foundation; either
+ version 2.1 of the License, or (at your option) any later version.</p>
+
+ <p>This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.</p>
+
+ <p>You should have received a copy of the GNU Lesser General Public
+ License along with this library; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+ 02110-1301, USA.</p>
+ </tp:license>
+
+ <interface name="org.freedesktop.Telepathy.Call.Stream.Interface.Media.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.19.0">(draft 1)</tp:added>
+ <tp:requires interface="org.freedesktop.Telepathy.Call.Stream.DRAFT"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ [FIXME]
+
+ <h4>ICE restarts</h4>
+
+ <p>If the <tp:dbus-ref
+ namespace="ofdT.Call.Stream.Endpoint.DRAFT">RemoteCredentialsSet</tp:dbus-ref>
+ signal is fired during a call once it has been called before
+ whilst setting up the call for initial use, and the
+ credentials have changed, then there has been an ICE
+ restart. In such a case, the CM SHOULD also empty the remote
+ candidate list in the <tp:dbus-ref
+ namespace="ofdT.Call.Stream">Endpoint.DRAFT</tp:dbus-ref>.</p>
+
+ <p>If the CM does an ICE restart, then the
+ <tp:member-ref>PleaseRestartICE</tp:member-ref> signal is
+ emitted and the streaming implementation should then call
+ <tp:member-ref>SetCredentials</tp:member-ref> again.</p>
+
+ <p>For more information on ICE restarts see
+ <a href="http://tools.ietf.org/html/rfc5245#section-9.1.1.1">RFC 5245
+ section 9.1.1.1</a></p>
+ </tp:docstring>
+
+ <method name="SetCredentials" tp:name-for-bindings="Set_Credentials">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Used to set the username fragment and password for streams that have
+ global credentials.</p>
+ </tp:docstring>
+ <arg name="Username" type="s" direction="in">
+ <tp:docstring>
+ The username to use when authenticating on the stream.
+ </tp:docstring>
+ </arg>
+ <arg name="Password" type="s" direction="in">
+ <tp:docstring>
+ The password to use when authenticating on the stream.
+ </tp:docstring>
+ </arg>
+ </method>
+
+ <tp:mapping name="Candidate_Info">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Extra information about the candidate. Allowed and mandatory keys
+ depend on the transport protocol used. The following keys are commenly
+ used:</p>
+
+ <dl>
+ <dt>Type (u)</dt>
+ <dd>type of candidate (host, srflx, prflx, relay)</dd>
+
+ <dt>Foundation (s)</dt>
+ <dd>the foundation of this candiate</dd>
+
+ <dt>Protocol (u) </dt>
+ <dd>Underlying protocol of the candidate (udp, tcp) </dd>
+
+ <dt>Priority (u) </dt>
+ <dd>Priority of the candidate </dd>
+
+ <dt>BaseIP (u) </dt>
+ <dd>Base IP of this candidate </dd>
+
+ <dt>Username (s) </dt>
+ <dd>Username of this candidate
+ (only if credentials are per candidate)</dd>
+
+ <dt>Password (s) </dt>
+ <dd>Password of this candidate
+ (only if credentials are per candidate)</dd>
+
+ <dt>RawUDPFallback (b) </dt>
+ <dd>Indicate whether this candidate may be used to provide a UDP
+ fallback</dd>
+ </dl>
+ </tp:docstring>
+ <tp:member name="Key" type="s">
+ <tp:docstring>One of the well-known keys documented here, or an
+ implementation-specific key.</tp:docstring>
+ </tp:member>
+ <tp:member name="Value" type="v">
+ <tp:docstring>The value corresponding to that key.</tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <tp:struct name="Candidate" array-name="Candidate_List">
+ <tp:docstring>A Stream Candidate.</tp:docstring>
+ <tp:member name="Component" type="u">
+ <tp:docstring>The component number.</tp:docstring>
+ </tp:member>
+ <tp:member name="IP" type="s">
+ <tp:docstring>The IP address to use.</tp:docstring>
+ </tp:member>
+ <tp:member name="Port" type="q">
+ <tp:docstring>The port number to use.</tp:docstring>
+ </tp:member>
+ <tp:member name="Info" type="a{sv}" tp:type="Candidate_Info">
+ <tp:docstring>Additional information about the candidate.</tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <method name="AddCandidates" tp:name-for-bindings="Add_Candidates">
+ <tp:docstring>
+ Add candidates to the
+ <tp:member-ref>LocalCandidates</tp:member-ref> property and
+ signal them to the remote contact(s).
+ </tp:docstring>
+ <arg name="Candidates" direction="in"
+ type="a(usqa{sv})" tp:type="Candidate[]">
+ <tp:docstring>
+ The candidates to be added.
+ </tp:docstring>
+ </arg>
+ </method>
+
+ <method name="CandidatesPrepared"
+ tp:name-for-bindings="Candidates_Prepared">
+ <tp:docstring>
+ This indicates to the CM that the initial batch of candidates
+ has been added.
+ </tp:docstring>
+ </method>
+
+ <tp:enum type="u" name="Stream_Transport_Type">
+ <tp:changed version="0.21.2">WLM_8_5 was removed</tp:changed>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ A transport that can be used for streaming.
+ </tp:docstring>
+ <tp:enumvalue suffix="Unknown" value="0">
+ <tp:docstring>
+ The stream transport type is unknown or not applicable
+ (for streams that do not have a configurable transport).
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Raw_UDP" value="1">
+ <tp:docstring>
+ Raw UDP, with or without STUN. All streaming clients are assumed to
+ support this transport, so there is no handler capability token for
+ it in the <tp:dbus-ref namespace="ofdT.Channel.Type"
+ >Call.DRAFT</tp:dbus-ref> interface.
+ [This corresponds to "none" or "stun" in the old Media.StreamHandler
+ interface.]
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="ICE" value="2">
+ <tp:docstring>
+ Interactive Connectivity Establishment, as defined by RFC
+ 5245. Note that this value covers ICE-UDP only.
+ [This corresponds to "ice-udp" in the old
+ Media.StreamHandler interface.]
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="GTalk_P2P" value="3">
+ <tp:docstring>
+ Google Talk peer-to-peer connectivity establishment, as implemented
+ by libjingle 0.3.
+ [This corresponds to "gtalk-p2p" in the old Media.StreamHandler
+ interface.]
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="WLM_2009" value="4">
+ <tp:docstring>
+ The transport used by Windows Live Messenger 2009 or later, which
+ resembles ICE draft 19.
+ [This corresponds to "wlm-2009" in the old Media.StreamHandler
+ interface.]
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="SHM" value="5">
+ <tp:added version="0.21.2"/>
+ <tp:docstring>
+ Shared memory transport, as implemented by the GStreamer
+ shmsrc and shmsink plugins.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Multicast" value="6">
+ <tp:added version="0.21.5"/>
+ <tp:docstring>
+ Multicast transport.
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <property name="Transport" tp:name-for-bindings="Transport"
+ type="u" tp:type="Stream_Transport_Type" access="read" tp:immutable="yes">
+ <tp:docstring>
+ The transport for this stream.
+ </tp:docstring>
+ </property>
+
+ <property name="LocalCandidates" tp:name-for-bindings="Local_Candidates"
+ type="a(usqa{sv})" tp:type="Candidate[]" access="read">
+ <tp:docstring>
+ [FIXME]. Change notification is via the
+ <tp:member-ref>LocalCandidatesAdded</tp:member-ref> signal.
+ </tp:docstring>
+ </property>
+
+ <signal name="LocalCandidatesAdded"
+ tp:name-for-bindings="Local_Candidates_Added">
+ <tp:docstring>
+ Emitted when local candidates are added to the
+ <tp:member-ref>LocalCandidates</tp:member-ref> property.
+ </tp:docstring>
+ <arg name="Candidates" type="a(usqa{sv})" tp:type="Candidate[]">
+ <tp:docstring>
+ Candidates that have been added.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <tp:struct name="Stream_Credentials">
+ <tp:docstring>A username and password pair.</tp:docstring>
+
+ <tp:member name="Username" type="s">
+ <tp:docstring>The username.</tp:docstring>
+ </tp:member>
+
+ <tp:member name="Password" type="s">
+ <tp:docstring>The password.</tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <property name="LocalCredentials" tp:name-for-bindings="Local_Credentials"
+ type="(ss)" tp:type="Stream_Credentials" access="read">
+ <tp:docstring>
+ [FIXME]. Change notification is via the
+ <tp:member-ref>LocalCredentialsChanged</tp:member-ref> signal.
+ </tp:docstring>
+ </property>
+
+ <signal name="LocalCredentialsChanged"
+ tp:name-for-bindings="Local_Credentials_Changed">
+ <tp:changed version="0.21.2">renamed from LocalCredentailsSet</tp:changed>
+ <tp:docstring>
+ Emitted when the value of
+ <tp:member-ref>LocalCredentials</tp:member-ref> changes.
+ </tp:docstring>
+ <arg name="Username" type="s" />
+ <arg name="Password" type="s" />
+ </signal>
+
+ <signal name="RelayInfoChanged"
+ tp:name-for-bindings="Relay_Info_Changed">
+ <tp:docstring>
+ Emitted when the value of
+ <tp:member-ref>RelayInfo</tp:member-ref> changes.
+ </tp:docstring>
+ <arg name="Relay_Info" type="aa{sv}" tp:type="String_Variant_Map[]" />
+ </signal>
+
+ <signal name="STUNServersChanged"
+ tp:name-for-bindings="STUN_Servers_Changed">
+ <tp:docstring>
+ Emitted when the value of
+ <tp:member-ref>STUNServers</tp:member-ref> changes.
+ </tp:docstring>
+ <arg name="Servers" type="a(sq)" tp:type="Socket_Address_IP[]" />
+ </signal>
+
+ <property name="STUNServers" tp:name-for-bindings="STUN_Servers"
+ type="a(sq)" tp:type="Socket_Address_IP[]" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The IP addresses of possible STUN servers to use for NAT
+ traversal, as dotted-quad IPv4 address literals or RFC2373
+ IPv6 address literals. Change notification is via the
+ <tp:member-ref>STUNServersChanged</tp:member-ref>
+ signal. The IP addresses MUST NOT be given as DNS hostnames.</p>
+
+ <tp:rationale>
+ High-quality connection managers already need an asynchronous
+ DNS resolver, so they might as well resolve this name to an IP
+ to make life easier for streaming implementations.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="RelayInfo" type="aa{sv}" access="read"
+ tp:type="String_Variant_Map[]" tp:name-for-bindings="Relay_Info">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A list of mappings describing TURN or Google relay servers
+ available for the client to use in its candidate gathering, as
+ determined from the protocol. Map keys are:</p>
+
+ <dl>
+ <dt><code>ip</code> - s</dt>
+ <dd>The IP address of the relay server as a dotted-quad IPv4
+ address literal or an RFC2373 IPv6 address literal. This MUST NOT
+ be a DNS hostname.
+
+ <tp:rationale>
+ High-quality connection managers already need an asynchronous
+ DNS resolver, so they might as well resolve this name to an IP
+ and make life easier for streaming implementations.
+ </tp:rationale>
+ </dd>
+
+ <dt><code>type</code> - s</dt>
+ <dd>
+ <p>Either <code>udp</code> for UDP (UDP MUST be assumed if this
+ key is omitted), <code>tcp</code> for TCP, or
+ <code>tls</code>.</p>
+
+ <p>The precise meaning of this key depends on the
+ <tp:member-ref>Transport</tp:member-ref> property: if
+ Transport is ICE, <code>tls</code> means
+ TLS over TCP as referenced by ICE draft 19, and if
+ Transport is GTalk_P2P, <code>tls</code> means
+ a fake SSL session over TCP as implemented by libjingle.</p>
+ </dd>
+
+ <dt><code>port</code> - q</dt>
+ <dd>The UDP or TCP port of the relay server as an ASCII unsigned
+ integer</dd>
+
+ <dt><code>username</code> - s</dt>
+ <dd>The username to use</dd>
+
+ <dt><code>password</code> - s</dt>
+ <dd>The password to use</dd>
+
+ <dt><code>component</code> - u</dt>
+ <dd>The component number to use this relay server for, as an
+ ASCII unsigned integer; if not included, this relay server
+ may be used for any or all components.
+
+ <tp:rationale>
+ In ICE draft 6, as used by Google Talk, credentials are only
+ valid once, so each component needs relaying separately.
+ </tp:rationale>
+ </dd>
+ </dl>
+
+ <tp:rationale>
+ <p>An equivalent of the gtalk-p2p-relay-token property on
+ MediaSignalling channels is not included here. The connection
+ manager should be responsible for making the necessary HTTP
+ requests to turn the token into a username and password.</p>
+ </tp:rationale>
+
+ <p>The type of relay server that this represents depends on
+ the value of the <tp:member-ref>Transport</tp:member-ref>
+ property. If Transport is ICE, this is a TURN server;
+ if Transport is GTalk_P2P, this is a Google relay server;
+ otherwise, the meaning of RelayInfo is undefined.</p>
+
+ <p>If relaying is not possible for this stream, the list is
+ empty.</p>
+
+ <p>Change notification is given via the
+ <tp:member-ref>RelayInfoChanged</tp:member-ref> signal.</p>
+ </tp:docstring>
+ </property>
+
+ <signal name="ServerInfoRetrieved"
+ tp:name-for-bindings="Server_Info_Retrieved">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Signals that the initial information about STUN and Relay servers
+ has been retrieved, i.e. the
+ <tp:member-ref>HasServerInfo</tp:member-ref> property is
+ now true.</p>
+ </tp:docstring>
+ </signal>
+
+ <property name="HasServerInfo" type="b"
+ tp:name-for-bindings="Has_Server_Info" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>True if all the initial information about STUN servers and Relay
+ servers has been retrieved. Change notification is via the
+ <tp:member-ref>ServerInfoRetrieved</tp:member-ref> signal.</p>
+
+ <tp:rationale>
+ Streaming implementations that can't cope with STUN and
+ relay servers being added later SHOULD wait for this
+ property to become true before proceeding.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <signal name="EndpointsChanged"
+ tp:name-for-bindings="Endpoints_Changed">
+ <tp:docstring>
+ Emitted when the <tp:member-ref>Endpoints</tp:member-ref> property
+ changes.
+ </tp:docstring>
+ <arg name="Endpoints_Added" type="ao">
+ <tp:docstring>
+ Endpoints that were added.
+ </tp:docstring>
+ </arg>
+ <arg name="Endpoints_Removed" type="ao">
+ <tp:docstring>
+ Endpoints that no longer exist.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <property name="Endpoints" tp:name-for-bindings="Endpoints"
+ type="ao" access="read">
+ <tp:docstring>
+ <p>The list of <tp:dbus-ref namespace="ofdT.Call.Stream"
+ >Endpoint.DRAFT</tp:dbus-ref> objects that exist for this
+ stream.</p>
+
+ <p>Change notification is via the
+ <tp:member-ref>EndpointsChanged</tp:member-ref> signal.</p>
+ </tp:docstring>
+ </property>
+
+ <signal name="PleaseRestartICE"
+ tp:name-for-bindings="Please_Restart_ICE">
+ <tp:docstring>
+ Emitted when the CM does an ICE restart to notify the
+ streaming implementation that it should call
+ <tp:member-ref>SetCredentials</tp:member-ref> again.
+ </tp:docstring>
+ </signal>
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel.xml b/spec/Channel.xml
new file mode 100644
index 0000000..11d3e50
--- /dev/null
+++ b/spec/Channel.xml
@@ -0,0 +1,557 @@
+<?xml version="1.0" ?>
+<node name="/Channel" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2005-2009 Collabora Limited</tp:copyright>
+ <tp:copyright>Copyright © 2005-2009 Nokia Corporation</tp:copyright>
+ <tp:copyright>Copyright © 2006 INdT</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.</p>
+
+<p>This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+Lesser General Public License for more details.</p>
+
+<p>You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
+ </tp:license>
+ <interface name="org.freedesktop.Telepathy.Channel">
+
+ <property name="ChannelType" type="s" tp:type="DBus_Interface"
+ access="read" tp:name-for-bindings="Channel_Type">
+ <tp:added version="0.17.7"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The channel's type. This cannot change once the channel has
+ been created.</p>
+
+ <p>For compatibility between older connection managers and newer
+ clients, if this is unavailable or is an empty string,
+ clients MUST use the result of calling
+ <tp:member-ref>GetChannelType</tp:member-ref>.</p>
+
+ <tp:rationale>
+ The GetAll method lets clients retrieve all properties in one
+ round-trip, which is desirable.
+ </tp:rationale>
+
+ <p>When requesting a channel, the request MUST specify a channel
+ type, and the request MUST fail if the specified channel type
+ cannot be supplied.</p>
+
+ <tp:rationale>
+ Common sense.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="Interfaces" tp:name-for-bindings="Interfaces"
+ type="as" tp:type="DBus_Interface[]" access="read">
+ <tp:added version="0.17.7"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Extra interfaces provided by this channel. This SHOULD NOT include
+ the channel type and the Channel interface itself, and cannot
+ change once the channel has been created.</p>
+
+ <p>For compatibility between older connection managers and newer
+ clients, if this is unavailable, or if this is an empty list and
+ <tp:member-ref>ChannelType</tp:member-ref> is an empty string,
+ clients MUST use the result of calling
+ <tp:member-ref>GetInterfaces</tp:member-ref> instead. If this is an
+ empty list but ChannelType is non-empty, clients SHOULD NOT call
+ GetInterfaces; this implies that connection managers that implement
+ the ChannelType property MUST also implement the Interfaces property
+ correctly.</p>
+
+ <tp:rationale>
+ The GetAll method lets clients retrieve all properties in one
+ round-trip, which is desirable.
+ </tp:rationale>
+
+ <p>When requesting a channel with a particular value for this
+ property, the request must fail without side-effects unless the
+ connection manager expects to be able to provide a channel whose
+ interfaces include at least the interfaces requested.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="TargetHandle" type="u" access="read" tp:type="Handle"
+ tp:name-for-bindings="Target_Handle">
+ <tp:added version="0.17.7"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The handle (a representation for the identifier) of the contact,
+ chatroom, etc. with which this handle communicates. Its type
+ is given by the <tp:member-ref>TargetHandleType</tp:member-ref>
+ property.</p>
+
+ <p>This is fixed for the lifetime of the channel, so channels which
+ could potentially be used to communicate with multiple contacts,
+ and do not have an identity of their own (such as a Handle_Type_Room
+ handle), must have TargetHandleType set to Handle_Type_None and
+ TargetHandle set to 0.</p>
+
+ <p>Unlike in the telepathy-spec 0.16 API, there is no particular
+ uniqueness guarantee - there can be many channels with the same
+ (channel type, handle type, handle) tuple. This is necessary
+ to support conversation threads in XMPP and SIP, for example.</p>
+
+ <p>If this is present in a channel request, it must be nonzero,
+ <tp:member-ref>TargetHandleType</tp:member-ref>
+ MUST be present and not Handle_Type_None, and
+ <tp:member-ref>TargetID</tp:member-ref> MUST NOT be
+ present. Properties from
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface">Addressing.DRAFT</tp:dbus-ref>
+ MUST NOT be present.</p>
+
+ <p>The channel that satisfies the request MUST either:</p>
+
+ <ul>
+ <li>have the specified TargetHandle property; or</li>
+ <li>have <tp:member-ref>TargetHandleType</tp:member-ref> =
+ Handle_Type_None, TargetHandle = 0, and be configured such that
+ it could communicate with the specified handle in some other way
+ (e.g. have the requested contact handle in its Group
+ interface)</li>
+ </ul>
+ </tp:docstring>
+ </property>
+
+ <property name="TargetID" tp:name-for-bindings="Target_ID"
+ type="s" access="read">
+ <tp:added version="0.17.9"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The string that would result from inspecting the
+ <tp:member-ref>TargetHandle</tp:member-ref>
+ property (i.e. the identifier in the IM protocol of the contact,
+ room, etc. with which this channel communicates), or the empty
+ string if the TargetHandle is 0.</p>
+
+ <tp:rationale>
+ <p>The presence of this property avoids the following race
+ condition:</p>
+
+ <ul>
+ <li>New channel C is signalled with target handle T</li>
+ <li>Client calls <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(CONTACT,
+ [T])</li>
+ <li>Channel C closes, removing the last reference to handle T</li>
+ <li><tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(CONTACT,
+ [T]) returns an error</li>
+ </ul>
+ </tp:rationale>
+
+ <p>If this is present in a channel request,
+ <tp:member-ref>TargetHandleType</tp:member-ref>
+ MUST be present and not Handle_Type_None, and
+ <tp:member-ref>TargetHandle</tp:member-ref> MUST NOT be
+ present. Properties from
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface">Addressing.DRAFT</tp:dbus-ref>
+ MUST NOT be present.The request MUST fail with error InvalidHandle,
+ without side-effects, if the requested TargetID would not be
+ accepted by
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection">RequestHandles</tp:dbus-ref>.</p>
+
+ <p>The returned channel must be related to the handle corresponding
+ to the given identifier, in the same way as if TargetHandle
+ had been part of the request instead.</p>
+
+ <tp:rationale>
+ <p>Requesting channels with a string identifier saves a round-trip
+ (the call to RequestHandles). It also allows the channel
+ dispatcher to accept a channel request for an account that is not
+ yet connected (and thus has no valid handles), bring the account
+ online, and pass on the same parameters to the new connection's
+ CreateChannel method.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="TargetHandleType" type="u" access="read"
+ tp:type="Handle_Type" tp:name-for-bindings="Target_Handle_Type">
+ <tp:added version="0.17.7"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The type of <tp:member-ref>TargetHandle</tp:member-ref>.</p>
+
+ <p>If this is omitted from a channel request, connection managers
+ SHOULD treat this as equivalent to Handle_Type_None.</p>
+
+ <p>If this is omitted or is Handle_Type_None,
+ <tp:member-ref>TargetHandle</tp:member-ref> and
+ <tp:member-ref>TargetID</tp:member-ref> MUST be omitted from the
+ request.</p>
+ </tp:docstring>
+ </property>
+
+ <method name="Close" tp:name-for-bindings="Close">
+ <tp:docstring>
+ Request that the channel be closed. This is not the case until
+ the <tp:member-ref>Closed</tp:member-ref> signal has been emitted, and
+ depending on the connection
+ manager this may simply remove you from the channel on the server,
+ rather than causing it to stop existing entirely. Some channels
+ such as contact list channels may not be closed.
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ This channel may never be closed, e.g. a contact list
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ This channel is not currently in a state where it can be closed,
+ e.g. a non-empty user-defined contact group
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <signal name="Closed" tp:name-for-bindings="Closed">
+ <tp:docstring>
+ Emitted when the channel has been closed. Method calls on the
+ channel are no longer valid after this signal has been emitted,
+ and the connection manager may then remove the object from the bus
+ at any point.
+ </tp:docstring>
+ </signal>
+
+ <method name="GetChannelType" tp:name-for-bindings="Get_Channel_Type">
+ <tp:deprecated version="0.17.7">Use the ChannelType
+ property if possible.</tp:deprecated>
+ <arg direction="out" type="s" tp:type="DBus_Interface"
+ name="Channel_Type">
+ <tp:docstring>The interface name</tp:docstring>
+ </arg>
+ <tp:docstring>
+ Returns the interface name for the type of this channel. Clients
+ SHOULD use the <tp:member-ref>ChannelType</tp:member-ref> property
+ instead, falling back to this method only if necessary.
+
+ <tp:rationale>
+ The GetAll method lets clients retrieve all properties in one
+ round-trip.
+ </tp:rationale>
+ </tp:docstring>
+ </method>
+
+ <method name="GetHandle" tp:name-for-bindings="Get_Handle">
+ <tp:deprecated version="0.17.7">Use the TargetHandleType
+ and TargetHandle properties if possible.</tp:deprecated>
+ <arg direction="out" type="u" tp:type="Handle_Type"
+ name="Target_Handle_Type">
+ <tp:docstring>
+ The same as TargetHandleType.
+ </tp:docstring>
+ </arg>
+ <arg direction="out" type="u" tp:type="Handle" name="Target_Handle">
+ <tp:docstring>
+ The same as TargetHandle.
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Returns the handle type and number if this channel represents a
+ communication with a particular contact, room or server-stored list, or
+ zero if it is transient and defined only by its contents. Clients
+ SHOULD use the <tp:member-ref>TargetHandle</tp:member-ref> and
+ <tp:member-ref>TargetHandleType</tp:member-ref> properties instead,
+ falling back to this method only if necessary.
+
+ <tp:rationale>
+ The GetAll method lets clients retrieve all properties in one
+ round-trip.
+ </tp:rationale>
+ </tp:docstring>
+ </method>
+
+ <method name="GetInterfaces" tp:name-for-bindings="Get_Interfaces">
+ <tp:deprecated version="0.17.7">Use the Interfaces
+ property if possible.</tp:deprecated>
+ <arg direction="out" type="as" tp:type="DBus_Interface[]"
+ name="Interfaces">
+ <tp:docstring>
+ An array of the D-Bus interface names
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Get the optional interfaces implemented by the channel.
+ Clients SHOULD use the <tp:member-ref>Interfaces</tp:member-ref>
+ property instead, falling back to this method only if necessary.
+
+ <tp:rationale>
+ The GetAll method lets clients retrieve all properties in one
+ round-trip.
+ </tp:rationale>
+ </tp:docstring>
+ </method>
+
+ <property name="Requested" tp:name-for-bindings="Requested"
+ type="b" access="read">
+ <tp:added version="0.17.13">(as stable API)</tp:added>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>True if this channel was created in response to a local request,
+ such as a call to
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.RequestChannel</tp:dbus-ref>
+ or
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>.</p>
+
+ <tp:rationale>
+ <p>The idea of this property is to distinguish between "incoming"
+ and "outgoing" channels, in a way that doesn't break down when
+ considering special cases like contact lists that are automatically
+ created on connection to the server, or chatrooms that an
+ IRC proxy/bouncer like irssi-proxy or bip was already in.</p>
+
+ <p>The reason we want to make that distinction is that UIs for
+ things that the user explicitly requested should start up
+ automatically, whereas for incoming messages and VoIP calls we
+ should first ask the user whether they want to open the messaging
+ UI or accept the call.</p>
+ </tp:rationale>
+
+ <p>If the channel was not explicitly requested (even if it was
+ created as a side-effect of a call to one of those functions,
+ e.g. because joining a Tube in a MUC context on XMPP implies
+ joining that MUC), then this property is false.</p>
+
+ <p>For compatibility with older connection managers, clients SHOULD
+ assume that this property is true if they see a channel announced
+ by the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.NewChannel</tp:dbus-ref>
+ signal with the suppress_handler parameter set to true.</p>
+
+ <tp:rationale>
+ <p>In a correct connection manager, the only way to get such a
+ channel is to request it.</p>
+ </tp:rationale>
+
+ <p>Clients MAY additionally assume that this property is false
+ if they see a channel announced by the NewChannel signal with the
+ suppress_handler parameter set to false.</p>
+
+ <tp:rationale>
+ <p>This is more controversial, since it's possible to get that
+ parameter set to false by requesting a channel. However, there's
+ no good reason to do so, and we've deprecated this practice.</p>
+
+ <p>In the particular case of the channel dispatcher, the only
+ side-effect of wrongly thinking a channel is unrequested
+ is likely to be that the user has to confirm that they want to
+ use it, so it seems fairly harmless to assume in the channel
+ dispatcher that channels with suppress_handler false are
+ indeed unrequested.</p>
+ </tp:rationale>
+
+ <p>It does not make sense for this property to be in channel
+ requests—it will always be true for channels returned by
+ CreateChannel, and callers of EnsureChannel cannot control whether an
+ existing channel was originally requested locally—so it MUST NOT
+ be accepted.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="InitiatorHandle" type="u" tp:type="Contact_Handle"
+ access="read" tp:name-for-bindings="Initiator_Handle">
+ <tp:added version="0.17.13">(as stable API)</tp:added>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The contact who initiated the channel; for instance, the contact
+ who invited the local user to a chatroom, or the contact who
+ initiated a call.</p>
+
+ <p>This does <em>not</em> necessarily represent the contact who
+ created the underlying protocol-level construct. For instance, if
+ Rob creates a chatroom, Will joins that chatroom, and Will invites Simon
+ to join it, then Simon will see Will as the InitiatorHandle of the
+ channel representing the chatroom.</p>
+
+ <tp:rationale>
+ <p>The room creator is generally a less useful piece of information
+ than the inviter, is less likely to be available at invitation
+ time (i.e. can't necessarily be an immutable property), and is
+ less likely to be available at all. The creator of a chatroom
+ is not currently available via Telepathy; if added in future, it
+ is likely to be made available as a property on the Chatroom
+ interface (<a
+ href="http://bugs.freedesktop.org/show_bug.cgi?id=23151">bug 23151</a>).</p>
+ </tp:rationale>
+
+ <p>For channels requested by the
+ local user, this MUST be the value of
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.SelfHandle</tp:dbus-ref>
+ at the time the channel was created (i.e. not a channel-specific
+ handle).</p>
+
+ <tp:rationale>
+ <p>On some protocols, the SelfHandle may change (as signalled by
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Connection.SelfHandleChanged</tp:dbus-ref>),
+ but this property is immutable. Hence, locally-requested channels'
+ InitiatorHandle and InitiatorID may not match the current
+ SelfHandle; <tp:member-ref>Requested</tp:member-ref> can be used to
+ determine whether the channel was created locally.</p>
+ </tp:rationale>
+
+ <p>For channels requested by a remote user, this MUST be their handle.
+ If unavailable or not applicable, this MUST be 0 (for instance,
+ contact lists are not really initiated by anyone in particular, and
+ it's easy to imagine a protocol where chatroom invitations can be
+ anonymous).</p>
+
+ <p>For channels with the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface">Group</tp:dbus-ref>
+ interface, this SHOULD be the same
+ contact who is signalled as the "Actor" causing the self-handle
+ to be placed in the local-pending set.</p>
+
+ <p>This SHOULD NOT be a channel-specific handle, if possible.</p>
+
+ <p>It does not make sense for this property to be in channel
+ requests - the initiator will always be the local user - so it
+ MUST NOT be accepted.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="InitiatorID" type="s" access="read"
+ tp:name-for-bindings="Initiator_ID">
+ <tp:added version="0.17.13">(as stable API)</tp:added>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The string that would result from inspecting the
+ <tp:member-ref>InitiatorHandle</tp:member-ref>
+ property (i.e. the initiator's identifier in the IM protocol).</p>
+
+ <tp:rationale>
+ <p>The presence of this property avoids the following race
+ condition:</p>
+
+ <ul>
+ <li>New StreamedMedia channel C is signalled with initiator
+ handle I</li>
+ <li>Client calls <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(CONTACT,
+ [I])</li>
+ <li>Channel C closes, removing the last reference to handle I</li>
+ <li><tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>(CONTACT,
+ [I]) returns an error</li>
+ <li>Client can indicate that a call was missed, but not who
+ called!</li>
+ </ul>
+ </tp:rationale>
+
+ <p>It does not make sense for this property to be in channel
+ requests - the initiator will always be the local user - so it
+ MUST NOT be accepted.</p>
+ </tp:docstring>
+ </property>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>All communication in the Telepathy framework is carried out via channel
+ objects which are created and managed by connections. This interface must
+ be implemented by all channel objects, along with one single channel type,
+ such as <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel.Type.ContactList</tp:dbus-ref>
+ which represents a list of people (such as a buddy list) or <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel.Type.Text</tp:dbus-ref> which
+ represents a channel over which textual messages are sent and received.</p>
+
+ <p>Each Channel's object path MUST start with the object path of
+ its associated <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>, followed
+ by '/'. There MAY be any number of additional object-path components,
+ which clients MUST NOT attempt to parse.</p>
+
+ <tp:rationale>
+ <p>This ensures that Channel object paths are unique, even between
+ Connections and CMs, because Connection object paths are
+ guaranteed-unique via their link to the well-known bus name.</p>
+
+ <p>If all connection managers in use are known to comply with at least
+ spec version 0.17.10, then the Connection's object path can
+ even be determined from the Channel's without any additional
+ information, by taking the first 7 components.</p>
+ </tp:rationale>
+
+ <p>Each channel has a number of immutable properties (which cannot vary
+ after the channel has been announced with <tp:dbus-ref
+ namespace='ofdT.Connection.Interface.Requests'>NewChannels</tp:dbus-ref>),
+ provided to clients in the
+ <tp:dbus-ref namespace='ofdT.Client.Observer'>ObserveChannels</tp:dbus-ref>,
+ <tp:dbus-ref namespace='ofdT.Client.Approver'>AddDispatchOperation</tp:dbus-ref> and
+ <tp:dbus-ref namespace='ofdT.Client.Handler'>HandleChannels</tp:dbus-ref>
+ methods to permit immediate identification of the channel. This interface
+ contains immutable properties common to all channels. In brief:</p>
+
+ <ul>
+ <li><tp:member-ref>ChannelType</tp:member-ref> specifies the kind of
+ communication carried out on this channel;</li>
+ <li><tp:member-ref>TargetHandleType</tp:member-ref>,
+ <tp:member-ref>TargetHandle</tp:member-ref> and
+ <tp:member-ref>TargetID</tp:member-ref> specify the entity with which
+ this channel communicates, such as the other party in a 1-1 call, or
+ the name of a multi-user chat room;</li>
+ <li><tp:member-ref>InitiatorHandle</tp:member-ref> and
+ <tp:member-ref>InitiatorID</tp:member-ref> specify who created this
+ channel;</li>
+ <li><tp:member-ref>Requested</tp:member-ref> indicates whether the local
+ user requested this channel, or whether it is an incoming call, a text
+ conversation started by a remote contact, a chatroom invitation,
+ etc.</li>
+ </ul>
+
+ <p>Other optional <tp:member-ref>Interfaces</tp:member-ref> can be
+ implemented to indicate other available
+ functionality, such as <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel.Interface.Group</tp:dbus-ref>
+ if the channel contains a number of contacts, <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel.Interface.Password</tp:dbus-ref>
+ to indicate that a channel may have a password set to require entry, and
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel.Interface.ChatState</tp:dbus-ref>
+ for typing notifications. The interfaces implemented may not vary after
+ the channel has been created. These other interfaces (along with the
+ interface named by <tp:member-ref>ChannelType</tp:member-ref>) may
+ themselves specify immutable properties to be announced up-front along
+ with the properties on this interface.</p>
+
+ <p>Some channels are “anonymous”, with
+ <tp:member-ref>TargetHandleType</tp:member-ref> set to <code>None</code>,
+ which indicates that the channel is defined by some other properties. For
+ instance, transient ad-hoc chat rooms may be defined only by their members (as visible
+ through the <tp:dbus-ref
+ namespace="ofdT.Channel.Interface">Group</tp:dbus-ref>
+ interface), and <tp:dbus-ref
+ namespace='ofdT.Channel.Type'>ContactSearch</tp:dbus-ref>
+ channels represent a single search attempt for a particular <tp:dbus-ref
+ namespace='ofdT.Channel.Type.ContactSearch'>Server</tp:dbus-ref>.</p>
+
+ <p>Specific connection manager implementations may implement channel types and
+ interfaces which are not contained within this specification in order to
+ support further functionality. To aid interoperability between client and
+ connection manager implementations, the interfaces specified here should be
+ used wherever applicable, and new interfaces made protocol-independent
+ wherever possible. Because of the potential for 3rd party interfaces adding
+ methods or signals with conflicting names, the D-Bus interface names should
+ always be used to invoke methods and bind signals.</p>
+ </tp:docstring>
+
+ <tp:changed version="0.17.7">Previously we guaranteed that, for
+ any handle type other than Handle_Type_None, and for any channel type
+ and any handle, there would be no more than one channel with that
+ combination of channel type, handle type and handle. This guarantee
+ has now been removed in order to accommodate features like message
+ threads.
+ </tp:changed>
+
+ <tp:changed version="0.17.10">Previously we did not explicitly
+ guarantee that Channels' object paths had the Connection's object path
+ as a prefix.
+ </tp:changed>
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Bundle.xml b/spec/Channel_Bundle.xml
new file mode 100644
index 0000000..d211525
--- /dev/null
+++ b/spec/Channel_Bundle.xml
@@ -0,0 +1,48 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Bundle"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+<p>This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.</p>
+
+<p>This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+Lesser General Public License for more details.</p>
+
+<p>You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+</p>
+ </tp:license>
+ <interface name="org.freedesktop.Telepathy.ChannelBundle.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A group of related channels, which should all be dispatched to the
+ same handler if possible.</p>
+
+ <p>Bundles currently have no functionality of their own, so clients
+ SHOULD NOT examine this interface, but should instead treat the
+ bundle object-path as an opaque identifier. If more functionality is
+ added to bundles in future, this interface will be used for capability
+ discovery.</p>
+
+ <p>The lifetime of a bundle is defined by its component channels -
+ as long as one or more channels whose Bundle property is <em>B</em>
+ exist, the bundle <em>B</em> will also exist.</p>
+ </tp:docstring>
+
+ <property name="Interfaces" tp:name-for-bindings="Interfaces"
+ type="as" access="read" tp:type="DBus_Interface[]">
+ <tp:docstring>
+ A list of the extra interfaces provided by this channel bundle.
+ </tp:docstring>
+ </property>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Dispatch_Operation.xml b/spec/Channel_Dispatch_Operation.xml
new file mode 100644
index 0000000..6ec69a6
--- /dev/null
+++ b/spec/Channel_Dispatch_Operation.xml
@@ -0,0 +1,483 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Dispatch_Operation"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+
+ <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ License as published by the Free Software Foundation; either
+ version 2.1 of the License, or (at your option) any later version.</p>
+
+ <p>This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.</p>
+
+ <p>You should have received a copy of the GNU Lesser General Public
+ License along with this library; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
+ MA 02110-1301, USA.</p>
+ </tp:license>
+
+ <interface name="org.freedesktop.Telepathy.ChannelDispatchOperation">
+ <tp:added version="0.17.26">(as a stable interface)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A channel dispatch operation is an object in the ChannelDispatcher
+ representing a batch of unrequested channels being announced to
+ client
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Client">Approver</tp:dbus-ref>
+ processes.</p>
+
+ <p>These objects can result from new incoming channels or channels
+ which are automatically created for some reason, but cannot result
+ from outgoing requests for channels.</p>
+
+ <p>More specifically, whenever the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.NewChannels</tp:dbus-ref>
+ signal contains channels whose
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">Requested</tp:dbus-ref>
+ property is false, or whenever the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.NewChannel</tp:dbus-ref>
+ signal contains a channel with suppress_handler false,
+ one or more ChannelDispatchOperation objects are created for those
+ channels.</p>
+
+ <p>(If some channels in a NewChannels signal are in different bundles,
+ this is an error. The channel dispatcher SHOULD recover by treating
+ the NewChannels signal as if it had been several NewChannels signals
+ each containing one channel.)</p>
+
+ <p>First, the channel dispatcher SHOULD construct a list of all the
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref>s
+ that could handle all the channels (based on their <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref>
+ property), ordered by
+ priority in some implementation-dependent way. If there are handlers
+ which could handle all the channels, one channel dispatch operation
+ SHOULD be created for all the channels. If there are not, one channel
+ dispatch operation SHOULD be created for each channel, each with
+ a list of channel handlers that could handle that channel.</p>
+
+ <p>If no handler at all can handle a channel, the channel dispatcher
+ SHOULD terminate that channel instead of creating a channel dispatcher
+ for it. It is RECOMMENDED that the channel dispatcher closes
+ the channels using <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel.Interface.Destroyable.Destroy</tp:dbus-ref>
+ if supported, or <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel.Close</tp:dbus-ref>
+ otherwise. As a special case, the channel dispatcher SHOULD NOT close
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">ContactList</tp:dbus-ref>
+ channels, and if Close fails, the channel dispatcher SHOULD ignore
+ that channel.</p>
+
+ <tp:rationale>
+ <p>ContactList channels are strange. We hope to replace them with
+ something better, such as an interface on the Connection, in a
+ future version of this specification.</p>
+ </tp:rationale>
+
+ <p>When listing channel handlers, priority SHOULD be given to
+ channel handlers that are already handling channels from the same
+ bundle.</p>
+
+ <p>If a handler with <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">BypassApproval</tp:dbus-ref>
+ <code>= True</code> could handle all of the channels in the dispatch
+ operation, then the channel dispatcher SHOULD call <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref>
+ on that handler, and (assuming the call succeeds) emit
+ <tp:member-ref>Finished</tp:member-ref> and stop processing those
+ channels without involving any approvers.</p>
+
+ <tp:rationale>
+ <p>Some channel types can be picked up "quietly" by an existing
+ channel handler. If a <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref>
+ channel is added to an existing bundle containing a <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref>
+ channel, there shouldn't be
+ any approvers, flashing icons or notification bubbles, if the
+ the UI for the StreamedMedia channel can just add a text box
+ and display the message.</p>
+ </tp:rationale>
+
+ <p>Otherwise, the channel dispatcher SHOULD send the channel dispatch
+ operation to all relevant approvers (in parallel) and wait for an
+ approver to claim the channels or request that they are handled.
+ See
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Approver">AddDispatchOperation</tp:dbus-ref>
+ for more details on this.</p>
+
+ <p>Finally, if the approver requested it, the channel dispatcher SHOULD
+ send the channels to a handler.</p>
+ </tp:docstring>
+
+ <property name="Interfaces" tp:name-for-bindings="Interfaces"
+ type="as" access="read" tp:type="DBus_Interface[]">
+ <tp:docstring>
+ A list of the extra interfaces provided by this channel dispatch
+ operation. This property cannot change.
+ </tp:docstring>
+ </property>
+
+ <property name="Connection" tp:name-for-bindings="Connection"
+ type="o" access="read">
+ <tp:docstring>
+ The <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>
+ with which the <tp:member-ref>Channels</tp:member-ref> are
+ associated. The well-known bus name to use can be derived from
+ this object path by removing the leading '/' and replacing all
+ subsequent '/' by '.'. This property cannot change.
+ </tp:docstring>
+ </property>
+
+ <property name="Account" tp:name-for-bindings="Account"
+ type="o" access="read">
+ <tp:docstring>
+ The <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>
+ with which the <tp:member-ref>Connection</tp:member-ref>
+ and <tp:member-ref>Channels</tp:member-ref> are
+ associated. This property cannot change.
+ </tp:docstring>
+ </property>
+
+ <property name="Channels" tp:name-for-bindings="Channels"
+ type="a(oa{sv})" access="read" tp:type="Channel_Details[]">
+ <tp:docstring>
+ The <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref>s
+ to be dispatched, and their properties. Change notification is via
+ the <tp:member-ref>ChannelLost</tp:member-ref> signal (channels
+ cannot be added to this property, only removed).
+ </tp:docstring>
+ </property>
+
+ <signal name="ChannelLost" tp:name-for-bindings="Channel_Lost">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A channel has closed before it could be claimed or handled. If
+ this is emitted for the last remaining channel in a channel
+ dispatch operation, it MUST immediately be followed by
+ <tp:member-ref>Finished</tp:member-ref>.</p>
+
+ <p>This signal MUST NOT be emitted until all Approvers that were
+ invoked have returned (successfully or with an error) from
+ their <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Approver">AddDispatchOperation</tp:dbus-ref>
+ method.</p>
+
+ <tp:rationale>
+ <p>This means that Approvers can connect to the ChannelLost signal
+ in a race-free way. Non-approver processes that discover
+ a channel dispatch operation in some way (such as observers)
+ will have to follow the usual "connect to signals then recover
+ state" model - first connect to ChannelLost and
+ <tp:member-ref>Finished</tp:member-ref>,
+ then download <tp:member-ref>Channels</tp:member-ref> (and
+ on error, perhaps assume that the operation has already
+ Finished).</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg name="Channel" type="o">
+ <tp:docstring>
+ The <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref>
+ that closed.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Error" type="s" tp:type="DBus_Error_Name">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The name of a D-Bus error indicating why the channel closed. If
+ no better reason can be found,
+ <code>org.freedesktop.Telepathy.Error.NotAvailable</code> MAY
+ be used as a fallback; this means that this error SHOULD NOT be
+ given any more specific meaning.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg name="Message" type="s">
+ <tp:docstring>
+ A string associated with the D-Bus error.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <property name="PossibleHandlers" tp:name-for-bindings="Possible_Handlers"
+ type="as" access="read" tp:type="DBus_Well_Known_Name[]">
+ <tp:docstring>
+ <p>The well known bus names (starting with
+ <code>org.freedesktop.Telepathy.Client.</code>) of the possible
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref>s
+ for these channels. The channel dispatcher MUST place the most
+ preferred handlers first, according to some reasonable heuristic.
+ As a result, approvers SHOULD use the first handler by default.</p>
+
+ <p>The heuristic used to prioritize handlers SHOULD give a higher
+ priority to handlers that are already running.</p>
+
+ <tp:rationale>
+ <p>If, for instance, Empathy and Kopete have similar functionality,
+ and Empathy is running, we should prefer to send channels to it
+ rather than launching Kopete via service activation.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <method name="HandleWith" tp:name-for-bindings="Handle_With">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Called by an approver to accept a channel bundle and request that
+ the given handler be used to handle it.</p>
+
+ <p>If successful, this method will cause the ChannelDispatchOperation
+ object to disappear, emitting
+ <tp:member-ref>Finished</tp:member-ref>.</p>
+
+ <p>However, this method may fail because the dispatch has already been
+ completed and the object has already gone. If this occurs, it
+ indicates that another approver has asked for the bundle to be
+ handled by a particular handler. The approver MUST NOT attempt
+ to interact with the channels further in this case, unless it is
+ separately invoked as the handler.</p>
+
+ <p>Approvers which are also channel handlers SHOULD use
+ <tp:member-ref>Claim</tp:member-ref> instead
+ of HandleWith to request that they can handle a channel bundle
+ themselves.</p>
+
+ <p>(FIXME: list some possible errors)</p>
+
+ <p>If the channel handler raises an error from <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref>,
+ this method
+ MAY respond by raising that same error, even if it is not
+ specifically documented here.</p>
+ </tp:docstring>
+
+ <arg direction="in" type="s" tp:type="DBus_Bus_Name" name="Handler">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The well-known bus name (starting with
+ <code>org.freedesktop.Telepathy.Client.</code>) of the channel
+ handler that should handle the channel, or the empty string
+ if the client has no preferred channel handler.</p>
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ The selected handler is non-empty, but is not a syntactically
+ correct <tp:type>DBus_Bus_Name</tp:type> or does not start with
+ "<code>org.freedesktop.Telepathy.Client.</code>".
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The selected handler is temporarily unable to handle these
+ channels.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ The selected handler is syntactically correct, but will never
+ be able to handle these channels (for instance because the channels
+ do not match its HandlerChannelFilter, or because HandleChannels
+ raised NotImplemented).
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotYours">
+ <tp:docstring>
+ At the time that HandleWith was called, this dispatch operation was
+ processing an earlier call to HandleWith. The earlier call has
+ now succeeded, so some Handler nominated by another approver is
+ now responsible for the channels. In this situation, the second
+ call to HandleWith MUST NOT return until the first one has
+ returned successfully or unsuccessfully, and if the first call
+ to HandleChannels fails, the channel dispatcher SHOULD try to obey
+ the choice of Handler made by the second call to HandleWith.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="Claim" tp:name-for-bindings="Claim">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Called by an approver to claim channels for handling
+ internally. If this method is called successfully, the process
+ calling this method becomes the handler for the channel, but
+ <em>does not</em> have the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref>
+ method called on it.</p>
+
+ <p>Clients that call Claim on channels but do not immediately
+ close them SHOULD implement the Handler interface and its
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">HandledChannels</tp:dbus-ref>
+ property.</p>
+
+ <p>Approvers wishing to reject channels MUST call this method to
+ claim ownership of them, and MUST NOT call
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref>
+ on the channels unless/until this method returns successfully.</p>
+
+ <tp:rationale>
+ <p>The channel dispatcher can't know how best to close arbitrary
+ channel types, so it leaves it up to the approver to do so.
+ For instance, for Text channels it is necessary
+ to acknowledge any messages that have already been displayed to
+ the user first - ideally, the approver would display and then
+ acknowledge the messages - or to call <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel.Interface.Destroyable.Destroy</tp:dbus-ref>
+ if the destructive behaviour of that method is desired.</p>
+
+ <p>Similarly, an Approver for StreamedMedia channels can close the
+ channel with a reason (e.g. "busy") if desired. The channel
+ dispatcher, which is designed to have no specific knowledge
+ of particular channel types, can't do that.</p>
+ </tp:rationale>
+
+ <p>If successful, this method will cause the ChannelDispatchOperation
+ object to disappear, emitting
+ <tp:member-ref>Finished</tp:member-ref>, in the same way as for
+ <tp:member-ref>HandleWith</tp:member-ref>.</p>
+
+ <p>This method may fail because the dispatch operation has already
+ been completed. Again, see HandleWith for more details. The approver
+ MUST NOT attempt to interact with the channels further in this
+ case.</p>
+
+ <p>(FIXME: list some other possible errors)</p>
+ </tp:docstring>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotYours">
+ <tp:docstring>
+ At the time that Claim was called, this dispatch operation was
+ processing a call to HandleWith which has now succeeded, so
+ some Handler nominated by another approver is now responsible for
+ the channel.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="HandleWithTime" tp:name-for-bindings="Handle_With_Time">
+ <tp:added version="0.19.6">
+ At the time of writing, no released implementation of the
+ Channel Dispatcher implements this method; clients should fall
+ back to calling <tp:member-ref>HandleWith</tp:member-ref>.
+ </tp:added>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A variant of <tp:member-ref>HandleWith</tp:member-ref> allowing the
+ approver to pass an user action time. This timestamp will be passed
+ to the Handler when <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref>
+ is called.</p>
+ </tp:docstring>
+
+ <arg direction="in" type="s" tp:type="DBus_Bus_Name" name="Handler">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The well-known bus name (starting with
+ <code>org.freedesktop.Telepathy.Client.</code>) of the channel
+ handler that should handle the channel, or the empty string
+ if the client has no preferred channel handler.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" type="x" tp:type="User_Action_Timestamp" name="UserActionTime">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The time at which user action occurred.</p>
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ The selected handler is non-empty, but is not a syntactically
+ correct <tp:type>DBus_Bus_Name</tp:type> or does not start with
+ "<code>org.freedesktop.Telepathy.Client.</code>".
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The selected handler is temporarily unable to handle these
+ channels.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ The selected handler is syntactically correct, but will never
+ be able to handle these channels (for instance because the channels
+ do not match its HandlerChannelFilter, or because HandleChannels
+ raised NotImplemented).
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotYours">
+ <tp:docstring>
+ At the time that HandleWith was called, this dispatch operation was
+ processing an earlier call to HandleWith. The earlier call has
+ now succeeded, so some Handler nominated by another approver is
+ now responsible for the channels. In this situation, the second
+ call to HandleWith MUST NOT return until the first one has
+ returned successfully or unsuccessfully, and if the first call
+ to HandleChannels fails, the channel dispatcher SHOULD try to obey
+ the choice of Handler made by the second call to HandleWith.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <signal name="Finished" tp:name-for-bindings="Finished">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when this dispatch operation finishes. The dispatch
+ operation is no longer present and further methods must not be
+ called on it.</p>
+
+ <p>Approvers that have a user interface SHOULD stop notifying the user
+ about the channels in response to this signal; they MAY assume that
+ on errors, they would have received
+ <tp:member-ref>ChannelLost</tp:member-ref> first.</p>
+
+ <p>Its object path SHOULD NOT be reused for a subsequent dispatch
+ operation; the ChannelDispatcher MUST choose object paths
+ in a way that avoids immediate re-use.</p>
+
+ <tp:rationale>
+ <p>Otherwise, clients might accidentally call
+ <tp:member-ref>HandleWith</tp:member-ref> or
+ <tp:member-ref>Claim</tp:member-ref> on a new dispatch operation
+ instead of the one they intended to handle.</p>
+ </tp:rationale>
+
+ <p>This signal MUST NOT be emitted until all Approvers that were
+ invoked have returned (successfully or with an error) from
+ their <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Approver">AddDispatchOperation</tp:dbus-ref>
+ method.</p>
+
+ <tp:rationale>
+ <p>This means that Approvers can connect to the ChannelLost signal
+ in a race-free way. Non-approver processes that discover
+ a channel dispatch operation in some way (such as observers)
+ will have to follow the usual "connect to signals then recover
+ state" model - first connect to
+ <tp:member-ref>ChannelLost</tp:member-ref> and
+ Finished, then download <tp:member-ref>Channels</tp:member-ref>
+ (and on error, perhaps assume that the operation has already
+ Finished).</p>
+ </tp:rationale>
+ </tp:docstring>
+ </signal>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Dispatcher.xml b/spec/Channel_Dispatcher.xml
new file mode 100644
index 0000000..2dd000b
--- /dev/null
+++ b/spec/Channel_Dispatcher.xml
@@ -0,0 +1,595 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Dispatcher"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+
+ <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ License as published by the Free Software Foundation; either
+ version 2.1 of the License, or (at your option) any later version.</p>
+
+ <p>This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.</p>
+
+ <p>You should have received a copy of the GNU Lesser General Public
+ License along with this library; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
+ USA.</p>
+ </tp:license>
+
+ <interface name="org.freedesktop.Telepathy.ChannelDispatcher">
+ <tp:added version="0.17.26">(as a stable interface)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The channel dispatcher is responsible for responding to new
+ channels and launching client processes to handle them. It also
+ provides functionality for client processes to request that new
+ channels are created.</p>
+
+ <p>If a channel dispatcher is running, it is responsible for dispatching
+ new channels on all
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>s
+ created by the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>.
+ Connections not created by the AccountManager are outside the scope
+ of the channel dispatcher.</p>
+
+ <tp:rationale>
+ <p>Connections created by standalone Telepathy clients
+ that do not intend to interact with the channel dispatcher
+ should be ignored - otherwise, the channel dispatcher would try
+ to launch handlers for channels that the standalone client
+ was already handling internally.</p>
+ </tp:rationale>
+
+ <p>The current channel dispatcher is defined to be the process that
+ owns the well-known bus name
+ <code>org.freedesktop.Telepathy.ChannelDispatcher</code> on
+ the session bus. This process MUST export an object with this
+ interface at the object path
+ <code>/org/freedesktop/Telepathy/ChannelDispatcher</code>.</p>
+
+ <p>Until a mechanism exists for making a reasonable automatic choice
+ of ChannelDispatcher implementation, implementations SHOULD NOT
+ register as an activatable service for the ChannelDispatcher's
+ well-known bus name. Instead, it is RECOMMENDED that some component
+ of the user's session will select and activate a particular
+ implementation, and that other Telepathy-enabled programs
+ can detect whether channel request/dispatch functionality is available
+ by checking whether the ChannelDispatcher's well-known name is in use
+ at runtime.</p>
+
+ <p>There are three categories of client process defined by this
+ specification:</p>
+
+ <dl>
+ <dt><tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client">Observer</tp:dbus-ref></dt>
+ <dd><p>Observers monitor the creation of new channels. This
+ functionality can be used for things like message logging.
+ All observers are notified simultaneously.</p></dd>
+
+ <dt><tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client">Approver</tp:dbus-ref></dt>
+ <dd>
+ <p>Approvers notify the user that new channels have been created,
+ and also select which channel handler will be used for the channel,
+ either by asking the user or by choosing the most appropriate
+ channel handler.</p>
+ </dd>
+
+ <dt><tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref></dt>
+ <dd>
+ <p>Each new channel or set of channels is passed to exactly one
+ handler as its final destination. A typical channel handler is a
+ user interface process handling channels of a particular type.</p>
+ </dd>
+ </dl>
+ </tp:docstring>
+
+ <property name="Interfaces" tp:name-for-bindings="Interfaces"
+ type="as" access="read" tp:type="DBus_Interface[]">
+ <tp:docstring>
+ A list of the extra interfaces provided by this channel dispatcher.
+ </tp:docstring>
+ </property>
+
+ <method name="CreateChannel" tp:name-for-bindings="Create_Channel">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Equivalent to calling
+ <tp:member-ref>CreateChannelWithHints</tp:member-ref> with an empty
+ <var>Hints</var> parameter.</p>
+ </tp:docstring>
+
+ <arg direction="in" name="Account" type="o">
+ <tp:docstring>
+ The
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>
+ for which the new channel is to be created.
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="Requested_Properties" type="a{sv}"
+ tp:type="Qualified_Property_Value_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A dictionary containing desirable properties.</p>
+
+ <p>This parameter is used in the same way as the corresponding
+ parameter to
+ <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="User_Action_Time" type="x"
+ tp:type="User_Action_Timestamp">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The time at which user action occurred, or 0 if this channel
+ request is for some reason not involving user action.</p>
+
+ <p>This parameter is used in the same way as the corresponding
+ parameter to
+ <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="Preferred_Handler" type="s"
+ tp:type="DBus_Well_Known_Name">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Either the well-known bus name (starting with
+ <code>org.freedesktop.Telepathy.Client.</code>)
+ of the preferred handler for this
+ channel, or an empty string to indicate that any handler would be
+ acceptable.</p>
+
+ <p>This parameter is used in the same way as the corresponding
+ parameter to
+ <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p>
+ </tp:docstring>
+ <tp:changed version="0.19.0">
+ Previously, the spec didn't say that this should disregard the
+ handler's filter. This has been implemented since
+ telepathy-mission-control 5.3.2.
+ </tp:changed>
+ </arg>
+
+ <arg direction="out" name="Request" type="o">
+ <tp:docstring>
+ A
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref>
+ object.
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The Preferred_Handler is syntactically invalid or does
+ not start with <code>org.freedesktop.Telepathy.Client.</code>,
+ the Account does not exist, or one of the Requested_Properties
+ is invalid
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+
+ </method>
+
+ <method name="EnsureChannel" tp:name-for-bindings="Ensure_Channel">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Equivalent to calling
+ <tp:member-ref>EnsureChannelWithHints</tp:member-ref> with an empty
+ <var>Hints</var> parameter.</p>
+ </tp:docstring>
+
+ <arg direction="in" name="Account" type="o">
+ <tp:docstring>
+ The
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>
+ for which the new channel is to be created.
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="Requested_Properties" type="a{sv}"
+ tp:type="Qualified_Property_Value_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A dictionary containing desirable properties.</p>
+
+ <p>This parameter is used in the same way as the corresponding
+ parameter to
+ <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="User_Action_Time" type="x"
+ tp:type="User_Action_Timestamp">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The time at which user action occurred, or 0 if this channel
+ request is for some reason not involving user action.</p>
+
+ <p>This parameter is used in the same way as the corresponding
+ parameter to
+ <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="Preferred_Handler" type="s"
+ tp:type="DBus_Well_Known_Name">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Either the well-known bus name (starting with
+ <code>org.freedesktop.Telepathy.Client.</code>)
+ of the preferred handler for this
+ channel, or an empty string to indicate that any handler would be
+ acceptable. The behaviour and rationale are the same as for the
+ corresponding parameter to
+ <tp:member-ref>EnsureChannelWithHints</tp:member-ref>.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="out" name="Request" type="o">
+ <tp:docstring>
+ A
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref>
+ object.
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The Preferred_Handler is syntactically invalid or does
+ not start with <code>org.freedesktop.Telepathy.Client.</code>,
+ the Account does not exist, or one of the Requested_Properties
+ is invalid
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+
+ </method>
+
+ <method name="CreateChannelWithHints"
+ tp:name-for-bindings="Create_Channel_With_Hints">
+ <tp:added version="0.21.5">
+ Support for this method is indicated by the
+ <tp:member-ref>SupportsRequestHints</tp:member-ref> property.
+ Clients MUST recover from this method being unsupported by falling back
+ to <tp:dbus-ref
+ namespace="ofdT.ChannelDispatcher">CreateChannel</tp:dbus-ref>.
+ </tp:added>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Start a request to create a channel. This initially just creates a
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref>
+ object, which can be used to continue the request and track its
+ success or failure.</p>
+
+ <tp:rationale>
+ <p>The request can take a long time - in the worst case, the
+ channel dispatcher has to ask the account manager to put the
+ account online, the account manager has to ask the operating
+ system to obtain an Internet connection, and the operating
+ system has to ask the user whether to activate an Internet
+ connection using an on-demand mechanism like dialup.</p>
+
+ <p>This means that using a single D-Bus method call and response
+ to represent the whole request will tend to lead to that call
+ timing out, which is not the behaviour we want.</p>
+ </tp:rationale>
+
+ <p>If this method is called for an Account that is disabled, invalid
+ or otherwise unusable, no error is signalled until
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ChannelRequest.Proceed</tp:dbus-ref>
+ is called, at which point
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ChannelRequest.Failed</tp:dbus-ref>
+ is emitted with an appropriate error.</p>
+
+ <tp:rationale>
+ <p>This means there's only one code path for errors, apart from
+ InvalidArgument for "that request makes no sense".</p>
+
+ <p>It also means that the request will proceed if the account is
+ enabled after calling CreateChannel, but before calling
+ Proceed.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg direction="in" name="Account" type="o">
+ <tp:docstring>
+ The
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>
+ for which the new channel is to be created.
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="Requested_Properties" type="a{sv}"
+ tp:type="Qualified_Property_Value_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A dictionary containing desirable properties. This has the same
+ semantics as the corresponding parameter to
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>.
+ </p>
+
+ <p>Certain properties will not necessarily make sense in this
+ dictionary: for instance,
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>
+ can only be given if the requester is able to interact with a
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>
+ to the desired account.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="User_Action_Time" type="x"
+ tp:type="User_Action_Timestamp">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The time at which user action occurred, or 0 if this channel
+ request is for some reason not involving user action.
+ The <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.ChannelRequest">UserActionTime</tp:dbus-ref>
+ property will be set to this value, and it will eventually be
+ passed as the <code>User_Action_Time</code> parameter of <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref>.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="Preferred_Handler" type="s"
+ tp:type="DBus_Well_Known_Name">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Either the well-known bus name (starting with
+ <code>org.freedesktop.Telepathy.Client.</code>)
+ of the preferred handler for this
+ channel, or an empty string to indicate that any handler would be
+ acceptable. The channel dispatcher SHOULD dispatch as many as
+ possible of the resulting channels (ideally, all of them)
+ to that handler—irrespective of whether that handler's <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">HandlerChannelFilter</tp:dbus-ref>
+ matches the channel—and SHOULD remember the preferred handler
+ so it can try to dispatch subsequent channels in the same bundle
+ to the same handler.</p>
+
+ <tp:rationale>
+ <p>This must be the well-known bus name, not the unique name,
+ to ensure that all handlers do indeed have the Client API,
+ and the Client object on the handler can be located easily.</p>
+
+ <p>This is partly so the channel dispatcher can call
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">HandleChannels</tp:dbus-ref>
+ on it, and partly so the channel dispatcher
+ can recover state if it crashes and is restarted.</p>
+
+ <p>The filter should be disregarded for ease of use of this
+ interface: clients will usually use this argument to request
+ channels be sent to themself, and this should trump the filter
+ not matching. This also allows a client to become the handler
+ for a channel produced by one of its own requests, while not
+ being a candidate to handle other channels of that type.</p>
+ </tp:rationale>
+
+ <p>If this is a well-known bus name and the handler has the
+ Requests interface, the channel dispatcher SHOULD
+ call <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Interface.Requests">AddRequest</tp:dbus-ref>
+ on that Handler after this method has returned.</p>
+
+ <tp:rationale>
+ <p>This ordering allows a Handler which calls CreateChannel with
+ itself as the preferred handler to associate the call to
+ AddRequest with that call.</p>
+ </tp:rationale>
+
+ <p>This is copied to the ChannelRequest that is returned,
+ as the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.ChannelRequest">PreferredHandler</tp:dbus-ref>
+ property.</p>
+ </tp:docstring>
+
+ <tp:changed version="0.19.0">
+ Previously, the spec didn't say that this should disregard the
+ handler's filter. This has been implemented since
+ telepathy-mission-control 5.3.2.
+ </tp:changed>
+ </arg>
+
+ <arg direction="in" name="Hints" type="a{sv}">
+ <tp:docstring>
+ <p>Additional information about the channel request, which will be
+ used as the value for the resulting request's <tp:dbus-ref
+ namespace="ofdT.ChannelRequest">Hints</tp:dbus-ref>
+ property.</p>
+
+ <tp:rationale>
+ <p>See the Hints property's documentation for rationale.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="out" name="Request" type="o">
+ <tp:docstring>
+ A
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref>
+ object.
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The Preferred_Handler is syntactically invalid or does
+ not start with <code>org.freedesktop.Telepathy.Client.</code>,
+ the Account does not exist, or one of the Requested_Properties
+ is invalid
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+
+ </method>
+
+ <method name="EnsureChannelWithHints"
+ tp:name-for-bindings="Ensure_Channel_With_Hints">
+ <tp:added version="0.21.5">
+ Support for this method is indicated by the
+ <tp:member-ref>SupportsRequestHints</tp:member-ref> property.
+ Clients MUST recover from this method being unsupported by falling back
+ to <tp:dbus-ref
+ namespace="ofdT.ChannelDispatcher">EnsureChannel</tp:dbus-ref>.
+ </tp:added>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Start a request to ensure that a channel exists, creating it if
+ necessary. This initially just creates a <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref>
+ object, which can be used to continue the request and track its
+ success or failure.</p>
+
+ <p>If this method is called for an Account that is disabled, invalid
+ or otherwise unusable, no error is signalled until
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ChannelRequest.Proceed</tp:dbus-ref>
+ is called, at which point
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ChannelRequest.Failed</tp:dbus-ref>
+ is emitted with an appropriate error.</p>
+
+ <tp:rationale>
+ <p>The rationale is as for <tp:dbus-ref
+ namespace='org.freedesktop.Telepathy.ChannelDispatcher'>CreateChannelWithHints</tp:dbus-ref>.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg direction="in" name="Account" type="o">
+ <tp:docstring>
+ The
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>
+ for which the new channel is to be created.
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="Requested_Properties" type="a{sv}"
+ tp:type="Qualified_Property_Value_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A dictionary containing desirable properties. This has the same
+ semantics as the corresponding parameter to
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.EnsureChannel</tp:dbus-ref>.
+ </p>
+
+ <p>Certain properties will not necessarily make sense in this
+ dictionary: for instance,
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>
+ can only be given if the requester is able to interact with a
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>
+ to the desired account.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="User_Action_Time" type="x"
+ tp:type="User_Action_Timestamp">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The time at which user action occurred, or 0 if this channel
+ request is for some reason not involving user action.</p>
+
+ <p>This parameter is used in the same way as the corresponding
+ parameter to
+ <tp:member-ref>CreateChannelWithHints</tp:member-ref>.</p>
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="Preferred_Handler" type="s"
+ tp:type="DBus_Well_Known_Name">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Either the well-known bus name (starting with
+ <code>org.freedesktop.Telepathy.Client.</code>)
+ of the preferred handler for this
+ channel, or an empty string to indicate that any handler would be
+ acceptable. The behaviour and rationale are the same as for the
+ corresponding parameter to
+ <tp:member-ref>CreateChannelWithHints</tp:member-ref>, except
+ as noted here.</p>
+
+ <p>If any new channels are created in response to this
+ request, the channel dispatcher SHOULD dispatch as many as
+ possible of the resulting channels (ideally, all of them)
+ to that handler, and SHOULD remember the preferred handler
+ so it can try to dispatch subsequent channels in the same bundle
+ to the same handler. If the requested channel already exists (that
+ is, <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.EnsureChannel</tp:dbus-ref>
+ returns <code>Yours=False</code>) then the channel dispatcher
+ SHOULD re-dispatch the channel to its existing handler, and MUST
+ NOT dispatch it to this client (unless it is the existing handler);
+ the request is still deemed to have succeeded in this case.</p>
+
+ <tp:rationale>
+ <p>An address book application, for example, might call <tp:dbus-ref
+ namespace='org.freedesktop.Telepathy.ChannelDispatcher'>EnsureChannel</tp:dbus-ref>
+ to ensure that a text channel with a particular contact is
+ displayed to the user; it does not care whether a new channel was
+ made. An IM client might call <tp:dbus-ref
+ namespace='org.freedesktop.Telepathy.ChannelDispatcher'>EnsureChannel</tp:dbus-ref>
+ in response to the user double-clicking an entry in the contact
+ list, with itself as the <code>Preferred_Handler</code>; if the
+ user already has a conversation with that contact in another
+ application, they would expect the existing window to be
+ presented, rather than their double-click leading to an error
+ message. So the request should succeed, even if its
+ <code>Preferred_Handler</code> is not used.</p>
+ </tp:rationale>
+
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" name="Hints" type="a{sv}">
+ <tp:docstring>
+ Additional information about the channel request, which will be used
+ as the value for the resulting request's <tp:dbus-ref
+ namespace="ofdT.ChannelRequest">Hints</tp:dbus-ref>
+ property.</tp:docstring>
+ </arg>
+
+ <arg direction="out" name="Request" type="o">
+ <tp:docstring>
+ A
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest</tp:dbus-ref>
+ object.
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The Preferred_Handler is syntactically invalid or does
+ not start with <code>org.freedesktop.Telepathy.Client.</code>,
+ the Account does not exist, or one of the Requested_Properties
+ is invalid
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+
+ </method>
+
+ <property name="SupportsRequestHints"
+ tp:name-for-bindings="Supports_Request_Hints"
+ type="b" access="read">
+ <tp:added version="0.21.5"/>
+ <tp:docstring>
+ If <code>True</code>, the channel dispatcher is new enough to support
+ <tp:member-ref>CreateChannelWithHints</tp:member-ref> and
+ <tp:member-ref>EnsureChannelWithHints</tp:member-ref>, in addition
+ to the older <tp:dbus-ref
+ namespace="ofdT.ChannelDispatcher">CreateChannel</tp:dbus-ref>
+ and <tp:dbus-ref
+ namespace="ofdT.ChannelDispatcher">EnsureChannel</tp:dbus-ref>
+ methods, and also new enough to emit <tp:dbus-ref
+ namespace="ofdT.ChannelRequest">SucceededWithChannel</tp:dbus-ref>
+ before the older <tp:dbus-ref
+ namespace="ofdT.ChannelRequest">Succeeded</tp:dbus-ref> signal.
+ If <code>False</code> or missing, only the metadata-less
+ variants are supported.
+ </tp:docstring>
+ </property>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Dispatcher_Interface_Operation_List.xml b/spec/Channel_Dispatcher_Interface_Operation_List.xml
new file mode 100644
index 0000000..be06f5c
--- /dev/null
+++ b/spec/Channel_Dispatcher_Interface_Operation_List.xml
@@ -0,0 +1,140 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Dispatcher_Interface_Operation_List"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+
+ <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ License as published by the Free Software Foundation; either
+ version 2.1 of the License, or (at your option) any later version.</p>
+
+ <p>This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.</p>
+
+ <p>You should have received a copy of the GNU Lesser General Public
+ License along with this library; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
+ USA.</p>
+ </tp:license>
+
+ <interface name="org.freedesktop.Telepathy.ChannelDispatcher.Interface.OperationList">
+ <tp:added version="0.17.26">(as a stable interface)</tp:added>
+
+ <tp:requires interface="org.freedesktop.Telepathy.ChannelDispatcher"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This interface allows users of the ChannelDispatcher to enumerate
+ all the pending dispatch operations, with change notification.</p>
+
+ <tp:rationale>
+ <p>The existence of the
+ <tp:member-ref>DispatchOperations</tp:member-ref> property allows a
+ newly started approver to pick up existing dispatch operations.</p>
+
+ <p>This is on a separate interface so clients that aren't interested
+ in doing this aren't woken up by its signals.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <tp:struct name="Dispatch_Operation_Details"
+ array-name="Dispatch_Operation_Details_List">
+
+ <tp:docstring>
+ Details of a channel dispatch operation.
+ </tp:docstring>
+
+ <tp:member name="Channel_Dispatch_Operation" type="o">
+ <tp:docstring>
+ The object path of the
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ChannelDispatchOperation</tp:dbus-ref>.
+ </tp:docstring>
+ </tp:member>
+
+ <tp:member name="Properties" type="a{sv}"
+ tp:type="Qualified_Property_Value_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Properties of the channel dispatch operation.</p>
+
+ <p>Connection managers MUST NOT include properties in this mapping
+ if their values can change. Clients MUST ignore properties
+ that appear in this mapping if their values can change.</p>
+
+ <tp:rationale>
+ <p>The rationale is the same as for
+ <tp:type>Channel_Details</tp:type>.</p>
+ </tp:rationale>
+
+ <p>Each dictionary MUST contain at least the following keys:</p>
+ <ul>
+ <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.Interfaces</tp:dbus-ref></li>
+ <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.Connection</tp:dbus-ref></li>
+ <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.Account</tp:dbus-ref></li>
+ <li><tp:dbus-ref>org.freedesktop.Telepathy.ChannelDispatchOperation.PossibleHandlers</tp:dbus-ref></li>
+ </ul>
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <property
+ name="DispatchOperations" tp:name-for-bindings="Dispatch_Operations"
+ type="a(oa{sv})" tp:type="Dispatch_Operation_Details[]" access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The list of ChannelDispatchOperation objects currently being
+ processed. Change notification is via the
+ <tp:member-ref>NewDispatchOperation</tp:member-ref> and
+ <tp:member-ref>DispatchOperationFinished</tp:member-ref> signals.</p>
+ </tp:docstring>
+ </property>
+
+ <signal name="NewDispatchOperation"
+ tp:name-for-bindings="New_Dispatch_Operation">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when a dispatch operation is added to
+ <tp:member-ref>DispatchOperations</tp:member-ref>.</p>
+ </tp:docstring>
+
+ <arg name="Dispatch_Operation" type="o">
+ <tp:docstring>
+ The dispatch operation that was created.
+ </tp:docstring>
+ </arg>
+
+ <arg name="Properties"
+ type="a{sv}" tp:type="Qualified_Property_Value_Map">
+ <tp:docstring>
+ The same properties that would appear in the Properties member of
+ <tp:type>Dispatch_Operation_Details</tp:type>.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <signal name="DispatchOperationFinished"
+ tp:name-for-bindings="Dispatch_Operation_Finished">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ Emitted when a dispatch operation finishes (i.e. exactly once per
+ emission of <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">ChannelDispatchOperation.Finished</tp:dbus-ref>).
+
+ <tp:rationale>
+ Strictly speaking this is redundant with
+ ChannelDispatchOperation.Finished, but it provides full
+ change-notification for the
+ <tp:member-ref>DispatchOperations</tp:member-ref> property.
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg name="Dispatch_Operation" type="o">
+ <tp:docstring>
+ The dispatch operation that was closed.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Future.xml b/spec/Channel_Future.xml
new file mode 100644
index 0000000..5bbca17
--- /dev/null
+++ b/spec/Channel_Future.xml
@@ -0,0 +1,68 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Future"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.</p>
+
+<p>This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+Lesser General Public License for more details.</p>
+
+<p>You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
+ </tp:license>
+ <interface name="org.freedesktop.Telepathy.Channel.FUTURE"
+ tp:causes-havoc="a staging area for future Channel functionality">
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This interface contains functionality which we intend to incorporate
+ into the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref> interface
+ in future. It should be considered to
+ be conceptually part of the core Channel interface, but without
+ API or ABI guarantees.</p>
+
+ <tp:rationale>
+ <p>If we add new functionality to the Channel interface, libraries
+ that use generated code (notably telepathy-glib) will have it as
+ part of their ABI forever, meaning we can't make incompatible
+ changes. By using this interface as a staging area for future
+ Channel functionality, we can try out new properties, signals
+ and methods as application-specific extensions, then merge them
+ into the core Channel interface when we have enough implementation
+ experience to declare them to be stable.</p>
+
+ <p>The name is by analogy to Python's <code>__future__</code>
+ pseudo-module.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <property name="Bundle" tp:name-for-bindings="Bundle"
+ type="o" access="read">
+ <tp:added version="0.17.9">(in Channel.FUTURE
+ pseudo-interface)</tp:added>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelBundle.DRAFT</tp:dbus-ref>
+ to which this channel belongs.</p>
+
+ <p>A channel's Bundle property can never change.</p>
+
+ <p>Older connection managers might not have this property. Clients
+ (particularly the channel dispatcher) SHOULD recover by considering
+ each channel to be in a bundle containing only that channel,
+ distinct from all other bundles, which has no additional
+ interfaces.</p>
+ </tp:docstring>
+ </property>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Handler.xml b/spec/Channel_Handler.xml
new file mode 100644
index 0000000..edf975e
--- /dev/null
+++ b/spec/Channel_Handler.xml
@@ -0,0 +1,78 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Handler" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright (C) 2007-2008 Collabora Limited</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.</p>
+
+<p>This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+Lesser General Public License for more details.</p>
+
+<p>You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
+ </tp:license>
+ <interface name="org.freedesktop.Telepathy.ChannelHandler">
+ <tp:deprecated version="0.17.23">
+ Clients should implement <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Client.Handler</tp:dbus-ref>
+ instead.
+ </tp:deprecated>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface exported by Mission Control 4 client applications which
+ are able to handle incoming channels.</p>
+ </tp:docstring>
+ <tp:added version="0.17.0"/>
+
+ <method name="HandleChannel" tp:name-for-bindings="Handle_Channel">
+ <tp:docstring>
+ Called when a channel handler should handle a new channel.
+ </tp:docstring>
+ <tp:added version="0.17.0"/>
+
+ <arg direction="in" type="s" name="Bus_Name" tp:type="DBus_Bus_Name">
+ <tp:docstring>
+ The bus name of the connection and channel
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" type="o" name="Connection">
+ <tp:docstring>
+ The object-path of the connection that owns the channel
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" type="s" tp:type="DBus_Interface" name="Channel_Type">
+ <tp:docstring>
+ The channel type
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" type="o" name="Channel">
+ <tp:docstring>
+ The object-path of the channel
+ </tp:docstring>
+ </arg>
+
+ <arg direction="in" type="u" tp:type="Handle_Type" name="Handle_Type">
+ <tp:docstring>The type of the handle that the channel communicates
+ with, or 0 if there is no associated handle</tp:docstring>
+ </arg>
+
+ <arg direction="in" type="u" tp:type="Handle" name="Handle">
+ <tp:docstring>The handle that the channel communicates with,
+ or 0 if there is no associated handle</tp:docstring>
+ </arg>
+
+ <!-- FIXME: possible errors? -->
+ </method>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
+
diff --git a/spec/Channel_Interface_Addressing.xml b/spec/Channel_Interface_Addressing.xml
new file mode 100644
index 0000000..494fd7b
--- /dev/null
+++ b/spec/Channel_Interface_Addressing.xml
@@ -0,0 +1,107 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Addressing" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2010 Collabora Limited</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.</p>
+
+<p>This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+Lesser General Public License for more details.</p>
+
+<p>You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
+ </tp:license>
+ <interface name="org.freedesktop.Telepathy.Channel.Interface.Addressing.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.19.12">(as draft)</tp:added>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This interface provides properties that can be used for
+ requesting channels through different contact addressing
+ schemes like vCard addresses or URIs.
+ </p>
+ </tp:docstring>
+
+ <property name="TargetVCardField" type="s" access="read"
+ tp:name-for-bindings="Target_VCard_Field">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The vCard field, normalized to lower case,
+ <tp:member-ref>TargetVCardAddress</tp:member-ref> refers to.</p>
+
+ <p>The <code>url</code> vCard field MUST NOT appear here; see
+ <tp:member-ref>TargetURI</tp:member-ref> instead.</p>
+
+ <tp:rationale>
+ <p>In practice, protocols have a limited set of URI
+ schemes that make sense to resolve as a contact.</p>
+ </tp:rationale>
+
+ <p>If this is omitted from a request,
+ <tp:member-ref>TargetVCardAddress</tp:member-ref> MUST be
+ omitted as well.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="TargetURIScheme" type="s" access="read"
+ tp:name-for-bindings="Target_URI_Scheme">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The URI scheme used in <tp:member-ref>TargetURI</tp:member-ref></p>
+
+ <tp:rationale>
+ <p>While this seems redundant, since the scheme is included in
+ <tp:member-ref>TargetURI</tp:member-ref>, it exists for constructing
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref>
+ that support a limited set of URI schemes.</p>
+ </tp:rationale>
+
+ <p>If this is omitted from a request,
+ <tp:member-ref>TargetURI</tp:member-ref> MUST be
+ omitted as well.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="TargetVCardAddress" type="s" access="read"
+ tp:name-for-bindings="Target_VCard_Address">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The vCard address of the Channel's target.</p>
+
+ <p>If this is present in a channel request,
+ <tp:member-ref>TargetVCardField</tp:member-ref>
+ MUST be present, and
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>,
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>,
+ and <tp:member-ref>TargetURI</tp:member-ref> MUST NOT be present.
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
+ must either not be present or set to Handle_Type_Contact.
+ The request MUST fail with error InvalidHandle, without
+ side-effects, if the requested vCard address cannot be found.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="TargetURI" type="s" access="read"
+ tp:name-for-bindings="Target_URI">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The URI of the Channel's target. The URI's scheme (i.e. the
+ part before the first colon) MUST be identical to
+ <tp:member-ref>TargetURIScheme</tp:member-ref>.</p>
+
+ <p>If this is present in a channel request,
+ <tp:member-ref>TargetVCardField</tp:member-ref>
+ MUST be present, and
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandle</tp:dbus-ref>,
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>,
+ and <tp:member-ref>TargetVCardAddress</tp:member-ref> MUST NOT be
+ present.
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>
+ must either not be present or set to Handle_Type_Contact.
+ The request MUST fail with error InvalidHandle, without
+ side-effects, if the requested vCard address cannot be found.</p>
+ </tp:docstring>
+ </property>
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Interface_Anonymity.xml b/spec/Channel_Interface_Anonymity.xml
new file mode 100644
index 0000000..ef3a3b8
--- /dev/null
+++ b/spec/Channel_Interface_Anonymity.xml
@@ -0,0 +1,68 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Anonymity"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+
+ <tp:copyright>Copyright © 2008-2010 Nokia Corporation</tp:copyright>
+ <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ License as published by the Free Software Foundation; either
+ version 2.1 of the License, or (at your option) any later version.</p>
+
+ <p>This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.</p>
+
+ <p>You should have received a copy of the GNU Lesser General Public
+ License along with this library; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+ 02110-1301, USA.</p>
+ </tp:license>
+
+ <interface name="org.freedesktop.Telepathy.Channel.Interface.Anonymity">
+ <tp:added version="0.19.7">(as stable API)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Interface for requesting the anonymity modes of a channel
+ (as defined in <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+ >Connection.Interface.Anonymity</tp:dbus-ref>).</p>
+ </tp:docstring>
+
+ <property name="AnonymityModes" type="u" tp:type="Anonymity_Mode_Flags"
+ access="read" tp:name-for-bindings="Anonymity_Modes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ The list of initially requested anonymity modes on the channel. This
+ MUST NOT change, and is Requestable.
+ </tp:docstring>
+ </property>
+
+ <property name="AnonymityMandatory" type="b" access="read"
+ tp:name-for-bindings="Anonymity_Mandatory">
+ <tp:docstring>
+ Whether or not the anonymity settings are required for this channel.
+ This MUST NOT change, and is Requestable.
+ </tp:docstring>
+ </property>
+
+ <property name="AnonymousID" type="s" access="read"
+ tp:name-for-bindings="Anonymous_ID">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This is the ID that the remote user of the channel MAY see
+ (assuming there's a single ID). For example, for SIP connections
+ where the From address has been scrambled by the CM, the scrambled
+ address would be available here for the client to see. This is
+ completely optional, and MAY be an empty string ("") in
+ cases where anonymity modes are not set, or the CM doesn't know
+ what the remote contact will see, or any other case where this
+ doesn't make sense.</p>
+
+ <p>This MAY change over the lifetime of the channel, and SHOULD NOT
+ be used with the Request interface.</p>
+ </tp:docstring>
+ </property>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Interface_Call_State.xml b/spec/Channel_Interface_Call_State.xml
new file mode 100644
index 0000000..b0aea59
--- /dev/null
+++ b/spec/Channel_Interface_Call_State.xml
@@ -0,0 +1,147 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Call_State" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright> Copyright (C) 2008 Collabora Limited </tp:copyright>
+ <tp:copyright> Copyright (C) 2008 Nokia Corporation </tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.</p>
+
+<p>This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+Lesser General Public License for more details.</p>
+
+<p>You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
+ </tp:license>
+ <interface name="org.freedesktop.Telepathy.Channel.Interface.CallState">
+ <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface for streamed media channels that can indicate call
+ progress or call states. The presence of this interface is no guarantee
+ that call states will actually be signalled (for instance, SIP
+ implementations are not guaranteed to generate status 180 Ringing, so a
+ call can be accepted without the Ringing flag ever having been set;
+ similarly, Jingle implementations are not guaranteed to send
+ <code>&lt;ringing/&gt;</code>).</p>
+
+ <p>To notify the other participant in the call that they are on hold,
+ see <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface"
+ >Hold</tp:dbus-ref>.</p>
+ </tp:docstring>
+ <tp:added version="0.17.2"/>
+
+ <method name="GetCallStates" tp:name-for-bindings="Get_Call_States">
+ <tp:docstring>
+ Get the current call states for all contacts involved in this call.
+ </tp:docstring>
+
+ <arg tp:type="Channel_Call_State_Map" name="States" direction="out"
+ type="a{uu}">
+ <tp:docstring>
+ The current call states. Participants where the call state flags
+ would be 0 (all unset) may be omitted from this mapping.
+ </tp:docstring>
+ </arg>
+ </method>
+
+ <signal name="CallStateChanged" tp:name-for-bindings="Call_State_Changed">
+ <tp:docstring>
+ Emitted when the state of a member of the channel has changed.
+ </tp:docstring>
+
+ <arg name="Contact" type="u" tp:type="Contact_Handle">
+ <tp:docstring>
+ An integer handle for the contact.
+ </tp:docstring>
+ </arg>
+
+ <arg name="State" type="u" tp:type="Channel_Call_State_Flags">
+ <tp:docstring>
+ The new state for this contact.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <tp:mapping name="Channel_Call_State_Map">
+ <tp:docstring>
+ A map from contacts to call states.
+ </tp:docstring>
+
+ <tp:member name="Contact" type="u" tp:type="Contact_Handle">
+ <tp:docstring>A contact involved in this call.</tp:docstring>
+ </tp:member>
+
+ <tp:member name="State" type="u" tp:type="Channel_Call_State_Flags">
+ <tp:docstring>State flags for the given contact.</tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <tp:flags name="Channel_Call_State_Flags" value-prefix="Channel_Call_State" type="u">
+ <tp:docstring>
+ A set of flags representing call states.
+ </tp:docstring>
+
+ <tp:flag suffix="Ringing" value="1">
+ <tp:docstring>
+ The contact has been alerted about the call but has not responded
+ (e.g. 180 Ringing in SIP).
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="Queued" value="2">
+ <tp:docstring>
+ The contact is temporarily unavailable, and the call has been placed
+ in a queue (e.g. 182 Queued in SIP, or call-waiting in telephony).
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="Held" value="4">
+ <tp:docstring>
+ The contact has placed the call on hold, and will not receive
+ media from the local user or any other participants until they
+ unhold the call again.
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="Forwarded" value="8">
+ <tp:docstring>
+ The initiator of the call originally called a contact other than the
+ current recipient of the call, but the call was then forwarded or
+ diverted.
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="In_Progress" value="16">
+ <tp:docstring>
+ Progress has been made in placing the outgoing call, but the
+ destination contact may not have been made aware of the call yet
+ (so the Ringing state is not appropriate). This corresponds to SIP's
+ status code 183 Session Progress, and could be used when the
+ outgoing call has reached a gateway, for instance.
+ </tp:docstring>
+ </tp:flag>
+
+ <tp:flag suffix="Conference_Host" value="32">
+ <tp:added version='0.19.11'/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ This contact has merged this call into a conference. Note that GSM
+ provides a notification when the remote party merges a call into a
+ conference, but not when it is split out again; thus, this flag can
+ only indicate that the call has been part of a conference at some
+ point. If a GSM connection manager receives a notification that a
+ call has been merged into a conference a second time, it SHOULD
+ represent this by clearing and immediately re-setting this flag on
+ the remote contact.
+ </tp:docstring>
+ </tp:flag>
+ </tp:flags>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Interface_Chat_State.xml b/spec/Channel_Interface_Chat_State.xml
new file mode 100644
index 0000000..27515d2
--- /dev/null
+++ b/spec/Channel_Interface_Chat_State.xml
@@ -0,0 +1,144 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Chat_State" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright> Copyright (C) 2007 Collabora Limited </tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.</p>
+
+<p>This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+Lesser General Public License for more details.</p>
+
+<p>You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
+ </tp:license>
+ <interface name="org.freedesktop.Telepathy.Channel.Interface.ChatState">
+ <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Text"/>
+
+ <tp:mapping name="Chat_State_Map">
+ <tp:added version="0.19.7"/>
+ <tp:docstring>A map from contacts to their chat states.</tp:docstring>
+ <tp:member name="Contact" type="u" tp:type="Contact_Handle">
+ <tp:docstring>A contact</tp:docstring>
+ </tp:member>
+ <tp:member name="State" type="u" tp:type="Channel_Chat_State">
+ <tp:docstring>The contact's chat state</tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <property name="ChatStates" tp:name-for-bindings="Chat_States"
+ access="read" type="a{uu}" tp:type="Chat_State_Map">
+ <tp:added version="0.19.7"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A map containing the chat states of all contacts in this
+ channel whose chat state is not Inactive.</p>
+
+ <p>Contacts in this channel, but who are not listed in this map,
+ may be assumed to be in the Inactive state.</p>
+
+ <p>In implementations that do not have this property, its value may be
+ assumed to be empty until a
+ <tp:member-ref>ChatStateChanged</tp:member-ref> signal indicates
+ otherwise.</p>
+
+ <tp:rationale>
+ <p>This property was not present in older versions of telepathy-spec,
+ because chat states in XMPP are not state-recoverable (if you
+ miss the change notification signal, there's no way to know the
+ state). However, this property still allows clients to recover
+ state changes that were seen by the CM before the client started
+ to deal with the channel.</p>
+
+ <p>In CMs that follow older spec versions, assuming Inactive will
+ mean that initial chat states will always be assumed to be
+ Inactive, which is the best we can do. XEP 0085 specifies
+ Inactive as the "neutral" state to be assumed unless told
+ otherwise.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <method name="SetChatState" tp:name-for-bindings="Set_Chat_State">
+ <arg direction="in" name="State" type="u" tp:type="Channel_Chat_State">
+ <tp:docstring>
+ The new state.
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Set the local state and notify other members of the channel that it
+ has changed.
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
+ </tp:possible-errors>
+ </method>
+ <signal name="ChatStateChanged" tp:name-for-bindings="Chat_State_Changed">
+ <arg name="Contact" type="u" tp:type="Contact_Handle">
+ <tp:docstring>
+ An integer handle for the contact.
+ </tp:docstring>
+ </arg>
+ <arg name="State" type="u" tp:type="Channel_Chat_State">
+ <tp:docstring>
+ The new state of this contact.
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Emitted when the state of a member of the channel has changed.
+ This includes local state.
+ </tp:docstring>
+ </signal>
+ <tp:enum name="Channel_Chat_State" type="u">
+ <tp:enumvalue suffix="Gone" value="0">
+ <tp:docstring>
+ The contact has effectively ceased participating in the chat.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Inactive" value="1">
+ <tp:docstring>
+ The contact has not been active for some time.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Active" value="2">
+ <tp:docstring>
+ The contact is actively participating in the chat.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Paused" value="3">
+ <tp:docstring>
+ The contact has paused composing a message.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Composing" value="4">
+ <tp:docstring>
+ The contact is composing a message to be sent to the chat.
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface for channels for receiving notifications of remote contacts'
+ state, and for notifying remote contacts of the local state.</p>
+
+ <p>Clients should assume that a contact's state is Channel_Chat_State_Inactive
+ unless they receive a notification otherwise.</p>
+
+ <p>The Channel_Chat_State_Gone state is treated differently to other states:</p>
+ <ul>
+ <li>It may not be used for multi-user chats</li>
+ <li>It may not be explicitly sent</li>
+ <li>It should be automatically sent when the channel is closed</li>
+ <li>It must not be sent to the peer if a channel is closed without being used</li>
+ <li>Receiving it must not cause a new channel to be opened</li>
+ </ul>
+
+ <p>The different states are defined by XEP-0085, but may be applied to any suitable protocol.</p>
+ </tp:docstring>
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Interface_Conference.xml b/spec/Channel_Interface_Conference.xml
new file mode 100644
index 0000000..abda59e
--- /dev/null
+++ b/spec/Channel_Interface_Conference.xml
@@ -0,0 +1,628 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Conference"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2009 Collabora Limited</tp:copyright>
+ <tp:copyright>Copyright © 2009 Nokia Corporation</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ License as published by the Free Software Foundation; either
+ version 2.1 of the License, or (at your option) any later version.</p>
+
+ <p>This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.</p>
+
+ <p>You should have received a copy of the GNU Lesser General Public
+ License along with this library; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+ 02110-1301, USA.</p>
+ </tp:license>
+ <interface
+ name="org.freedesktop.Telepathy.Channel.Interface.Conference">
+ <tp:added version="0.19.13">(as stable API)</tp:added>
+ <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+ <tp:requires
+ interface="org.freedesktop.Telepathy.Channel.Interface.Group"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface for multi-user conference channels that can "continue
+ from" one or more individual channels. This could be used to invite
+ other contacts to an existing 1-1 text conversation, combine two phone
+ calls into one conference call, and so on, with roughly the same API in
+ each case.</p>
+
+ <tp:rationale>
+ <p>This interface addresses freedesktop.org <a
+ href="http://bugs.freedesktop.org/show_bug.cgi?id=24906">bug
+ #24906</a> (GSM-compatible conference calls) and <a
+ href="http://bugs.freedesktop.org/show_bug.cgi?id=24939">bug
+ #24939</a> (upgrading calls and chats to multi-user).
+ See those bugs for more rationale and use cases.</p>
+ </tp:rationale>
+
+ <p>Existing channels are upgraded by requesting a new channel of the same
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>,
+ listing the channels to be merged into the new conference in the
+ <tp:member-ref>InitialChannels</tp:member-ref> property of the request.
+ If <tp:member-ref>InitialInviteeHandles</tp:member-ref> and
+ <tp:member-ref>InitialInviteeIDs</tp:member-ref> are
+ <var>Allowed_Properties</var> in <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">RequestableChannelClasses</tp:dbus-ref>,
+ ad-hoc conferences to a set of contacts may be created by requesting a
+ channel, specifying
+ <tp:member-ref>InitialInviteeHandles</tp:member-ref> and/or
+ <tp:member-ref>InitialInviteeIDs</tp:member-ref> to be the contacts in
+ question. A request may specify these alongside
+ <tp:member-ref>InitialChannels</tp:member-ref>, to simultaneously
+ upgrade a channel to a conference and invite others to join it.</p>
+
+ <p>Channels with this interface MAY also implement <tp:dbus-ref
+ namespace='ofdT.Channel.Interface'>MergeableConference.DRAFT</tp:dbus-ref>
+ to support merging more 1-1 channels into an ongoing conference.
+ Similarly, 1-1 channels MAY implement <tp:dbus-ref
+ namespace='ofdT.Channel.Interface'>Splittable.DRAFT</tp:dbus-ref> to
+ support being broken out of a Conference channel.</p>
+
+ <p>The <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface"
+ >Group</tp:dbus-ref> interface on Conference channels MAY use
+ channel-specific handles for participants; clients SHOULD support
+ both Conferences that have channel-specific handles, and those that
+ do not.</p>
+
+ <tp:rationale>
+ <p>In the GSM case, the Conference's Group interface MAY have
+ channel-specific handles, to represent the fact that the same
+ phone number may be in a conference twice (for instance, it could be
+ the number of a corporate switchboard).</p>
+
+ <p>In the XMPP case, the Conference's Group interface SHOULD have
+ channel-specific handles, to reflect the fact that the participants
+ have MUC-specific identities, and the user might also be able to see
+ their global identities, or not.</p>
+
+ <p>In most other cases, including MSN and link-local XMPP, the
+ Conference's Group interface SHOULD NOT have channel-specific
+ handles, since users' identities are always visible.</p>
+ </tp:rationale>
+
+ <p>Connection managers implementing channels with this interface
+ MUST NOT allow the object paths of channels that could be merged
+ into a Conference to be re-used, unless the channel re-using the
+ object path is equivalent to the channel that previously used it.</p>
+
+ <tp:rationale>
+ <p>If you upgrade some channels into a conference, and then close
+ the original channels, <tp:member-ref>InitialChannels</tp:member-ref>
+ (which is immutable) will contain paths to channels which no longer
+ exist. This implies that you should not re-use channel object paths,
+ unless future incarnations of the path are equivalent.</p>
+
+ <p>For instance, on protocols where you can only have
+ zero or one 1-1 text channels with Emily at one time, it would
+ be OK to re-use the same object path for every 1-1 text channel
+ with Emily; but on protocols where this is not true, it would
+ be misleading.</p>
+ </tp:rationale>
+
+ <h4>Examples of usage</h4>
+
+ <p>A pair of 1-1 GSM calls <var>C1</var> and <var>C2</var> can be merged
+ into a single conference call by calling:</p>
+
+ <blockquote>
+ <code><tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>({
+ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">ChannelType</tp:dbus-ref>: ...Call,
+ ...<tp:member-ref>InitialChannels</tp:member-ref>: [C1, C2]
+ })</code>
+ </blockquote>
+
+ <p>which returns a new channel <var>Cn</var> implementing the conference
+ interface. (As a quirk of GSM, both 1-1 will cease to function normally
+ until they are <tp:dbus-ref
+ namespace="ofdT.Channel.Interface.Splittable.DRAFT">Split</tp:dbus-ref>
+ from the conference, or the conference ends.)</p>
+
+ <p>An XMPP 1-1 conversation <var>C3</var> (with
+ <tt>chris@example.com</tt>, say) can be continued in a newly created
+ multi-user chatroom by calling:</p>
+
+ <blockquote>
+ <code>CreateChannel({
+ ...ChannelType: ...Text,
+ ...<tp:member-ref>InitialChannels</tp:member-ref>: [C3]
+ })</code>
+ </blockquote>
+
+ <p>Or, to invite <tt>emily@example.net</tt> to join the newly-created MUC
+ at the same time:</p>
+
+ <blockquote>
+ <code>CreateChannel({
+ ...ChannelType: ...Text,
+ ...<tp:member-ref>InitialChannels</tp:member-ref>: [C3],
+ ...<tp:member-ref>InitialInviteeIDs</tp:member-ref>: ['emily@example.net']
+ })</code>
+ </blockquote>
+
+ <p>To continue <var>C3</var> in a particular multi-user
+ chatroom (rather than the implementation inventing a unique name for
+ the room), call:</p>
+
+ <blockquote>
+ <code><tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">EnsureChannel</tp:dbus-ref>({
+ ...ChannelType: ...Text,
+ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetHandleType</tp:dbus-ref>: ...Room,
+ ...<tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel">TargetID</tp:dbus-ref>: 'telepathy@conf.example.com',
+ ...<tp:member-ref>InitialChannels</tp:member-ref>: [C3]
+ })</code>
+ </blockquote>
+
+ <p>Note the use of EnsureChannel — if a channel for
+ <tt>telepathy@conf.example.com</tt> is already open, this SHOULD be
+ equivalent to inviting <tt>chris@example.com</tt> to the existing
+ channel.</p>
+
+ <p>In the above cases, the text channel <var>C3</var> SHOULD remain open
+ and fully functional (until explicitly closed by a client); new
+ incoming 1-1 messages from <tt>chris@example.com</tt> SHOULD appear in
+ <var>C3</var>, and messages sent using <var>C3</var> MUST be relayed
+ only to <tt>chris@example.com</tt>.</p>
+
+ <tp:rationale>
+ <p>If there is an open 1-1 text channel with a contact, in every
+ other situation new messages will appear in that channel. Given
+ that the old channel remains open — which is the least surprising
+ behaviour, and eases us towards a beautiful world where channels
+ never close themselves — it stands to reason that it should be
+ where new messages from Chris should appear. On MSN, creating a
+ conference from <var>C3</var> should migrate the underlying
+ switchboard from <var>C3</var> to the new channel; this is an
+ implementation detail, and should not affect the representation on
+ D-Bus. With a suitable change of terminology, Skype has the same
+ behaviour.</p>
+
+ <p>If the current handler of that channel doesn't want this to happen
+ (maybe it transformed the existing tab into the group chat window,
+ and so there'd be no UI element still around to show new messages),
+ then it should just <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> the
+ old 1-1 channel; it'll respawn if necessary.</p>
+ </tp:rationale>
+
+ <p>Either of the XMPP cases could work for Call channels, to
+ upgrade from 1-1 Jingle to multi-user Jingle. Any of the XMPP cases
+ could in principle work for link-local XMPP (XEP-0174).</p>
+
+ <p>XMPP and MSN do not natively have a concept of merging two or more
+ channels C1, C2... into one channel, Cn. However, the GSM-style
+ merging API can be supported on XMPP and MSN, as an API short-cut
+ for upgrading C1 into a conference Cn (which invites the
+ TargetHandle of C1 into Cn), then immediately inviting the
+ TargetHandle of C2, the TargetHandle of C3, etc. into Cn as well.</p>
+
+ <h4>Sample <tp:dbus-ref namespace='ofdT.Connection.Interface.Requests'
+ >RequestableChannelClasses</tp:dbus-ref></h4>
+
+ <p>A GSM connection might advertise the following channel class for
+ conference calls:</p>
+
+ <blockquote>
+ <code>
+( Fixed = {<br/>
+    ...<tp:dbus-ref namespace='ofdT.Channel'>ChannelType</tp:dbus-ref>:
+ ...<tp:dbus-ref namespace='ofdT.Channel.Type'>StreamedMedia</tp:dbus-ref><br/>
+  },<br/>
+  Allowed = [ <tp:member-ref>InitialChannels</tp:member-ref>,
+ <tp:dbus-ref namespace='ofdT.Channel.Type.StreamedMedia'
+ >InitialAudio</tp:dbus-ref>
+ ]<br/>
+)
+ </code>
+ </blockquote>
+
+ <p>This indicates support for starting audio-only conference calls by
+ merging two or more existing channels (since
+ <tp:member-ref>InitialInviteeHandles</tp:member-ref> and
+ <tp:member-ref>InitialInviteeIDs</tp:member-ref> are not allowed).</p>
+
+ <p>An XMPP connection might advertise the following classes for ad-hoc
+ multi-user text chats:</p>
+
+ <blockquote>
+ <code>
+( Fixed = {<br/>
+    ...<tp:dbus-ref namespace='ofdT.Channel'>ChannelType</tp:dbus-ref>:
+ ...<tp:dbus-ref namespace='ofdT.Channel.Type'>Text</tp:dbus-ref><br/>
+  },<br/>
+  Allowed = [ <tp:member-ref>InitialChannels</tp:member-ref>,
+ <tp:member-ref>InitialInviteeHandles</tp:member-ref>,
+ <tp:member-ref>InitialInviteeIDs</tp:member-ref>,
+ <tp:member-ref>InvitationMessage</tp:member-ref>
+ ]<br/>
+),<br/>
+( Fixed = {<br/>
+    ...<tp:dbus-ref namespace='ofdT.Channel'>ChannelType</tp:dbus-ref>:
+ ...<tp:dbus-ref namespace='ofdT.Channel.Type'>Text</tp:dbus-ref>,<br/>
+    ...<tp:dbus-ref namespace='ofdT.Channel'>TargetHandleType</tp:dbus-ref>:
+ Room<br/>
+  },<br/>
+  Allowed = [ <tp:dbus-ref namespace='ofdT.Channel'>TargetHandle</tp:dbus-ref>,
+ <tp:dbus-ref namespace='ofdT.Channel'>TargetID</tp:dbus-ref>,<br/>
+              <tp:member-ref>InitialChannels</tp:member-ref>,
+ <tp:member-ref>InitialInviteeHandles</tp:member-ref>,
+ <tp:member-ref>InitialInviteeIDs</tp:member-ref>,
+ <tp:member-ref>InvitationMessage</tp:member-ref>
+ ]<br/>
+)
+ </code>
+ </blockquote>
+
+ <p>The first class indicates support for starting ad-hoc (nameless) chat
+ rooms, upgraded from existing 1-1 channels and/or inviting new
+ contacts, along with a message to be sent along with the invitations.
+ The second indicates support for upgrading to a particular named chat
+ room.</p>
+ </tp:docstring>
+
+ <property name="Channels" tp:name-for-bindings="Channels"
+ access="read" type="ao">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The individual <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref>s that
+ are continued by this conference, which have the same <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel"
+ >ChannelType</tp:dbus-ref> as this one, but with <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel"
+ >TargetHandleType</tp:dbus-ref> = CONTACT.</p>
+
+ <p>This property MUST NOT be requestable; instead, the
+ <tp:member-ref>InitialChannels</tp:member-ref> property may be
+ specified when requesting a channel.</p>
+
+ <tp:rationale>
+ <p>This is consistent with requesting
+ <tp:member-ref>InitialInviteeHandles</tp:member-ref> and
+ <tp:member-ref>InitialInviteeIDs</tp:member-ref>, rather than
+ requesting <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface">Group.Members</tp:dbus-ref>
+ and some hypothetical ID version of that property.</p>
+ </tp:rationale>
+
+ <p>Change notification is via the
+ <tp:member-ref>ChannelMerged</tp:member-ref> and
+ <tp:member-ref>ChannelRemoved</tp:member-ref> signals.</p>
+ </tp:docstring>
+ </property>
+
+ <signal name="ChannelMerged" tp:name-for-bindings="Channel_Merged">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when a new channel is added to the value of
+ <tp:member-ref>Channels</tp:member-ref>.</p>
+ </tp:docstring>
+
+ <arg name="Channel" type="o">
+ <tp:docstring>The channel that was added to
+ <tp:member-ref>Channels</tp:member-ref>.</tp:docstring>
+ </arg>
+
+ <arg name="Channel_Specific_Handle" type="u" tp:type="Contact_Handle">
+ <tp:docstring>A new channel-specific handle for the <tp:dbus-ref
+ namespace="ofdT.Channel">TargetHandle</tp:dbus-ref> of
+ <var>Channel</var>, as will appear in
+ <tp:member-ref>OriginalChannels</tp:member-ref>, or <tt>0</tt> if a
+ global handle is used for
+ <var>Channel</var>'s TargetHandle on the <tp:dbus-ref
+ namespace="ofdT.Channel.Interface">Group</tp:dbus-ref> interface
+ of this channel.</tp:docstring>
+ </arg>
+
+ <arg name="Properties" type="a{sv}"
+ tp:type="Qualified_Property_Value_Map">
+ <tp:docstring><var>Channel</var>'s immutable properties.</tp:docstring>
+ </arg>
+ </signal>
+
+ <signal name="ChannelRemoved" tp:name-for-bindings="Channel_Removed">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when a channel is removed from the value of
+ <tp:member-ref>Channels</tp:member-ref>, either because it closed
+ or because it was split using the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface"
+ >Splittable.DRAFT.Split</tp:dbus-ref> method.</p>
+
+ <p>If a channel is removed because it was closed, <tp:dbus-ref
+ namespace='ofdT.Channel'>Closed</tp:dbus-ref> should be emitted
+ before this signal.</p>
+ </tp:docstring>
+
+ <arg name="Channel" type="o">
+ <tp:docstring>The channel that was removed from
+ <tp:member-ref>Channels</tp:member-ref>.</tp:docstring>
+ </arg>
+
+ <arg name="Details" type="a{sv}" tp:type="String_Variant_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ Additional information about the removal, which may include
+ the same well-known keys as the Details argument of
+ <tp:dbus-ref namespace="ofdT.Channel.Interface.Group"
+ >MembersChangedDetailed</tp:dbus-ref>, with the same semantics.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <property name="InitialChannels" tp:name-for-bindings="Initial_Channels"
+ access="read" type="ao" tp:immutable="yes" tp:requestable="yes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The initial value of <tp:member-ref>Channels</tp:member-ref>.</p>
+
+ <p>This property SHOULD be requestable. Omitting it from a request is
+ equivalent to providing it with an empty list as value. Requests
+ where its value has at least two channel paths SHOULD be expected to
+ succeed on any implementation of this interface. If
+ <tp:member-ref>InitialInviteeHandles</tp:member-ref> and
+ <tp:member-ref>InitialInviteeIDs</tp:member-ref> are
+ <var>Allowed_Properties</var> in <tp:dbus-ref
+ namespace='ofdT.Connection.Interface.Requests'
+ >RequestableChannelClasses</tp:dbus-ref>, then requests with zero
+ or one channel paths SHOULD also succeed; otherwise, clients SHOULD
+ NOT make requests with zero or one paths for this property.</p>
+
+ <tp:rationale>
+ <p>In GSM, a pair of calls can be merged into a conference, but you
+ can't start a conference call from zero or one existing calls. In
+ XMPP and MSN, you can create a new chatroom, or upgrade one 1-1
+ channel into a chatroom; however, on these protocols, it is also
+ possible to fake GSM-style merging by upgrading the first channel,
+ then inviting the targets of all the other channels into it.</p>
+ </tp:rationale>
+
+ <p>If possible, the <tp:member-ref>Channels</tp:member-ref>' states SHOULD
+ NOT be altered by merging them into a conference. However, depending on
+ the protocol, the Channels MAY be placed in a "frozen" state by placing
+ them in this property's value or by calling
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface"
+ >MergeableConference.DRAFT.Merge</tp:dbus-ref> on them.</p>
+
+ <tp:rationale>
+ <p>In Jingle, nothing special will happen to merged calls. UIs MAY
+ automatically place calls on hold before merging them, if that is
+ the desired behaviour; this SHOULD always work. Not doing
+ an implicit hold/unhold seems to preserve least-astonishment.</p>
+
+ <p>In GSM, the calls that are merged go into a state similar to
+ Hold, but they cannot be unheld, only split from the conference
+ call using <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+ >Channel.Interface.Splittable.DRAFT.Split</tp:dbus-ref>.</p>
+ </tp:rationale>
+
+ <p>Depending on the protocol, it might be signalled to remote users
+ that this channel is a continuation of all the requested channels,
+ or that it is only a continuation of the first channel in the
+ list.</p>
+
+ <tp:rationale>
+ <p>In MSN, the conference steals the underlying switchboard (protocol
+ construct) from one of its component channels, so the conference
+ appears to remote users to be a continuation of that channel and no
+ other. The connection manager has to make some arbitrary choice, so
+ we arbitrarily mandate that it SHOULD choose the first channel in
+ the list as the one to continue.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="InitialInviteeHandles"
+ tp:name-for-bindings="Initial_Invitee_Handles"
+ access="read" type="au" tp:type="Contact_Handle[]" tp:immutable="yes"
+ tp:requestable="yes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A list of additional contacts invited to this conference when it
+ was created.</p>
+
+ <p>If it is possible to invite new contacts when creating a conference
+ (as opposed to merging several channels into one new conference
+ channel), this property SHOULD be requestable, and appear in the allowed
+ properties in <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests"
+ >RequestableChannelClasses</tp:dbus-ref>. Otherwise, this property
+ SHOULD NOT be requestable, and its value SHOULD always be the empty
+ list.</p>
+
+ <tp:rationale>
+ <p>On GSM you have to place a 1-1 call before you can merge it into a
+ conference; on the other hand, you can invite new contacts to XMPP
+ Muji calls and XMPP/MSN/Skype ad-hoc chat rooms without starting a
+ 1-1 channel with them first.</p>
+ </tp:rationale>
+
+ <p>If included in a request, the given contacts are automatically
+ invited into the new channel, as if they had been added with
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface"
+ >Group.AddMembers</tp:dbus-ref>(InitialInviteeHandles,
+ <tp:member-ref>InvitationMessage</tp:member-ref>) immediately after
+ the channel was created.</p>
+
+ <tp:rationale>
+ <p>This is a simple convenience API for the common case that a UI
+ upgrades a 1-1 chat to a multi-user chat solely in order to invite
+ someone else to participate.</p>
+ </tp:rationale>
+
+ <p>If the local user was not the initiator of this channel, the
+ <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface"
+ >Group.SelfHandle</tp:dbus-ref> SHOULD appear in the value of this
+ property, together with any other contacts invited at the same time
+ (if that information is known).</p>
+
+ <p>InitialInviteeHandles, InitialInviteeIDs and InitialChannels MAY be
+ combined in a single request.</p>
+
+ <tp:rationale>
+ <p>For example, if you have a 1-1 channel C1 with Rob, and you want
+ to invite Sjoerd to join the discussion, you can do so by
+ requesting a channel with InitialChannels=[C1] and
+ InitialInviteeHandles=[sjoerd],
+ or InitialChannels=[C1] and
+ InitialInviteeIDs=["sjoerd@example.com"].</p>
+ </tp:rationale>
+
+ <p>If a request includes some combination of InitialInviteeHandles,
+ InitialInviteeIDs and InitialChannels, then the value of
+ InitialInviteeHandles on the resulting channel SHOULD be the union of
+ the handles from InitialInviteeHandles, the handles corresponding
+ to the InitialInviteeIDs, and the target handles of the
+ InitialChannels, with any duplicate handles removed. Because this
+ property is immutable, its value SHOULD be computed before the
+ channel is announced via the NewChannels signal.</p>
+
+ <tp:rationale>
+ <p>This simplifies identification of new channels in clients - they
+ only have to look at one of the properties, not both. For example,
+ after either of the requests mentioned above, the NewChannels
+ signal would announce the channel with InitialChannels=[C1],
+ InitialInviteeHandles=[rob, sjoerd], and
+ InitialInviteeIDs=["rob@example.net", "sjoerd.example.com"].</p>
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <property name="InitialInviteeIDs"
+ tp:name-for-bindings="Initial_Invitee_IDs"
+ access="read" type="as" tp:immutable="yes" tp:requestable="yes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A list of additional contacts invited to this conference when it
+ was created.</p>
+
+ <p>This property SHOULD be requestable if and only if
+ <tp:member-ref>InitialInviteeHandles</tp:member-ref> is requestable.
+ Its semantics are the same, except that it takes a list of the
+ string representations of contact handles; invitations are sent to
+ any contact present in either or both of these properties.</p>
+
+ <p>When a channel is created, the values of InitialInviteeHandles and
+ InitialInviteeIDs MUST correspond to each other. In particular, this
+ means that the value of InitialInviteeIDs will include the TargetID
+ of each channel in InitialChannels, and the ID corresponding to each
+ handle in InitialInviteeHandles.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="InvitationMessage" tp:name-for-bindings="Invitation_Message"
+ access="read" type="s" tp:immutable="yes" tp:requestable="yes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The message that was sent to the
+ <tp:member-ref>InitialInviteeHandles</tp:member-ref> when they were
+ invited.</p>
+
+ <p>This property SHOULD be requestable, and appear in the allowed
+ properties in <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Requests"
+ >RequestableChannelClasses</tp:dbus-ref>, in protocols where
+ invitations can have an accompanying text message.</p>
+
+ <tp:rationale>
+ <p>This allows invitations with a message to be sent when using
+ <tp:member-ref>InitialInviteeHandles</tp:member-ref> or
+ <tp:member-ref>InitialInviteeIDs</tp:member-ref>.</p>
+ </tp:rationale>
+
+ <p>If the local user was not the initiator of this channel, the
+ message with which they were invited (if any) SHOULD appear in the
+ value of this property.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="OriginalChannels" tp:name-for-bindings="Original_Channels"
+ type="a{uo}" tp:type="Channel_Originator_Map"
+ access="read">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>On GSM conference calls, it is possible to have the same phone
+ number in a conference twice; for instance, it could be the number of
+ a corporate switchboard. This is represented using channel-specific
+ handles; whether or not a channel uses channel-specific handles is
+ reported in <tp:dbus-ref
+ namespace='ofdT.Channel.Interface'>Group.GroupFlags</tp:dbus-ref>.
+ The <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface">Group.HandleOwners</tp:dbus-ref>
+ property specifies the mapping from opaque channel-specific handles
+ to actual numbers; this property specifies the original 1-1 channel
+ corresponding to each channel-specific handle in the conference.</p>
+
+ <p>In protocols where this situation cannot arise, such as XMPP,
+ this property MAY remain empty.</p>
+
+ <p>For example, consider this situation:</p>
+
+ <ol>
+ <li>Place a call (with path <tt>/call/to/simon</tt>) to the contact
+ <tt>+441234567890</tt> (which is assigned the handle <var>h</var>,
+ say), and ask to be put through to Simon McVittie;</li>
+ <li>Put that call on hold;</li>
+ <li>Place another call (with path <tt>/call/to/jonny</tt>) to
+ <tt>+441234567890</tt>, and ask to be put
+ through to Jonny Lamb;</li>
+ <li>Request a new channel with
+ <tp:member-ref>InitialChannels</tp:member-ref>:
+ <tt>['/call/to/simon', '/call/to/jonny']</tt>.</li>
+ </ol>
+
+ <p>The new channel will have the following properties, for some handles
+ <var>s</var> and <var>j</var>:</p>
+
+ <blockquote>
+ <code>{<br/>
+ ...<tp:dbus-ref
+ namespace="ofdT.Channel.Interface">Group.GroupFlags</tp:dbus-ref>:
+ Channel_Specific_Handles | (other flags),<br/>
+ ...<tp:dbus-ref
+ namespace="ofdT.Channel.Interface">Group.Members</tp:dbus-ref>:
+ [self_handle, s, j],<br/>
+ ...<tp:dbus-ref
+ namespace="ofdT.Channel.Interface">Group.HandleOwners</tp:dbus-ref>:
+ { s: h, j: h },<br/>
+ ...<tp:member-ref>InitialChannels</tp:member-ref>:
+ ['/call/to/simon', '/call/to/jonny'],<br/>
+ ...<tp:member-ref>Channels</tp:member-ref>:
+ ['/call/to/simon', '/call/to/jonny'],<br/>
+ ...<tp:member-ref>OriginalChannels</tp:member-ref>:
+ { s: '/call/to/simon', j: '/call/to/jonny' },<br/>
+ # ...standard properties like ChannelType: Group elided...<br/>
+ }</code>
+ </blockquote>
+
+ <p>Change notification is via the
+ <tp:member-ref>ChannelMerged</tp:member-ref> and
+ <tp:member-ref>ChannelRemoved</tp:member-ref> signals: if
+ <var>Channel_Specific_Handle</var> in the former is non-zero, this
+ property SHOULD be updated to map that handle to the merged channel's
+ path.</p>
+ </tp:docstring>
+ </property>
+
+ <tp:mapping name="Channel_Originator_Map">
+ <tp:member name="Channel_Specific_Handle" type="u" tp:type="Contact_Handle">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ A channel-specific handle for a participant in this conference.
+ </tp:docstring>
+ </tp:member>
+ <tp:member name="Original_Channel" type="o">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ The object path of <tp:member-ref>Channels</tp:member-ref>
+ representing the original 1-1 channel with
+ <var>Channel_Specific_Handle</var>.
+ </tp:docstring>
+ </tp:member>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ A mapping from members of a conference to the original 1-1 channel with
+ that contact, if any. See
+ <tp:member-ref>OriginalChannels</tp:member-ref> for details.
+ </tp:docstring>
+ </tp:mapping>
+ </interface>
+</node>
diff --git a/spec/Channel_Interface_DTMF.xml b/spec/Channel_Interface_DTMF.xml
new file mode 100644
index 0000000..d74ea6f
--- /dev/null
+++ b/spec/Channel_Interface_DTMF.xml
@@ -0,0 +1,342 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_DTMF" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2005-2010 Collabora Limited</tp:copyright>
+ <tp:copyright>Copyright © 2005-2010 Nokia Corporation</tp:copyright>
+ <tp:copyright>Copyright © 2006 INdT</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.</p>
+
+<p>This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+Lesser General Public License for more details.</p>
+
+<p>You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
+ </tp:license>
+ <interface name="org.freedesktop.Telepathy.Channel.Interface.DTMF">
+ <tp:xor-requires>
+ <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/>
+ <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Call.DRAFT"/>
+ </tp:xor-requires>
+ <tp:changed version="0.19.6">The <tp:type>Stream_ID</tp:type>s in this
+ interface should now be ignored by CMs. This is primarily to allow this
+ interface to be used with <tp:dbus-ref
+ namespace='ofdT.Channel.Type'>Call.DRAFT</tp:dbus-ref>
+ channels.</tp:changed>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ An interface that gives a Channel the ability to send DTMF events over
+ audio streams which have been established using the StreamedMedia channel
+ type. The event codes used are in common with those defined in <a
+ href="http://www.rfc-editor.org/rfc/rfc4733.txt">RFC4733</a>, and are
+ listed in the <tp:type>DTMF_Event</tp:type> enumeration.
+ </tp:docstring>
+
+ <method name="StartTone" tp:name-for-bindings="Start_Tone">
+ <tp:changed version="0.19.6">The <var>Stream_ID</var> parameter became
+ vestigial.</tp:changed>
+ <arg direction="in" name="Stream_ID" type="u" tp:type="Stream_ID">
+ <tp:docstring>A stream ID as defined in the StreamedMedia channel
+ type. This argument is included for backwards compatibility and MUST
+ be ignored by the implementations - the tone SHOULD be sent to all
+ eligible streams in the channel.</tp:docstring>
+ </arg>
+ <arg direction="in" name="Event" type="y" tp:type="DTMF_Event">
+ <tp:docstring>A numeric event code from the DTMF_Event enum.</tp:docstring>
+ </arg>
+
+ <tp:docstring>
+ <p>Start sending a DTMF tone to all eligible streams in the channel.
+ Where possible, the tone will continue until
+ <tp:member-ref>StopTone</tp:member-ref> is called. On certain protocols,
+ it may only be possible to send events with a predetermined length. In
+ this case, the implementation MAY emit a fixed-length tone, and the
+ StopTone method call SHOULD return NotAvailable.</p>
+ <tp:rationale>
+ The client may wish to control the exact duration and timing of the
+ tones sent as a result of user's interaction with the dialpad, thus
+ starting and stopping the tone sending explicitly.
+ </tp:rationale>
+
+ <p>Tone overlaping or queueing is not supported, so this method can only
+ be called if no DTMF tones are already being played.</p>
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError" />
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The given stream ID was invalid. Deprecated, since stream IDs
+ are ignored.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ There are no eligible audio streams.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.ServiceBusy">
+ <tp:docstring>
+ DTMF tones are already being played.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="StopTone" tp:name-for-bindings="Stop_Tone">
+ <tp:changed version="0.19.6">The <var>Stream_ID</var> parameter became
+ vestigial.</tp:changed>
+ <arg direction="in" name="Stream_ID" type="u" tp:type="Stream_ID">
+ <tp:docstring>A stream ID as defined in the StreamedMedia channel
+ type. This argument is included for backwards compatibility and MUST
+ be ignored by the implementations - the sending SHOULD be stoped in
+ all eligible streams in the channel.</tp:docstring>
+ </arg>
+
+ <tp:docstring>
+ Stop sending any DTMF tones which have been started using the
+ <tp:member-ref>StartTone</tp:member-ref> or
+ <tp:member-ref>MultipleTones</tp:member-ref> methods.
+ If there is no current tone, this method will do nothing.
+ If MultipleTones was used, the client should not assume the
+ sending has stopped immediately; instead, the client should wait
+ for the StoppedTones signal.
+ <tp:rationale>
+ On some protocols it might be impossible to cancel queued tones
+ immediately.
+ </tp:rationale>
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError" />
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The given stream ID was invalid. Deprecated, since stream IDs
+ are ignored.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ Continuous tones are not supported by this stream. Deprecated,
+ since stream IDs are ignored.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="MultipleTones" tp:name-for-bindings="Multiple_Tones">
+ <tp:added version="0.19.6" />
+ <tp:changed version="0.21.3">The characters [pPxXwW,] must
+ also be supported.</tp:changed>
+ <arg direction="in" name="Tones" type="s">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A string representation of one or more DTMF
+ events. Implementations of this method MUST support all of the
+ following characters in this string:</p>
+
+ <ul>
+ <li>the digits 0-9, letters A-D and a-d, and symbols '*' and '#'
+ correspond to the members of <tp:type>DTMF_Event</tp:type></li>
+
+ <li>any of 'p', 'P', 'x', 'X' or ',' (comma) results in an
+ implementation-defined pause, typically for 3 seconds</li>
+
+ <li>'w' or 'W' waits for the user to continue, by stopping
+ interpretation of the string, and if there is more to be played,
+ emitting the <tp:member-ref>TonesDeferred</tp:member-ref> signal
+ with the rest of the string as its argument: see that signal
+ for details</li>
+ </ul>
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ <p>Send multiple DTMF events to all eligible streams in the channel.
+ Each tone will be played for an implementation-defined number of
+ milliseconds (typically 250ms), followed by a gap before the next tone
+ is played (typically 100ms). The
+ duration and gap are defined by the protocol or connection manager.</p>
+
+ <tp:rationale>
+ <p>In cases where the client knows in advance the tone sequence it
+ wants to send, it's easier to use this method than manually start
+ and stop each tone in the sequence.</p>
+
+ <p>The tone and gap lengths may need to vary for interoperability,
+ according to the protocol and other implementations' ability to
+ recognise tones. At the time of writing, GStreamer uses a
+ minimum of 250ms tones and 100ms gaps when playing in-band DTMF
+ in the normal audio stream, or 70ms tones and 50ms gaps when
+ encoding DTMF as <code>audio/telephone-event</code>.</p>
+ </tp:rationale>
+
+ <p>Tone overlaping or queueing is not supported, so this method can only
+ be called if no DTMF tones are already being played.</p>
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError" />
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The supplied Tones string was invalid.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ There are no eligible audio streams.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.ServiceBusy">
+ <tp:docstring>
+ DTMF tones are already being played.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <property name="CurrentlySendingTones"
+ tp:name-for-bindings="Currently_Sending_Tones" type="b" access="read">
+ <tp:added version="0.19.6" />
+ <tp:docstring>
+ Indicates whether there are DTMF tones currently being sent in the
+ channel. If so, the client should wait for
+ <tp:member-ref>StoppedTones</tp:member-ref> signal before trying to
+ send more tones.
+ </tp:docstring>
+ </property>
+
+ <property name="InitialTones" tp:name-for-bindings="Initial_Tones"
+ type="s" access="read">
+ <tp:added version="0.19.6" />
+ <tp:docstring>
+ <p>If non-empty in a channel request that will create a new channel,
+ the connection manager should send the tones immediately after
+ at least one eligible audio stream has been created in the
+ channel.</p>
+
+ <p>This property is immutable (cannot change).</p>
+ </tp:docstring>
+ </property>
+
+ <property name="DeferredTones" tp:name-for-bindings="Deferred_Tones"
+ type="s" access="read">
+ <tp:added version="0.21.3" />
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The tones waiting for the user to continue, if any.</p>
+
+ <p>When this property is set to a non-empty value,
+ <tp:member-ref>TonesDeferred</tp:member-ref> is emitted.
+ When any tones are played (i.e. whenever
+ <tp:member-ref>SendingTones</tp:member-ref> is emitted),
+ this property is reset to the empty string.</p>
+ </tp:docstring>
+ </property>
+
+ <signal name="TonesDeferred" tp:name-for-bindings="Tones_Deferred">
+ <tp:added version="0.21.3" />
+ <arg name="Tones" type="s">
+ <tp:docstring>The new non-empty value of
+ <tp:member-ref>DeferredTones</tp:member-ref>.</tp:docstring>
+ </arg>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when 'w' or 'W', indicating "wait for the user to continue",
+ is encountered while playing a DTMF string queued by
+ <tp:member-ref>MultipleTones</tp:member-ref> or
+ <tp:member-ref>InitialTones</tp:member-ref>. Any queued DTMF events
+ after the 'w', which have not yet been played, are placed in the
+ <tp:member-ref>DeferredTones</tp:member-ref> property and copied
+ into this signal's argument.</p>
+
+ <p>When the channel handler is ready to continue, it MAY pass the
+ value of <tp:member-ref>DeferredTones</tp:member-ref> to
+ <tp:member-ref>MultipleTones</tp:member-ref>, to resume sending.
+ Alternatively, it MAY ignore the deferred tones, or even play
+ different tones instead. Any deferred tones are discarded the next
+ time a tone is played.</p>
+
+ <p>This signal SHOULD NOT be emitted if there is nothing left to play,
+ i.e. if the 'w' was the last character in the DTMF string.</p>
+ </tp:docstring>
+ </signal>
+
+ <signal name="SendingTones" tp:name-for-bindings="Sending_Tones">
+ <tp:added version="0.19.6" />
+ <arg name="Tones" type="s">
+ <tp:docstring>DTMF string (one or more events) that is to be played.
+ </tp:docstring>
+ </arg>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>DTMF tone(s)are being sent to all eligible streams in the channel.
+ The signal is provided to indicating the fact that the streams are
+ currently being used to send one or more DTMF tones, so any other
+ media input is not getting through to the audio stream. It also
+ serves as a cue for the
+ <tp:member-ref>StopTone</tp:member-ref> method.</p>
+ </tp:docstring>
+ </signal>
+
+ <signal name="StoppedTones" tp:name-for-bindings="Stopped_Tones">
+ <tp:added version="0.19.6" />
+ <arg name="Cancelled" type="b">
+ <tp:docstring>True if the DTMF tones were actively cancelled via
+ <tp:member-ref>StopTone</tp:member-ref>.</tp:docstring>
+ </arg>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>DTMF tones have finished playing on streams in this channel.</p>
+ </tp:docstring>
+ </signal>
+
+ <tp:enum name="DTMF_Event" type="y">
+ <tp:enumvalue suffix="Digit_0" value="0">
+ <tp:docstring>0</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Digit_1" value="1">
+ <tp:docstring>1</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Digit_2" value="2">
+ <tp:docstring>2</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Digit_3" value="3">
+ <tp:docstring>3</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Digit_4" value="4">
+ <tp:docstring>4</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Digit_5" value="5">
+ <tp:docstring>5</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Digit_6" value="6">
+ <tp:docstring>6</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Digit_7" value="7">
+ <tp:docstring>7</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Digit_8" value="8">
+ <tp:docstring>8</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Digit_9" value="9">
+ <tp:docstring>9</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Asterisk" value="10">
+ <tp:docstring>*</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Hash" value="11">
+ <tp:docstring>#</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Letter_A" value="12">
+ <tp:docstring>A</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Letter_B" value="13">
+ <tp:docstring>B</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Letter_C" value="14">
+ <tp:docstring>C</tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Letter_D" value="15">
+ <tp:docstring>D</tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Interface_Destroyable.xml b/spec/Channel_Interface_Destroyable.xml
new file mode 100644
index 0000000..ce55923
--- /dev/null
+++ b/spec/Channel_Interface_Destroyable.xml
@@ -0,0 +1,82 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Destroyable"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright>
+
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ License as published by the Free Software Foundation; either
+ version 2.1 of the License, or (at your option) any later version.</p>
+
+ <p>This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.</p>
+
+ <p>You should have received a copy of the GNU Lesser General Public
+ License along with this library; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
+ USA.</p>
+ </tp:license>
+
+ <interface
+ name="org.freedesktop.Telepathy.Channel.Interface.Destroyable">
+ <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+ <tp:added version="0.17.14">(as stable API)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This interface exists to support channels where
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel.Close</tp:dbus-ref>
+ is insufficiently destructive. At the moment this means
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel.Type.Text</tp:dbus-ref>,
+ but the existence of this interface means that unsupported channels
+ can be terminated in a non-channel-type-specific way.</p>
+ </tp:docstring>
+
+ <method name="Destroy" tp:name-for-bindings="Destroy">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Close the channel abruptly, possibly with loss of data. The
+ connection manager MUST NOT re-create the channel unless/until
+ more events occur.</p>
+
+ <tp:rationale>
+ <p>The main motivating situation for this method is that when a Text
+ channel with pending messages is closed with Close, it comes back
+ as an incoming channel (to avoid a race between Close and an
+ incoming message). If Destroy is called on a Text channel, the CM
+ should delete all pending messages and close the channel, and
+ the channel shouldn't be re-created until/unless another message
+ arrives.</p>
+ </tp:rationale>
+
+ <p>Most clients SHOULD call
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel.Close</tp:dbus-ref>
+ instead. However, if a client explicitly intends to destroy the
+ channel with possible loss of data, it SHOULD call this method
+ if this interface is supported (according to the
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Channel.Interfaces</tp:dbus-ref>
+ property), falling back to Close if not.</p>
+
+ <p>In particular, channel dispatchers SHOULD use this method if
+ available when terminating channels that cannot be handled
+ correctly (for instance, if no handler has been installed for
+ a channel type, or if the handler crashes repeatedly).</p>
+
+ <p>Connection managers do not need to implement this interface on
+ channels where Close and Destroy would be equivalent.</p>
+
+ <tp:rationale>
+ <p>Callers need to be able to fall back to Close in any case.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </method>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Interface_Group.xml b/spec/Channel_Interface_Group.xml
new file mode 100644
index 0000000..92de9c5
--- /dev/null
+++ b/spec/Channel_Interface_Group.xml
@@ -0,0 +1,1166 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Group" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2005-2009 Collabora Limited</tp:copyright>
+ <tp:copyright>Copyright © 2005-2009 Nokia Corporation</tp:copyright>
+ <tp:copyright>Copyright © 2006 INdT</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.</p>
+
+<p>This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+Lesser General Public License for more details.</p>
+
+<p>You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
+ </tp:license>
+ <interface name="org.freedesktop.Telepathy.Channel.Interface.Group">
+ <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+
+ <tp:struct name="Local_Pending_Info" array-name="Local_Pending_Info_List">
+ <tp:docstring>A structure representing a contact whose attempt to
+ join a group is to be confirmed by the local user using
+ <tp:member-ref>AddMembers</tp:member-ref>.</tp:docstring>
+ <tp:member type="u" tp:type="Contact_Handle" name="To_Be_Added">
+ <tp:docstring>
+ The contact to be added to the group
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="u" tp:type="Contact_Handle" name="Actor">
+ <tp:docstring>
+ The contact requesting or causing the change
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="u" tp:type="Channel_Group_Change_Reason" name="Reason">
+ <tp:docstring>
+ The reason for the change
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="s" name="Message">
+ <tp:docstring>
+ A human-readable message from the Actor, or an empty string
+ if there is no message
+ </tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <method name="AddMembers" tp:name-for-bindings="Add_Members">
+ <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ An array of contact handles to invite to the channel
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="Message" type="s">
+ <tp:docstring>
+ A string message, which can be blank if desired
+ </tp:docstring>
+ </arg>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Invite all the given contacts into the channel, or accept requests for
+ channel membership for contacts on the pending local list.</p>
+
+ <p>A message may be provided along with the request, which will be sent
+ to the server if supported. See the CHANNEL_GROUP_FLAG_MESSAGE_ADD and
+ CHANNEL_GROUP_FLAG_MESSAGE_ACCEPT
+ <tp:member-ref>GroupFlags</tp:member-ref> to see in which cases this
+ message should be provided.</p>
+
+ <p>Attempting to add contacts who are already members is allowed;
+ connection managers must silently accept this, without error.</p>
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotCapable"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.Channel.Full"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.Channel.InviteOnly"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.Channel.Banned"/>
+ </tp:possible-errors>
+ </method>
+
+ <method name="GetAllMembers" tp:name-for-bindings="Get_All_Members">
+ <tp:deprecated version="0.17.6">Use GetAll on the D-Bus
+ Properties D-Bus interface to get properties including Members,
+ RemotePendingMembers and LocalPendingMembers instead, falling back to
+ this method and GetLocalPendingMembersWithInfo if necessary.
+ </tp:deprecated>
+
+ <arg direction="out" type="au" tp:type="Contact_Handle[]"
+ name="Members">
+ <tp:docstring>
+ array of handles of current members
+ </tp:docstring>
+ </arg>
+ <arg direction="out" type="au" tp:type="Contact_Handle[]"
+ name="Local_Pending">
+ <tp:docstring>
+ array of handles of local pending members
+ </tp:docstring>
+ </arg>
+ <arg direction="out" type="au" tp:type="Contact_Handle[]"
+ name="Remote_Pending">
+ <tp:docstring>
+ array of handles of remote pending members
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Returns arrays of all current, local and remote pending channel
+ members.
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ </tp:possible-errors>
+ </method>
+
+ <tp:flags name="Channel_Group_Flags" value-prefix="Channel_Group_Flag" type="u">
+ <tp:flag suffix="Can_Add" value="1">
+ <tp:docstring>
+ The <tp:member-ref>AddMembers</tp:member-ref> method can be used to
+ add or invite members who are
+ not already in the local pending list (which is always valid).
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="Can_Remove" value="2">
+ <tp:docstring>
+ The <tp:member-ref>RemoveMembers</tp:member-ref> method can be used
+ to remove channel members
+ (removing those on the pending local list is always valid).
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="Can_Rescind" value="4">
+ <tp:docstring>
+ The <tp:member-ref>RemoveMembers</tp:member-ref> method can be used
+ on people on the remote
+ pending list.
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="Message_Add" value="8">
+ <tp:docstring>
+ A message may be sent to the server when calling
+ <tp:member-ref>AddMembers</tp:member-ref> on
+ contacts who are not currently pending members.
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="Message_Remove" value="16">
+ <tp:docstring>
+ A message may be sent to the server when calling
+ <tp:member-ref>RemoveMembers</tp:member-ref> on
+ contacts who are currently channel members.
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="Message_Accept" value="32">
+ <tp:docstring>
+ A message may be sent to the server when calling
+ <tp:member-ref>AddMembers</tp:member-ref> on
+ contacts who are locally pending.
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="Message_Reject" value="64">
+ <tp:docstring>
+ A message may be sent to the server when calling
+ <tp:member-ref>RemoveMembers</tp:member-ref> on
+ contacts who are locally pending.
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="Message_Rescind" value="128">
+ <tp:docstring>
+ A message may be sent to the server when calling
+ <tp:member-ref>RemoveMembers</tp:member-ref> on
+ contacts who are remote pending.
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="Channel_Specific_Handles" value="256">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>
+ The members of this group have handles which are specific to
+ this channel, and are not valid as general-purpose handles on
+ the connection. Depending on the channel, it may be possible to
+ check the <tp:member-ref>HandleOwners</tp:member-ref> property or
+ call <tp:member-ref>GetHandleOwners</tp:member-ref> to find the
+ owners of these handles, which should be done if you wish to (e.g.)
+ subscribe to the contact's presence.
+ </p>
+
+ <p>
+ Connection managers must ensure that any given handle is not
+ simultaneously a general-purpose handle and a channel-specific
+ handle.
+ </p>
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="Only_One_Group" value="512">
+ <tp:docstring>
+ Placing a contact in multiple groups of this type is not allowed
+ and will raise NotAvailable (on services where contacts may only
+ be in one user-defined group, user-defined groups will have
+ this flag).
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="Handle_Owners_Not_Available" value="1024">
+ <tp:docstring>
+ In rooms with channel specific handles (ie Channel_Specific_Handles
+ flag is set), this flag indicates that no handle owners are
+ available, apart from the owner of the
+ <tp:member-ref>SelfHandle</tp:member-ref>.
+
+ <tp:rationale>
+ This used to be an important optimization to avoid repeated
+ GetHandleOwners calls, before we introduced the
+ <tp:member-ref>HandleOwners</tp:member-ref> property and
+ <tp:member-ref>HandleOwnersChanged</tp:member-ref> signal.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="Properties" value="2048">
+ <tp:docstring>
+ This flag indicates that all the properties introduced in
+ specification 0.17.6 are fully supported.
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="Members_Changed_Detailed" value="4096">
+ <tp:docstring>
+ Indicates that <tp:member-ref>MembersChangedDetailed</tp:member-ref>
+ will be emitted for changes to this group's members in addition to
+ <tp:member-ref>MembersChanged</tp:member-ref>.
+ Clients can then connect to the former and ignore emission of the
+ latter. This flag's state MUST NOT change over the lifetime of a
+ channel.
+
+ <tp:rationale>
+ If it were allowed to change, client bindings would have to always
+ connect to MembersChanged just in case the flag ever went away (and
+ generally be unnecessarily complicated), which would mostly negate
+ the point of having this flag in the first place.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="Message_Depart" value="8192">
+ <tp:added version="0.17.21"/>
+ <tp:docstring>
+ A message may be sent to the server when calling
+ <tp:member-ref>RemoveMembers</tp:member-ref> on
+ the <tp:member-ref>SelfHandle</tp:member-ref>.
+
+ <tp:rationale>
+ This would be set for XMPP Multi-User Chat or IRC channels,
+ but not for a typical implementation of streamed media calls.
+ </tp:rationale>
+ </tp:docstring>
+ </tp:flag>
+ </tp:flags>
+
+ <property name="GroupFlags" type="u" tp:type="Channel_Group_Flags"
+ access="read" tp:name-for-bindings="Group_Flags">
+ <tp:docstring>
+ An integer representing the bitwise-OR of flags on this
+ channel. The user interface can use this to present information about
+ which operations are currently valid. Change notification is via
+ the <tp:member-ref>GroupFlagsChanged</tp:member-ref> signal.
+ </tp:docstring>
+ <tp:added version="0.17.6">For backwards compatibility,
+ clients should fall back to calling GetGroupFlags if
+ Channel_Group_Flag_Properties is not present.</tp:added>
+ </property>
+
+ <method name="GetGroupFlags" tp:name-for-bindings="Get_Group_Flags">
+ <arg direction="out" type="u" tp:type="Channel_Group_Flags"
+ name="Group_Flags">
+ <tp:docstring>
+ The value of the GroupFlags property
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Returns the value of the <tp:member-ref>GroupFlags</tp:member-ref> property.
+ </tp:docstring>
+ <tp:deprecated version="0.17.6">Use GetAll on the D-Bus
+ Properties D-Bus interface to get properties including GroupFlags
+ instead, falling back to this method if necessary.</tp:deprecated>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ </tp:possible-errors>
+ </method>
+
+ <tp:mapping name="Handle_Owner_Map">
+ <tp:docstring>
+ A map from channel-specific handles to their owners.
+ </tp:docstring>
+ <tp:added version="0.17.6">For backwards compatibility,
+ clients should fall back to calling GetHandleOwners if
+ Channel_Group_Flag_Properties is not present.</tp:added>
+
+ <tp:member type="u" name="Channel_Specific_Handle"
+ tp:type="Contact_Handle">
+ <tp:docstring>
+ A nonzero channel-specific handle
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="u" name="Global_Handle" tp:type="Contact_Handle">
+ <tp:docstring>
+ The global handle that owns the corresponding channel-specific
+ handle, or 0 if this could not be determined
+ </tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <property name="HandleOwners" type="a{uu}" tp:type="Handle_Owner_Map"
+ access="read" tp:name-for-bindings="Handle_Owners">
+ <tp:docstring>
+ A map from channel-specific handles to their owners, including
+ at least all of the channel-specific handles in this channel's members,
+ local-pending or remote-pending sets as keys. Any handle not in
+ the keys of this mapping is not channel-specific in this channel.
+ Handles which are channel-specific, but for which the owner is
+ unknown, MUST appear in this mapping with 0 as owner. Change
+ notification is via the
+ <tp:member-ref>HandleOwnersChanged</tp:member-ref> signal.
+ </tp:docstring>
+ <tp:added version="0.17.6"/>
+ </property>
+
+ <signal name="HandleOwnersChanged"
+ tp:name-for-bindings="Handle_Owners_Changed">
+ <tp:docstring>
+ Emitted whenever the <tp:member-ref>HandleOwners</tp:member-ref>
+ property changes.
+ </tp:docstring>
+ <tp:added version="0.17.6">This signal should not be relied on
+ unless Channel_Group_Flag_Properties is present.</tp:added>
+
+ <arg name="Added" type="a{uu}" tp:type="Handle_Owner_Map">
+ <tp:docstring>
+ A map from channel-specific handles to their owners, in which the
+ keys include all the handles that were added to the keys of the
+ HandleOwners property, and all the handles in that property whose
+ owner has changed
+ </tp:docstring>
+ </arg>
+ <arg name="Removed" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ The channel-specific handles that were removed from the keys of the
+ HandleOwners property, as a result of the contact leaving this group
+ in a previous <tp:member-ref>MembersChanged</tp:member-ref> signal
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <method name="GetHandleOwners" tp:name-for-bindings="Get_Handle_Owners">
+ <arg direction="in" name="Handles" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ A list of integer handles representing members of the channel
+ </tp:docstring>
+ </arg>
+ <arg direction="out" type="au" tp:type="Contact_Handle[]" name="Owners">
+ <tp:docstring>
+ An array of integer handles representing the owner handles of
+ the given room members, in the same order, or 0 if the
+ owner is not available
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ If the CHANNEL_GROUP_FLAG_CHANNEL_SPECIFIC_HANDLES flag is set on
+ the channel, then the handles of the group members are specific
+ to this channel, and are not meaningful in a connection-wide
+ context such as contact lists. This method allows you to find
+ the owner of the handle if it can be discovered in this channel,
+ or 0 if the owner is not available.
+ </tp:docstring>
+ <tp:deprecated version="0.17.6">Clients should use the
+ HandleOwners property and HandleOwnersChanged signal if
+ Channel_Group_Flag_Properties is present.</tp:deprecated>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ This channel doesn't have the CHANNEL_SPECIFIC_HANDLES flag,
+ so handles in this channel are globally meaningful and calling
+ this method is not necessary
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ One of the given handles is not a member
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <method name="GetLocalPendingMembers"
+ tp:name-for-bindings="Get_Local_Pending_Members">
+ <arg direction="out" type="au" tp:type="Contact_Handle[]"
+ name="Handles"/>
+ <tp:docstring>
+ Returns the To_Be_Added handle (only) for each structure in the
+ <tp:member-ref>LocalPendingMembers</tp:member-ref> property.
+ </tp:docstring>
+ <tp:deprecated version="0.17.6">Use the LocalPendingMembers
+ property, if Channel_Group_Flag_Properties is present.</tp:deprecated>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ </tp:possible-errors>
+ </method>
+
+ <method name="GetLocalPendingMembersWithInfo"
+ tp:name-for-bindings="Get_Local_Pending_Members_With_Info">
+ <tp:added version="0.15.0" />
+ <tp:docstring>
+ Returns the <tp:member-ref>LocalPendingMembers</tp:member-ref> property.
+ </tp:docstring>
+ <tp:deprecated version="0.17.6">Use the LocalPendingMembers
+ property, if Channel_Group_Flag_Properties is present.</tp:deprecated>
+ <arg direction="out" type="a(uuus)" tp:type="Local_Pending_Info[]"
+ name="Info">
+ <tp:docstring>
+ An array of structs containing:
+ <ul>
+ <li>
+ A handle representing the contact requesting channel membership
+ </li>
+ <li>
+ A handle representing the contact making the request, or 0 if
+ unknown
+ </li>
+ <li>
+ The reason for the request: one of the values of
+ <tp:type>Channel_Group_Change_Reason</tp:type>
+ </li>
+ <li>
+ A string message containing the reason for the request if any (or
+ blank if none)
+ </li>
+ </ul>
+ </tp:docstring>
+ </arg>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ </tp:possible-errors>
+ </method>
+
+ <property name="LocalPendingMembers" access="read"
+ type="a(uuus)" tp:type="Local_Pending_Info[]"
+ tp:name-for-bindings="Local_Pending_Members">
+ <tp:docstring>
+ An array of structs containing handles representing contacts
+ requesting channel membership and awaiting local approval with
+ <tp:member-ref>AddMembers</tp:member-ref>.
+ </tp:docstring>
+ <tp:added version="0.17.6">If Channel_Group_Flag_Properties is
+ not present, clients should fall back to using the
+ deprecated GetLocalPendingMembersWithInfo method, or fall back
+ from that to the deprecated GetAllMembers method.</tp:added>
+ </property>
+
+ <property name="Members" tp:name-for-bindings="Members"
+ access="read" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ The members of this channel.
+ </tp:docstring>
+ <tp:added version="0.17.6">If Channel_Group_Flag_Properties
+ is not set, fall back to calling GetAllMembers.</tp:added>
+ </property>
+
+ <method name="GetMembers" tp:name-for-bindings="Get_Members">
+ <arg direction="out" type="au" tp:type="Contact_Handle[]"
+ name="Handles"/>
+ <tp:docstring>
+ Returns the <tp:member-ref>Members</tp:member-ref> property.
+ </tp:docstring>
+ <tp:deprecated version="0.17.6">Use the Members
+ property, if Channel_Group_Flag_Properties is present.</tp:deprecated>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ </tp:possible-errors>
+ </method>
+
+ <property name="RemotePendingMembers" access="read" type="au"
+ tp:type="Contact_Handle[]" tp:name-for-bindings="Remote_Pending_Members">
+ <tp:docstring>
+ An array of handles representing contacts who have been
+ invited to the channel and are awaiting remote approval.
+ </tp:docstring>
+ <tp:added version="0.17.6">If Channel_Group_Flag_Properties
+ is not set, fall back to calling GetAllMembers.</tp:added>
+ </property>
+
+ <method name="GetRemotePendingMembers"
+ tp:name-for-bindings="Get_Remote_Pending_Members">
+ <arg direction="out" type="au" tp:type="Contact_Handle[]"
+ name="Handles"/>
+ <tp:docstring>
+ Returns an array of handles representing contacts who have been
+ invited to the channel and are awaiting remote approval.
+ </tp:docstring>
+ <tp:deprecated version="0.17.6">Use the
+ <tp:member-ref>RemotePendingMembers</tp:member-ref>
+ property, if Channel_Group_Flag_Properties is present.</tp:deprecated>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ </tp:possible-errors>
+ </method>
+
+ <signal name="SelfHandleChanged" tp:name-for-bindings="Self_Handle_Changed">
+ <tp:docstring>
+ Emitted whenever the <tp:member-ref>SelfHandle</tp:member-ref> property
+ changes.
+ </tp:docstring>
+ <tp:added version="0.17.6">This signal should not be relied on
+ unless Channel_Group_Flag_Properties is present.</tp:added>
+
+ <arg type="u" tp:type="Contact_Handle" name="Self_Handle">
+ <tp:docstring>
+ The new value of the SelfHandle property.
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <property name="SelfHandle" type="u" tp:type="Contact_Handle"
+ access="read" tp:name-for-bindings="Self_Handle">
+ <tp:docstring>
+ The handle for the user on this channel (which can also be a
+ local or remote pending member), or 0 if the user is not a member at
+ all (which is likely to be the case, for instance, on <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">ContactList</tp:dbus-ref>
+ channels). Note that this is different from the result of
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Connection.GetSelfHandle</tp:dbus-ref>
+ on some protocols, so the value of this handle should
+ always be used with the methods of this interface.
+ </tp:docstring>
+ <tp:added version="0.17.6">For backwards compatibility,
+ clients should fall back to calling GetSelfHandle if
+ Channel_Group_Flag_Properties is not present.</tp:added>
+ </property>
+
+ <method name="GetSelfHandle" tp:name-for-bindings="Get_Self_Handle">
+ <arg direction="out" type="u" tp:type="Contact_Handle"
+ name="Self_Handle"/>
+ <tp:docstring>
+ Returns the value of the <tp:member-ref>SelfHandle</tp:member-ref>
+ property.
+ </tp:docstring>
+ <tp:deprecated version="0.17.6">Clients should retrieve the
+ SelfHandle property using GetAll instead,
+ if Channel_Group_Flag_Properties is present.</tp:deprecated>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ </tp:possible-errors>
+ </method>
+
+ <signal name="GroupFlagsChanged" tp:name-for-bindings="Group_Flags_Changed">
+ <arg name="Added" type="u" tp:type="Channel_Group_Flags">
+ <tp:docstring>
+ A bitwise OR of the flags which have been set
+ </tp:docstring>
+ </arg>
+ <arg name="Removed" type="u" tp:type="Channel_Group_Flags">
+ <tp:docstring>
+ A bitwise OR of the flags which have been cleared
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Emitted when the flags as returned by
+ <tp:member-ref>GetGroupFlags</tp:member-ref> are changed.
+ The user interface should be updated as appropriate.
+ </tp:docstring>
+ </signal>
+
+ <tp:enum name="Channel_Group_Change_Reason" type="u">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The reason for a set of handles to move to one of
+ <tp:member-ref>Members</tp:member-ref>,
+ <tp:member-ref>LocalPendingMembers</tp:member-ref> or
+ <tp:member-ref>RemotePendingMembers</tp:member-ref>, or to be removed
+ from the group. A client may supply a reason when attempting to
+ remove members from a group with
+ <tp:member-ref>RemoveMembersWithReason</tp:member-ref>, and reasons
+ are supplied by the CM when emitting
+ <tp:member-ref>MembersChanged</tp:member-ref> and
+ <tp:member-ref>MembersChangedDetailed</tp:member-ref>. Some reason
+ codes have different meanings depending on the <var>Actor</var> in a
+ MembersChanged signal.</p>
+ </tp:docstring>
+
+ <tp:enumvalue suffix="None" value="0">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>No reason was provided for this change.</p>
+
+ <p>In particular, this reason SHOULD be used when representing
+ users joining a named chatroom in the usual way, users leaving
+ a chatroom by their own request, and normal termination of a
+ StreamedMedia call by the remote user.</p>
+
+ <p>If the <tp:member-ref>SelfHandle</tp:member-ref> is removed from
+ a group for this reason and the actor is not the SelfHandle, the
+ equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.Terminated</code>.</p>
+
+ <p>If the SelfHandle is removed from a group for this reason and
+ the actor is also the SelfHandle, the equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.Cancelled</code>.</p>
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Offline" value="1">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The change is due to a user going offline. Also used when
+ user is already offline, but this wasn't known previously.</p>
+
+ <p>If a one-to-one <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref>
+ call fails because the contact being called is offline, the
+ connection manager SHOULD indicate this by removing both the
+ <tp:member-ref>SelfHandle</tp:member-ref> and the other contact's
+ handle from the Group interface with reason Offline.</p>
+
+ <tp:rationale>
+ For 1-1 calls, the call terminates as a result of removing the
+ remote contact, so the SelfHandle should be removed at the same
+ time as the remote contact and for the same reason.
+ </tp:rationale>
+
+ <p>If a handle is removed from a group for this reason, the
+ equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.Offline</code>.</p>
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Kicked" value="2">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The change is due to a kick operation.</p>
+
+ <p>If the <tp:member-ref>SelfHandle</tp:member-ref> is removed
+ from a group for this reason, the equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.Channel.Kicked</code>.
+ </p>
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Busy" value="3">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The change is due to a busy indication.</p>
+
+ <p>If a one-to-one <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref>
+ call fails because the contact being called is busy, the
+ connection manager SHOULD indicate this by removing both the
+ <tp:member-ref>SelfHandle</tp:member-ref> and the other contact's
+ handle from the Group interface with reason Busy.</p>
+
+ <tp:rationale>
+ For 1-1 calls, the call terminates as a result of removing the
+ remote contact, so the SelfHandle should be removed at the same
+ time as the remote contact and for the same reason.
+ </tp:rationale>
+
+ <p>If the <tp:member-ref>SelfHandle</tp:member-ref> is removed
+ from a group for this reason, the equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.Busy</code>.
+ </p>
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Invited" value="4">
+ <tp:docstring>
+ The change is due to an invitation. This reason SHOULD only be used
+ when contacts are added to the remote-pending set (to indicate that
+ the contact has been invited) or to the members (to indicate that
+ the contact has accepted the invitation).
+
+ <tp:rationale>
+ Otherwise, what would it mean?
+ </tp:rationale>
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Banned" value="5">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The change is due to a kick+ban operation.</p>
+
+ <p>If the <tp:member-ref>SelfHandle</tp:member-ref> is removed
+ from a group for this reason, the equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.Channel.Banned</code>.
+ </p>
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Error" value="6">
+ <tp:docstring>
+ The change is due to an error occurring.
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Invalid_Contact" value="7">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The change is because the requested contact does not exist.</p>
+
+ <p>For instance, if the user invites a nonexistent contact to a
+ chatroom or attempts to call a nonexistent contact, this could
+ be indicated by the CM adding that contact's handle to
+ remote-pending for reason None or Invited, then removing it for
+ reason Invalid_Contact. In the case of a 1-1 StreamedMedia
+ call, the CM SHOULD remove the self handle from the Group
+ in the same signal.</p>
+
+ <tp:rationale>
+ For 1-1 calls, the call terminates as a result of removing the
+ remote contact, so the SelfHandle should be removed at the same
+ time as the remote contact and for the same reason.
+ </tp:rationale>
+
+ <p>If a contact is removed from a group for this reason, the
+ equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.DoesNotExist</code>.
+ </p>
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="No_Answer" value="8">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The change is because the requested contact did not respond.</p>
+
+ <p>If a one-to-one <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref>
+ call fails because the contact being called did not respond, or the
+ local user did not respond to an incoming call, the
+ connection manager SHOULD indicate this by removing both the
+ <tp:member-ref>SelfHandle</tp:member-ref> and the other contact's
+ handle from the Group interface with reason No_Answer.</p>
+
+ <tp:rationale>
+ Documenting existing practice.
+ </tp:rationale>
+
+ <p>If a contact is removed from a group for this reason, the
+ equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.NoAnswer</code>.
+ </p>
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Renamed" value="9">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The change is because a contact's unique identifier changed.
+ There must be exactly one handle in the removed set and exactly
+ one handle in one of the added sets. The <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface.Renaming">Renamed</tp:dbus-ref>
+ signal on the
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection.Interface">Renaming</tp:dbus-ref>
+ interface will have been emitted for the same handles,
+ shortly before this <tp:member-ref>MembersChanged</tp:member-ref> signal is emitted.</p>
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Permission_Denied" value="10">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The change is because there was no permission to contact the
+ requested handle.</p>
+
+ <p>If a contact is removed from a group for this reason, the
+ equivalent D-Bus error is
+ <code>org.freedesktop.Telepathy.Error.PermissionDenied</code>.
+ </p>
+ </tp:docstring>
+ </tp:enumvalue>
+ <tp:enumvalue suffix="Separated" value="11">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>If members are removed with this reason code, the change is
+ because the group has split into unconnected parts which can only
+ communicate within themselves (e.g. netsplits on IRC use this
+ reason code).
+ </p>
+ <p>
+ If members are added with this reason code, the change is because
+ unconnected parts of the group have rejoined. If this channel
+ carries messages (e.g. <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref>
+ or <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">Tubes</tp:dbus-ref>
+ channels) applications must
+ assume that the contacts being added are likely to have missed some
+ messages as a result of the separation, and that the contacts
+ in the group are likely to have missed some messages from the
+ contacts being added.
+ </p>
+ <p>Note that from the added contacts' perspective, they have been
+ in the group all along, and the contacts we indicate to be in
+ the group (including the local user) have just rejoined
+ the group with reason Separated. Application protocols in Tubes
+ should be prepared to cope with this situation.
+ </p>
+
+ <p>The <tp:member-ref>SelfHandle</tp:member-ref> SHOULD NOT be
+ removed from channels with this reason.</p>
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <signal name="MembersChanged" tp:name-for-bindings="Members_Changed">
+ <arg name="Message" type="s">
+ <tp:docstring>
+ A string message from the server, or blank if not
+ </tp:docstring>
+ </arg>
+ <arg name="Added" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ A list of members added to the channel
+ </tp:docstring>
+ </arg>
+ <arg name="Removed" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ A list of members removed from the channel
+ </tp:docstring>
+ </arg>
+ <arg name="Local_Pending" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ A list of members who are pending local approval
+ </tp:docstring>
+ </arg>
+ <arg name="Remote_Pending" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ A list of members who are pending remote approval
+ </tp:docstring>
+ </arg>
+ <arg name="Actor" type="u" tp:type="Contact_Handle">
+ <tp:docstring>
+ The contact handle of the person who made the change, or 0
+ if not known
+ </tp:docstring>
+ </arg>
+ <arg name="Reason" type="u" tp:type="Channel_Group_Change_Reason">
+ <tp:docstring>
+ A reason for the change
+ </tp:docstring>
+ </arg>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when contacts join any of the three lists (members, local
+ pending or remote pending) or when they leave any of the three lists.
+ There may also be a message from the server regarding this change,
+ which may be displayed to the user if desired.</p>
+
+ <p>All channel-specific handles that are mentioned in this signal
+ MUST be represented in the value of the
+ <tp:member-ref>HandleOwners</tp:member-ref> property.
+ In practice, this will mean that
+ <tp:member-ref>HandleOwnersChanged</tp:member-ref> is
+ emitted <em>before</em> emitting a MembersChanged signal in which
+ channel-specific handles are added, but that it is emitted
+ <em>after</em> emitting a MembersChanged signal in which
+ channel-specific handles are removed.</p>
+
+ <p>See <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref>
+ for an overview of how group state changes are used to indicate the
+ progress of a call.</p>
+ </tp:docstring>
+ </signal>
+
+ <tp:mapping name="Handle_Identifier_Map">
+ <tp:docstring>
+ A map from handles to the corresponding normalized string identifier.
+ </tp:docstring>
+ <tp:added version="0.17.17"/>
+
+ <tp:member type="u" name="Handle" tp:type="Contact_Handle">
+ <tp:docstring>
+ A nonzero handle
+ </tp:docstring>
+ </tp:member>
+ <tp:member type="s" name="Identifier">
+ <tp:docstring>
+ The same string that would be returned by <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>
+ for this handle.
+ </tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <signal name="MembersChangedDetailed"
+ tp:name-for-bindings="Members_Changed_Detailed">
+ <arg name="Added" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ A list of members added to the channel
+ </tp:docstring>
+ </arg>
+ <arg name="Removed" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ A list of members removed from the channel
+ </tp:docstring>
+ </arg>
+ <arg name="Local_Pending" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ A list of members who are pending local approval
+ </tp:docstring>
+ </arg>
+ <arg name="Remote_Pending" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ A list of members who are pending remote approval
+ </tp:docstring>
+ </arg>
+ <arg name="Details" type="a{sv}" tp:type="String_Variant_Map">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Information about the change, which may include the following
+ well-known keys:</p>
+
+ <dl>
+ <dt>actor (u — <tp:type>Contact_Handle</tp:type>)</dt>
+ <dd>The contact handle of the person who made the change; 0 or
+ omitted if unknown or not applicable.</dd>
+
+ <dt>change-reason (u — <tp:type>Channel_Group_Change_Reason</tp:type>)</dt>
+ <dd>A reason for the change.</dd>
+
+ <dt>contact-ids (a{us} — <tp:type>Handle_Identifier_Map</tp:type>)</dt>
+ <dd>
+ <p>The string identifiers for handles mentioned in this signal, to
+ give clients the minimal information necessary to react to the
+ event without waiting for round-trips. Connection managers
+ SHOULD include the identifiers for members added to the group and
+ for the actor (if any); they MAY omit the identifiers for handles
+ which have been removed from the group.</p>
+
+ <tp:rationale>
+ <p>On IRC, an event such as a netsplit could cause the vast
+ majority of a channel to leave. Given that clients should
+ already know the identifiers of a channel's members, including
+ potentially hundreds of strings in the netsplit signal is
+ unnecessary.</p>
+ </tp:rationale>
+
+ <p>Clients MUST NOT assume that the presence or absence of a
+ handle in this mapping is meaningful. This mapping is merely
+ an optimization for round-trip reduction, and connection
+ managers MAY add additional handles, omit some handles, or
+ omit the mapping completely.</p>
+ </dd>
+
+ <dt>message (s)</dt>
+ <dd>A string message from the server regarding the change</dd>
+
+ <dt>error (s — <tp:type>DBus_Error_Name</tp:type>)</dt>
+ <dd>A (possibly implementation-specific) DBus error describing the
+ change, providing more specific information than the
+ <tp:type>Channel_Group_Change_Reason</tp:type> enum allows. This
+ MUST only be present if it is strictly more informative than
+ 'change-reason'; if present, 'change-reason' MUST be set to the
+ closest available reason.
+
+ <tp:rationale>
+ A SIP connection manager might want to signal "402 Payment
+ required" as something more specific than Error or
+ Permission_Denied so that a SIP-aware UI could handle it
+ specially; including a namespaced error permits this to be done
+ without <tp:type>Channel_Group_Change_Reason</tp:type> being
+ extended to encompass every error any CM ever wants to report.
+ </tp:rationale>
+ </dd>
+
+ <dt>debug-message (s)</dt>
+ <dd>Debugging information on the change. SHOULD NOT be shown to
+ users in normal circumstances.</dd>
+ </dl>
+ </tp:docstring>
+ </arg>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Emitted when contacts join any of the three lists (members, local
+ pending or remote pending) or when they leave any of the three
+ lists. This signal provides a superset of the information provided by
+ <tp:member-ref>MembersChanged</tp:member-ref>;
+ if the channel's <tp:member-ref>GroupFlags</tp:member-ref>
+ contains Members_Changed_Detailed, then clients may listen exclusively
+ to this signal in preference to that signal.</p>
+
+ <p>All channel-specific handles that are mentioned in this signal
+ MUST be represented in the value of the
+ <tp:member-ref>HandleOwners</tp:member-ref> property. In practice,
+ this will mean that
+ <tp:member-ref>HandleOwnersChanged</tp:member-ref> is emitted
+ <em>before</em> emitting a MembersChangedDetailed signal in which
+ channel-specific handles are added, but that it is emitted
+ <em>after</em> emitting a MembersChangedDetailed signal in which
+ channel-specific handles are removed.</p>
+
+ <p>See <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref>
+ for an overview of how group state changes are used to indicate the
+ progress of a call.</p>
+ </tp:docstring>
+ <tp:added version="0.17.16"/>
+ </signal>
+
+ <method name="RemoveMembers" tp:name-for-bindings="Remove_Members">
+ <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ An array of contact handles to remove from the channel
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="Message" type="s">
+ <tp:docstring>
+ A string message, which can be blank if desired
+ </tp:docstring>
+ </arg>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Requests the removal of contacts from a channel, reject their
+ request for channel membership on the pending local list, or
+ rescind their invitation on the pending remote list.</p>
+
+ <p>If the <tp:member-ref>SelfHandle</tp:member-ref> is in a Group,
+ it can be removed via this method, in order to leave the group
+ gracefully. This is the recommended way to leave a chatroom, close
+ or reject a <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref>
+ call, and so on.</p>
+
+ <p>Accordingly, connection managers SHOULD support
+ doing this, regardless of the value of
+ <tp:member-ref>GroupFlags</tp:member-ref>.
+ If doing so fails with PermissionDenied, this is considered to a bug
+ in the connection manager, but clients MUST recover by falling back
+ to closing the channel with the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref>
+ method.</p>
+
+ <p>Removing any contact from the local pending list is always
+ allowed. Removing contacts other than the
+ <tp:member-ref>SelfHandle</tp:member-ref> from the channel's members
+ is allowed if and only if Channel_Group_Flag_Can_Remove is in the
+ <tp:member-ref>GroupFlags</tp:member-ref>,
+ while removing contacts other than the
+ <tp:member-ref>SelfHandle</tp:member-ref> from the remote pending list
+ is allowed if and only if Channel_Group_Flag_Can_Rescind is in the
+ <tp:member-ref>GroupFlags</tp:member-ref>.</p>
+
+ <p>A message may be provided along with the request, which will be
+ sent to the server if supported. See the
+ Channel_Group_Flag_Message_Remove,
+ Channel_Group_Flag_Message_Depart,
+ Channel_Group_Flag_Message_Reject and
+ Channel_Group_Flag_Message_Rescind
+ <tp:member-ref>GroupFlags</tp:member-ref> to see in which cases this
+ message should be provided.</p>
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
+ </tp:possible-errors>
+ </method>
+
+ <method name="RemoveMembersWithReason"
+ tp:name-for-bindings="Remove_Members_With_Reason">
+ <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]">
+ <tp:docstring>
+ An array of contact handles to remove from the channel
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="Message" type="s">
+ <tp:docstring>
+ A string message, which can be blank if desired
+ </tp:docstring>
+ </arg>
+ <arg direction="in" name="Reason" type="u"
+ tp:type="Channel_Group_Change_Reason">
+ <tp:docstring>
+ A reason for the change
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ As <tp:member-ref>RemoveMembers</tp:member-ref>, but a reason code may
+ be provided where
+ appropriate. The reason code may be ignored if the underlying
+ protocol is unable to represent the given reason.
+ </tp:docstring>
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The provided reason code was invalid.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Interface for channels which have multiple members, and where the members
+ of the channel can change during its lifetime. Your presence in the channel
+ cannot be presumed by the channel's existence (for example, a channel you
+ may request membership of but your request may not be granted).</p>
+
+ <p>This interface implements three lists: a list of current members
+ (<tp:member-ref>Members</tp:member-ref>), and two lists of local pending
+ and remote pending members
+ (<tp:member-ref>LocalPendingMembers</tp:member-ref> and
+ <tp:member-ref>RemotePendingMembers</tp:member-ref>, respectively).
+ Contacts on the remote
+ pending list have been invited to the channel, but the remote user has not
+ accepted the invitation. Contacts on the local pending list have requested
+ membership of the channel, but the local user of the framework must accept
+ their request before they may join. A single contact should never appear on
+ more than one of the three lists. The lists are empty when the channel is
+ created, and the <tp:member-ref>MembersChanged</tp:member-ref> signal
+ (and, if the channel's <tp:member-ref>GroupFlags</tp:member-ref> contains
+ Members_Changed_Detailed, the
+ <tp:member-ref>MembersChangedDetailed</tp:member-ref> signal)
+ should be emitted when information
+ is retrieved from the server, or changes occur.</p>
+
+ <p>If the <tp:member-ref>MembersChanged</tp:member-ref> or
+ <tp:member-ref>MembersChangedDetailed</tp:member-ref> signal indicates
+ that the <tp:member-ref>SelfHandle</tp:member-ref> has been removed from
+ the channel, and the channel subsequently emits <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel">Closed</tp:dbus-ref>,
+ clients SHOULD consider the details given in the MembersChanged or
+ MembersChangedDetailed signal to be the reason why the channel closed.</p>
+
+ <p>Addition of members to the channel may be requested by using
+ <tp:member-ref>AddMembers</tp:member-ref>. If
+ remote acknowledgement is required, use of the AddMembers method will cause
+ users to appear on the remote pending list. If no acknowledgement is
+ required, AddMembers will add contacts to the member list directly. If a
+ contact is awaiting authorisation on the local pending list, AddMembers
+ will grant their membership request.</p>
+
+ <p>Removal of contacts from the channel may be requested by using
+ <tp:member-ref>RemoveMembers</tp:member-ref>. If a contact is awaiting
+ authorisation on the local pending
+ list, RemoveMembers will refuse their membership request. If a contact is
+ on the remote pending list but has not yet accepted the invitation,
+ RemoveMembers will rescind the request if possible.</p>
+
+ <p>It should not be presumed that the requester of a channel implementing this
+ interface is immediately granted membership, or indeed that they are a
+ member at all, unless they appear in the list. They may, for instance,
+ be placed into the remote pending list until a connection has been
+ established or the request acknowledged remotely.</p>
+
+ <p>If the local user joins a Group channel whose members or other state
+ cannot be discovered until the user joins (e.g. many chat room
+ implementations), the connection manager should ensure that the channel
+ is, as far as possible, in a consistent state before adding the local
+ contact to the members set; until this happens, the local contact should
+ be in the remote-pending set. For instance, if the connection manager
+ queries the server to find out the initial members list for the
+ channel, it should leave the local contact in the remote-pending set
+ until it has finished receiving the initial members list.
+ </p>
+
+ <p>If the protocol provides no reliable way to tell whether the complete
+ initial members list has been received yet, the connection manager
+ should make a best-effort attempt to wait for the full list
+ (in the worst case, waiting for a suitable arbitrary timeout)
+ rather than requiring user interfaces to do so on its behalf.</p>
+ </tp:docstring>
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Interface_HTML.xml b/spec/Channel_Interface_HTML.xml
new file mode 100644
index 0000000..ad86867
--- /dev/null
+++ b/spec/Channel_Interface_HTML.xml
@@ -0,0 +1,86 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_HTML"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.</p>
+
+<p>This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+Lesser General Public License for more details.</p>
+
+<p>You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
+ </tp:license>
+ <interface
+ name="org.freedesktop.Telepathy.Channel.Interface.HTML.DRAFT"
+ tp:causes-havoc="unfinished">
+ <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Text"/>
+ <tp:requires
+ interface="org.freedesktop.Telepathy.Channel.Interface.Messages"/>
+ <tp:added version="0.17.5">(draft version, not API-stable)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This interface extends the Messages interface to support
+ capability discovery, so clients can decide what subset of HTML
+ is supported.</p>
+
+ <p>(However, the capability discovery mechanism has not been written
+ yet, so this interface MUST NOT be used. It exists only to
+ indicate what direction we intend to go in.)</p>
+
+ <tp:rationale>
+ <p>XMPP supports all of XHTML-IM, and SIP (at least theoretically)
+ supports all of XHTML. However, many protocols are more limited -
+ for instance, in MSN you can only set font properties for a
+ whole message at a time. We should not mislead users into thinking
+ they can send MSN messages where individual words are emphasized.</p>
+ </tp:rationale>
+
+ <p>If this interface is present, clients MAY send XHTML formatted text
+ in message parts with type "text/html", and SHOULD interpret
+ "text/html" message parts received in reply.</p>
+
+ <p>Client authors SHOULD pay careful attention to the security
+ considerations in XEP-0071, "XHTML-IM", to avoid exposing client users
+ to security risks. Clients MUST NOT assume that connection managers
+ will filter messages to remove unsafe HTML.</p>
+
+ <tp:rationale>
+ <p>Connection managers are the components in Telepathy that are most
+ likely to be exploitable by a remote attacker to run malicious code
+ (since they are network-facing), so any filtering that the CM does
+ might be subverted.</p>
+ </tp:rationale>
+
+ <p>To avoid misleading users, clients SHOULD only present UI for the
+ subset of HTML that is indicated to be supported by this
+ interface. It follows that clients SHOULD NOT send unsupported
+ markup to the connection manager. However, even if the connection
+ manager cannot send arbitrary XHTML, it MUST cope gracefully
+ with being given arbitrary XHTML by a client.</p>
+
+ <tp:rationale>
+ <p>Connection managers should be lenient in what they receive.</p>
+ </tp:rationale>
+
+ <p>Clients MUST NOT send HTML that is not well-formed XML, but
+ connection managers MAY signal HTML that is malformed or invalid.
+ Clients SHOULD attempt to parse messages as XHTML, but fall back
+ to using a permissive "tag-soup" HTML parser if that fails.
+ (FIXME: or should the presence of this interface imply that the
+ CM fixes up "text/html" to be XHTML? In practice that would result
+ in all the CMs having to link against libxml2 or something... the
+ rationale above no longer applies here, since dropping a malformed
+ message is "safe")</p>
+ </tp:docstring>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Interface_Hold.xml b/spec/Channel_Interface_Hold.xml
new file mode 100644
index 0000000..ef5a08f
--- /dev/null
+++ b/spec/Channel_Interface_Hold.xml
@@ -0,0 +1,222 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Hold" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright> Copyright (C) 2005-2008 Collabora Limited </tp:copyright>
+ <tp:copyright> Copyright (C) 2005-2008 Nokia Corporation </tp:copyright>
+ <tp:copyright> Copyright (C) 2006 INdT </tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.
+
+This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ </tp:license>
+
+ <interface name="org.freedesktop.Telepathy.Channel.Interface.Hold">
+ <tp:xor-requires>
+ <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/>
+ <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Call.DRAFT"/>
+ </tp:xor-requires>
+ <tp:changed version="0.17.4">first API-stable version</tp:changed>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Interface for channels where you may put the channel on hold.
+ This only makes sense for channels where
+ you are streaming media to or from the members. (To see whether the
+ other participant has put you on hold, see <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface">CallState</tp:dbus-ref>.)</p>
+
+ <p>If you place a channel on hold, this indicates that you do not wish
+ to be sent media streams by any of its members and will be ignoring
+ any media streams you continue to receive. It also requests that the
+ connection manager free up any resources that are only needed for
+ an actively used channel (e.g. in a GSM or PBX call, it will be
+ necessary to place an active call on hold before you can start
+ another call).</p>
+ </tp:docstring>
+
+ <method name="GetHoldState" tp:name-for-bindings="Get_Hold_State">
+ <tp:docstring>
+ Return whether the local user has placed the channel on hold.
+ </tp:docstring>
+
+ <arg name="HoldState" direction="out" type="u"
+ tp:type="Local_Hold_State">
+ <tp:docstring>
+ The state of the channel
+ </tp:docstring>
+ </arg>
+
+ <arg name="Reason" direction="out" type="u"
+ tp:type="Local_Hold_State_Reason">
+ <tp:docstring>
+ The reason why the channel is in that state
+ </tp:docstring>
+ </arg>
+ </method>
+
+ <signal name="HoldStateChanged" tp:name-for-bindings="Hold_State_Changed">
+ <tp:docstring>
+ Emitted to indicate that the hold state has changed for this channel.
+ This may occur as a consequence of you requesting a change with
+ <tp:member-ref>RequestHold</tp:member-ref>, or the state changing as a
+ result of a request from
+ another process.
+ </tp:docstring>
+
+ <arg name="HoldState" type="u" tp:type="Local_Hold_State">
+ <tp:docstring>
+ The state of the channel
+ </tp:docstring>
+ </arg>
+
+ <arg name="Reason" type="u" tp:type="Local_Hold_State_Reason">
+ <tp:docstring>
+ The reason for the state change
+ </tp:docstring>
+ </arg>
+ </signal>
+
+ <tp:enum name="Local_Hold_State" type="u">
+ <tp:docstring>
+ The hold state of a channel.
+ </tp:docstring>
+
+ <tp:enumvalue value="0" suffix="Unheld">
+ <tp:docstring>
+ All streams are unheld (the call is active). New channels SHOULD
+ have this hold state.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue value="1" suffix="Held">
+ <tp:docstring>
+ All streams are held (the call is on hold)
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue value="2" suffix="Pending_Hold">
+ <tp:docstring>
+ The connection manager is attempting to move to state Held, but
+ has not yet completed that operation. It is unspecified whether
+ any, all or none of the streams making up the channel are on hold.
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue value="3" suffix="Pending_Unhold">
+ <tp:docstring>
+ The connection manager is attempting to move to state Held, but
+ has not yet completed that operation. It is unspecified whether
+ any, all or none of the streams making up the channel are on hold.
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <tp:enum name="Local_Hold_State_Reason" type="u">
+ <tp:docstring>
+ The reason for a change to the Local_Hold_State. Clients MUST
+ treat unknown values as equivalent to Local_Hold_State_Reason_None.
+ </tp:docstring>
+
+ <tp:enumvalue value="0" suffix="None">
+ <tp:docstring>
+ The reason cannot be described by any of the predefined values
+ (connection managers SHOULD avoid this reason, but clients MUST
+ handle it gracefully)
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue value="1" suffix="Requested">
+ <tp:docstring>
+ The change is in response to a user request
+ </tp:docstring>
+ </tp:enumvalue>
+
+ <tp:enumvalue value="2" suffix="Resource_Not_Available">
+ <tp:docstring>
+ The change is because some resource was not available
+ </tp:docstring>
+ </tp:enumvalue>
+ </tp:enum>
+
+ <method name="RequestHold" tp:name-for-bindings="Request_Hold">
+ <arg direction="in" name="Hold" type="b">
+ <tp:docstring>
+ A boolean indicating whether or not the channel should be on hold
+ </tp:docstring>
+ </arg>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Request that the channel be put on hold (be instructed not to send
+ any media streams to you) or be taken off hold.</p>
+
+ <p>If the connection manager can immediately tell that the requested
+ state change could not possibly succeed, this method SHOULD
+ return the NotAvailable error. If the requested state is the
+ same as the current state, this method SHOULD return successfully
+ without doing anything.</p>
+
+ <p>Otherwise, this method SHOULD immediately set the hold state to
+ Local_Hold_State_Pending_Hold or Local_Hold_State_Pending_Unhold
+ (as appropriate), emitting
+ <tp:member-ref>HoldStateChanged</tp:member-ref> if this is a change,
+ and return successfully.</p>
+
+ <p>The eventual success or failure of the request is indicated by a
+ subsequent HoldStateChanged signal, changing the hold state to
+ Local_Hold_State_Held or Local_Hold_State_Unheld.</p>
+
+ <p>If the channel has multiple streams, and the connection manager
+ succeeds in changing the hold state of one stream but fails to
+ change the hold state of another, it SHOULD attempt to revert
+ all streams to their previous hold states.</p>
+
+ <p>The following state transitions SHOULD be used, where
+ appropriate:</p>
+
+ <ul>
+ <li>Successful hold:
+ (Unheld, any reason) → (Pending_Hold, Requested) →
+ (Held, Requested)
+ </li>
+ <li>Successful unhold:
+ (Held, any reason) → (Pending_Unhold, Requested) →
+ (Unheld, Requested)
+ </li>
+ <li>Attempting to unhold fails at the first attempt to acquire a
+ resource:
+ (Held, any reason) → (Pending_Unhold, Requested) →
+ (Held, Resource_Not_Available)
+ </li>
+ <li>Attempting to unhold acquires one resource, but fails to acquire
+ a second, and takes time to release the first:
+ (Held, any reason) → (Pending_Unhold, Requested) →
+ (Pending_Hold, Resource_Not_Available) →
+ (Held, Resource_Not_Available)
+ </li>
+ </ul>
+ </tp:docstring>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring>
+ The requested hold state cannot be achieved; for example,
+ if only a limited number of channels can be in the "not on hold"
+ state, attempts to exceed this number will raise NotAvailable.
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Interface_Media_Signalling.xml b/spec/Channel_Interface_Media_Signalling.xml
new file mode 100644
index 0000000..242c952
--- /dev/null
+++ b/spec/Channel_Interface_Media_Signalling.xml
@@ -0,0 +1,235 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Media_Signalling" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright> Copyright © 2005-2009 Collabora Limited </tp:copyright>
+ <tp:copyright> Copyright © 2005-2009 Nokia Corporation </tp:copyright>
+ <tp:copyright> Copyright © 2006 INdT </tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.</p>
+
+<p>This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+Lesser General Public License for more details.</p>
+
+<p>You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
+ </tp:license>
+ <interface name="org.freedesktop.Telepathy.Channel.Interface.MediaSignalling">
+ <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
+ <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface for signalling a channel containing synchronised media
+ sessions which can contain an arbitrary number of streams. The
+ presence of this interface on a Channel indicates that the connection
+ manager will not carry out the actual streaming for this channel,
+ and that the client handling the channel is responsible for doing
+ so; in most cases we recommend doing this by using the
+ telepathy-farsight library.</p>
+
+ <tp:rationale>
+ <p>Streaming audio and (particularly) video requires a high level of
+ integration with the UI, and having the connection manager act as
+ a proxy would be likely to introduce unacceptable latency. As a
+ result, audio/video streaming is offloaded into the client
+ where possible, as an exception to the general design of
+ Telepathy.</p>
+ </tp:rationale>
+
+ <p>The negotiation interface is based on the API of the
+ <a href="http://farsight.freedesktop.org/">Farsight</a> library.
+ This, in turn, is based upon the IETF MMusic ICE drafts, where
+ connections are established by signalling potential connection
+ candidates to the peer until a usable connection is found, and
+ codecs are negotiated with an SDP-style offer and answer. However,
+ the principles should be applicable to other media streaming methods
+ and the API re-used without difficulty.</p>
+
+ <p>Note that the naming conventions used in the MediaStreamHandler
+ and MediaSessionHandler interfaces are rather confusing; methods
+ have signal-like names and signals have method-like names, due to
+ the API being based rather too closely on that of Farsight. This
+ is for historical reasons and will be fixed in a future release
+ of the Telepathy specification.</p>
+ </tp:docstring>
+
+ <tp:simple-type name="Media_Session_Type" type="s">
+ <tp:docstring>The type of a media session. Currently, the only supported
+ value is "rtp".</tp:docstring>
+ </tp:simple-type>
+
+ <tp:struct name="Media_Session_Handler_Info"
+ array-name="Media_Session_Handler_Info_List">
+ <tp:docstring>A struct representing a active session handler.</tp:docstring>
+ <tp:member type="o" name="Session_Handler">
+ <tp:docstring>The object path of the session handler, which is on the
+ same bus name as the channel.</tp:docstring>
+ </tp:member>
+ <tp:member type="s" tp:type="Media_Session_Type" name="Media_Session_Type">
+ <tp:docstring>The media session's type</tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <method name="GetSessionHandlers"
+ tp:name-for-bindings="Get_Session_Handlers">
+ <arg direction="out" type="a(os)" tp:type="Media_Session_Handler_Info[]"
+ name="Session_Handlers"/>
+ <tp:docstring>
+ Returns all currently active session handlers on this channel
+ as a list of (session_handler_path, type).
+ </tp:docstring>
+ </method>
+
+ <signal name="NewSessionHandler" tp:name-for-bindings="New_Session_Handler">
+ <arg name="Session_Handler" type="o">
+ <tp:docstring>
+ Object path of the new <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy">Media.SessionHandler</tp:dbus-ref>
+ object
+ </tp:docstring>
+ </arg>
+ <arg name="Session_Type" tp:type="Media_Session_Type" type="s">
+ <tp:docstring>
+ String indicating type of session, eg &quot;rtp&quot;
+ </tp:docstring>
+ </arg>
+ <tp:docstring>
+ Signal that a session handler object has been created. The client
+ should create a session object and create streams for the streams
+ within.
+ </tp:docstring>
+ </signal>
+
+ <tp:property name="nat-traversal" type="s">
+ <tp:deprecated version="0.17.22">Use the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref>
+ property on the Media.StreamHandler, if available; use this
+ as a fallback.</tp:deprecated>
+ <tp:docstring>
+ A string indicating the NAT traversal techniques employed by the
+ streams within this channel if they do not have a <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref>
+ property. The possible values are the same as for the NATTraversal
+ property on the streams.
+ </tp:docstring>
+ </tp:property>
+
+ <tp:property name="stun-server" type="s">
+ <tp:deprecated version="0.17.22">Use the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Media.StreamHandler">STUNServers</tp:dbus-ref>
+ property on the Media.StreamHandler, if available; use this
+ as a fallback.</tp:deprecated>
+ <tp:docstring>
+ The IP address or hostname of the STUN server to use for NAT traversal
+ if the individual streams do not specify one.
+ </tp:docstring>
+ </tp:property>
+
+ <tp:property name="stun-port" type="q">
+ <tp:deprecated version="0.17.22">Use the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Media.StreamHandler">STUNServers</tp:dbus-ref>
+ property on the Media.StreamHandler, if available; use this
+ as a fallback.</tp:deprecated>
+ <tp:docstring>
+ The UDP port number to use on the provided STUN server.
+ </tp:docstring>
+ </tp:property>
+
+ <tp:property name="gtalk-p2p-relay-token" type="s">
+ <tp:deprecated version="0.17.22">XMPP connection managers
+ supporting the Google Talk relay server SHOULD make the necessary
+ HTTP requests to find a username and password, and use those
+ to populate the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Media.StreamHandler">RelayInfo</tp:dbus-ref>
+ property on the Media.StreamHandler.</tp:deprecated>
+ <tp:docstring>
+ The authentication token for use with the Google Talk peer-to-peer relay
+ server.
+ </tp:docstring>
+ </tp:property>
+
+ <tp:hct name="gtalk-p2p">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The client can implement streaming for streams whose <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref>
+ property is <code>gtalk-p2p</code>.</p>
+ </tp:docstring>
+ </tp:hct>
+
+ <tp:hct name="ice-udp">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The client can implement streaming for streams whose <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref>
+ property is <code>ice-udp</code>.</p>
+ </tp:docstring>
+ </tp:hct>
+
+ <tp:hct name="wlm-8.5">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The client can implement streaming for streams whose <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref>
+ property is <code>wlm-8.5</code>.</p>
+ </tp:docstring>
+ </tp:hct>
+
+ <tp:hct name="wlm-2009">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The client can implement streaming for streams whose <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref>
+ property is <code>wlm-2009</code>.</p>
+ </tp:docstring>
+ </tp:hct>
+
+ <tp:hct name="video/h264" is-family="yes">
+ <tp:docstring>
+ <p>The client supports media streaming with H264 (etc.).</p>
+
+ <p>This handler capability token is a one of a family
+ of similar tokens: for any other audio or video codec whose MIME
+ type is audio/<em>subtype</em> or video/<em>subtype</em>, a handler
+ capability token of this form may exist (the subtype MUST appear
+ in lower case in this context). Clients MAY support more
+ codecs than they explicitly advertise support for; clients SHOULD
+ explicitly advertise support for their preferred codec(s), and
+ for codecs like H264 that are, in practice, significant in codec
+ negotiation.</p>
+
+ <tp:rationale>
+ <p>For instance, the XMPP capability used by the Google Video
+ Chat web client to determine whether a client is compatible
+ with it requires support for H264 video, so an XMPP
+ connection manager that supports this version of Jingle should
+ not advertise the Google Video Chat capability unless there
+ is at least one installed client that declares that it supports
+ <code>video/h264</code> on StreamedMedia channels.</p>
+ </tp:rationale>
+
+ <p>For example, a client could advertise support for
+ Speex, Theora and H264 by having three
+ handler capability tokens,
+ <code>org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/audio/speex</code>,
+ <code>org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/theora</code> and
+ <code>org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/h264</code>,
+ in its <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client.Handler">Capabilities</tp:dbus-ref>
+ property.</p>
+
+ <p>Clients MAY have media signalling abilities without explicitly
+ supporting any particular codec, and connection managers SHOULD
+ support this usage.</p>
+
+ <tp:rationale>
+ <p>This is necessary to support gatewaying between two Telepathy
+ connections, in which case the available codecs might not be
+ known to the gatewaying process.</p>
+ </tp:rationale>
+ </tp:docstring>
+ </tp:hct>
+
+ </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Interface_Mergeable_Conference.xml b/spec/Channel_Interface_Mergeable_Conference.xml
new file mode 100644
index 0000000..cd606c1
--- /dev/null
+++ b/spec/Channel_Interface_Mergeable_Conference.xml
@@ -0,0 +1,110 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Mergeable_Conference"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2009 Collabora Limited</tp:copyright>
+ <tp:copyright>Copyright © 2009 Nokia Corporation</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ License as published by the Free Software Foundation; either
+ version 2.1 of the License, or (at your option) any later version.</p>
+
+ <p>This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.</p>
+
+ <p>You should have received a copy of the GNU Lesser General Public
+ License along with this library; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+ 02110-1301, USA.</p>
+ </tp:license>
+ <interface
+ name="org.freedesktop.Telepathy.Channel.Interface.MergeableConference.DRAFT"
+ tp:causes-havoc="experimental">
+ <tp:added version="0.19.0">(draft 1)</tp:added>
+ <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Conference"/>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>An interface for multi-user conference channels that can have
+ additional individual channels merged into them after they are
+ created.</p>
+
+ <tp:rationale>
+ <p>This interface addresses part of freedesktop.org <a
+ href="http://bugs.freedesktop.org/show_bug.cgi?id=24906">bug
+ #24906</a> (GSM-compatible conference calls). GSM is currently
+ the only protocol known to implement this; PBXs might implement
+ it too.</p>
+
+ <p>It might be made into a mandatory-to-implement part of Conference,
+ or kept as a separate interface, when stabilized.</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <method name="Merge"
+ tp:name-for-bindings="Merge">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Request that the given channel be incorporated into this
+ channel.</p>
+
+ <p>The given channel SHOULD be added to <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface"
+ >Conference.Channels</tp:dbus-ref> if and only if the
+ underlying protocol signals the merge in some way. It MUST NOT be
+ added to <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Interface"
+ >Conference.InitialChannels</tp:dbus-ref> (to preserve
+ immutability).</p>
+
+ <tp:rationale>
+ <p>In GSM it is possible to merge additional calls into an ongoing
+ conference.</p>
+
+ <p>In XMPP this method could be implemented to merge a 1-1 Text
+ channel into a MUC Text channel by inviting the peer from the Text
+ channel into the MUC, or to merge a 1-1 Jingle call into a Muji
+ call by inviting the peer from the Jingle call into the Muji call.
+ (MUC and Muji channels are both implemented by XMPP MUCs, with
+ Handle_Type_Room.)</p>
+ </tp:rationale>
+ </tp:docstring>
+
+ <arg direction="in" name="Channel" type="o">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A channel with the same <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel"
+ >ChannelType</tp:dbus-ref>
+ as this one, but with <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel"
+ >TargetHandleType</tp:dbus-ref> = CONTACT.</p>
+ </tp:docstring>
+ </arg>
+
+ <tp:possible-errors>
+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+ <tp:docstring>
+ The given channel isn't suitable for merging into this one: for
+ instance, it might have the wrong channel type or handle type.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
+ <tp:docstring>
+ It will never be possible to merge channels into this particular
+ conference.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ The given channel is theoretically suitable for merging into this
+ one, but that's not currently possible for some reason (for
+ instance, this SHOULD be raised if a limit on the number of
+ channels in a conference is exceeded).
+ <strong>[FIXME: PermissionDenied?]</strong>
+ </tp:docstring>
+ </tp:error>
+ </tp:possible-errors>
+ </method>
+
+ </interface>
+</node>
diff --git a/spec/Channel_Interface_Messages.xml b/spec/Channel_Interface_Messages.xml
new file mode 100644
index 0000000..62e8384
--- /dev/null
+++ b/spec/Channel_Interface_Messages.xml
@@ -0,0 +1,1433 @@
+<?xml version="1.0" ?>
+<node name="/Channel_Interface_Messages"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:copyright>Copyright © 2008–2010 Collabora Ltd.</tp:copyright>
+ <tp:copyright>Copyright © 2008–2010 Nokia Corporation</tp:copyright>
+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
+ <p>This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.</p>
+
+<p>This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+Lesser General Public License for more details.</p>
+
+<p>You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
+USA.</p>
+ </tp:license>
+ <interface
+ name="org.freedesktop.Telepathy.Channel.Interface.Messages">
+ <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.Text"/>
+ <tp:added version="0.17.16">(as stable API)</tp:added>
+
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>This interface extends the <tp:dbus-ref
+ namespace='org.freedesktop.Telepathy.Channel.Type'>Text</tp:dbus-ref>
+ interface to support more general messages, including:</p>
+
+ <ul>
+ <li>messages with attachments (like MIME multipart/mixed)</li>
+ <li>groups of alternatives (like MIME multipart/alternative)</li>
+ <li>delivery reports (which replace <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">Text.SendError</tp:dbus-ref>),
+ addding support for protocols where the message content is not echoed
+ back to the sender on failure and for receiving positive
+ acknowledgements, as well as ensuring that incoming delivery reports
+ are not lost if no client is handling the channel yet;</li>
+ <li>any extra types of message we need in future</li>
+ </ul>
+
+ <p>Incoming messages, outgoing messages, and delivery reports are all
+ represented as lists of <tp:type>Message_Part</tp:type> structures,
+ with a format reminiscent of e-mail. Messages are sent by calling
+ <tp:member-ref>SendMessage</tp:member-ref>; outgoing messages are
+ announced to other clients which may be interested in the channel by
+ the <tp:member-ref>MessageSent</tp:member-ref> signal. Incoming
+ messages and delivery reports are signalled by
+ <tp:member-ref>MessageReceived</tp:member-ref>, and are stored in the
+ the <tp:member-ref>PendingMessages</tp:member-ref> property until
+ acknowledged by calling <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type">Text.AcknowledgePendingMessages</tp:dbus-ref>.
+ Only the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref>
+ for a channel should acknowledge messages; <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client">Observer</tp:dbus-ref>s
+ (such as loggers) and <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Client">Approver</tp:dbus-ref>s
+ for the channel may listen for incoming messages, and send messages of their own, but SHOULD NOT acknowledge messages.</p>
+
+ <tp:rationale>
+ <p>If observers were allowed to acknowledge messages, then messages
+ might have been acknowledged before the handler even got to see the
+ channel, and hence could not be shown to the user.</p>
+ </tp:rationale>
+
+ <p>If this interface is present, clients that support it SHOULD
+ listen for the <tp:member-ref>MessageSent</tp:member-ref> and
+ <tp:member-ref>MessageReceived</tp:member-ref> signals, and
+ ignore the <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.Text">Sent</tp:dbus-ref>,
+ <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.Text">SendError</tp:dbus-ref>
+ and <tp:dbus-ref
+ namespace="org.freedesktop.Telepathy.Channel.Type.Text">Received</tp:dbus-ref>
+ signals on the Text interface (which are guaranteed to duplicate
+ signals from this interface).</p>
+
+ <p>Although this specification supports formatted (rich-text)
+ messages with unformatted alternatives, implementations SHOULD NOT
+ attempt to send formatted messages until the Telepathy specification
+ has also been extended to cover capability discovery for message
+ formatting.</p>
+
+ <tp:rationale>
+ We intend to expose all rich-text messages as XHTML-IM, but on some
+ protocols, formatting is an extremely limited subset of that format
+ (e.g. there are protocols where foreground/background colours, font
+ and size can be set, but only for entire messages).
+ Until we can tell UIs what controls to offer to the user, it's
+ unfriendly to offer the user controls that may have no effect.
+ </tp:rationale>
+ </tp:docstring>
+
+ <property name="SupportedContentTypes" type="as" access="read"
+ tp:name-for-bindings="Supported_Content_Types"
+ tp:immutable="yes">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A list of MIME types supported by this channel, with more preferred
+ MIME types appearing earlier in the list. The list MAY include "*/*"
+ to indicate that attachments with arbitrary MIME types can be sent.
+ This list MUST NOT be empty, since all Messages implementations
+ MUST accept messages containing a single "text/plain" part.</p>
+
+ <p>Items in this list MUST be normalized to lower-case.</p>
+
+ <p>Some examples of how this property interacts with the
+ <tp:member-ref>MessagePartSupportFlags</tp:member-ref>:</p>
+
+ <dl>
+ <dt>A simple IM implementation: only plain text messages are
+ allowed</dt>
+ <dd>SupportedContentTypes = ['text/plain'],
+ MessagePartSupportFlags = 0</dd>
+
+ <dt>Formatted text with a plain text alternative is allowed (see the
+ HTML interface draft)</dt>
+ <dd>SupportedContentTypes = ['text/html', 'text/plain'],
+ MessagePartSupportFlags = 0</dd>
+
+ <dt>JPEG or PNG images may be sent, but without any attached
+ text</dt>
+ <dd>SupportedContentTypes = ['text/plain', 'image/jpeg',
+ 'image/png'], MessagePartSupportFlags = 0</dd>
+
+ <dt>Unformatted text to which an optional JPEG or PNG image may be
+ attached</dt>
+ <dd>SupportedContentTypes = ['text/plain', 'image/jpeg',
+ 'image/png'], MessagePartSupportFlags = One_Attachment</dd>
+
+ <dt>Formatted text to which arbitrarily many images may be
+ attached</dt>
+ <dd>SupportedContentTypes = ['text/html', 'text/plain', 'image/jpeg',
+ 'image/png', 'image/x-ms-bmp'], MessagePartSupportFlags =
+ One_Attachment | Multiple_Attachments</dd>
+
+ <dt>A full SIP implementation: arbitrary MIME messages are
+ allowed</dt>
+ <dd>SupportedContentTypes = ['*/*'], MessagePartSupportFlags =
+ One_Attachment | Multiple_Attachments</dd>
+ </dl>
+ </tp:docstring>
+ </property>
+
+ <property name="MessageTypes" type="au"
+ tp:type="Channel_Text_Message_Type[]" access="read"
+ tp:name-for-bindings="Message_Types"
+ tp:immutable="yes">
+ <tp:added version="0.21.5">
+ This supersedes <tp:dbus-ref namespace="ofdT.Channel.Type.Text"
+ >GetMessageTypes</tp:dbus-ref>; fall back to that method for
+ compatibility with older connection managers.
+ </tp:added>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A list of message types which may be sent on this channel.</p>
+ </tp:docstring>
+ </property>
+
+ <property name="MessagePartSupportFlags" type="u"
+ tp:type="Message_Part_Support_Flags" access="read"
+ tp:name-for-bindings="Message_Part_Support_Flags"
+ tp:immutable="yes">
+ <tp:docstring>
+ Flags indicating the level of support for message parts on this
+ channel.
+ </tp:docstring>
+ </property>
+
+ <tp:flags name="Message_Part_Support_Flags"
+ value-prefix="Message_Part_Support_Flag" type="u">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Flags indicating the level of support for message parts on this
+ channel. They are designed such that setting more flags always
+ implies that the channel has more capabilities.</p>
+
+ <p>If no flags are set, this indicates that messages may contain
+ a single message part whose content-type is any of the types
+ from SupportedContentTypes, possibly with some alternatives.</p>
+
+ <p>There is no flag indicating support for alternatives. This is
+ because the SendMessage implementation can always accept messages
+ containing alternatives, even if the underlying protocol does not,
+ by deleting all alternatives except the first (most preferred)
+ that is supported.</p>
+
+ <tp:rationale>
+ Each of the flags so far implies the previous flag, so we could
+ have used a simple enumeration here; however, we've defined
+ the message-part support indicator as a flag set for future
+ expansion.
+ </tp:rationale>
+
+ <p>See <tp:member-ref>SupportedContentTypes</tp:member-ref> for some
+ examples.</p>
+ </tp:docstring>
+
+ <tp:flag suffix="One_Attachment" value="1">
+ <tp:docstring>
+ <tp:member-ref>SendMessage</tp:member-ref> will accept messages
+ containing a textual message body,
+ plus a single attachment of any type listed in the
+ SupportedContentTypes property. It does not make sense for this
+ flag to be set if Message_Part_Support_Flag_Data_Only is not also set
+ (because the connection manager can trivially provide an empty text
+ part if necessary).
+ </tp:docstring>
+ </tp:flag>
+ <tp:flag suffix="Multiple_Attachments" value="2">
+ <tp:docstring>
+ SendMessage will accept messages containing a textual message body,
+ plus an arbitrary number of attachments of any type listed in the
+ SupportedContentTypes property. It does not make sense for this
+ flag to be set if Message_Part_Support_Flag_One_Attachment is not
+ also set.
+ </tp:docstring>
+ </tp:flag>
+ </tp:flags>
+
+ <tp:mapping name="Message_Part" array-name="Message_Part_List"
+ array-depth="2">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Part of a message's content. In practice, this mapping never
+ appears in isolation: incoming messages are represented by a list of
+ <tp:type>Message_Part</tp:type> mappings in the
+ <tp:member-ref>MessageReceived</tp:member-ref> signal, and outgoing
+ messages are passed to <tp:member-ref>SendMessage</tp:member-ref> as
+ a list of these mappings.</p>
+
+ <p>The first part of the message contains "headers", which refer
+ to the entire message. The second and subsequent parts contain the
+ message's content, including plain text, formatted text and/or
+ attached files. Well-known keys for the header and body parts are
+ defined by the <tp:type>Message_Header_Key</tp:type> and
+ <tp:type>Message_Body_Key</tp:type> types, respectively. It is an
+ error for a connection manager to put keys referring to the message
+ as a whole in the second or subsequent Message_Part, or keys intended
+ for body parts in the first Message_Part; clients MUST recover from
+ this error by ignoring these mis-placed keys.</p>
+
+ <tp:rationale>
+ <p>Instead of representing messages as aa{sv} where the first
+ dictionary is special (a dictionary of headers), we could have
+ used a signature like (a{sv}aa{sv}) to separate out the headers
+ and the body parts.</p>
+
+ <p>However, this would make access to the messages more awkward.
+ In Python, the syntax for access to a header field would remain
+ <code>message[0]['message-type']</code>, but access to a body
+ field in the second body part would change from
+ <code>message[2]['content'] to message[1][1]['content']</code>. In
+ GLib, the message would change from being a
+ <code>GPtrArray(GHashTable)</code> to being a
+ <code>GValueArray(GHashTable, GPtrArray(GHashT