This file contains the same edited highlights as the announcement emails.
For full details, see the ChangeLog in tarballs, or "git log" in Git
checkouts.

telepathy-spec 0.20.0 (2010-09-14)
==================================

This is a new stable version of telepathy-spec, intended to serve as a
reference point for future work. There were no API changes since development
release 0.19.13; changes from the year of development since 0.18.0 are
summarized below.

The versions of libraries, connection managers and Mission Control recommended
for use with GNOME 2.32 (the upcoming telepathy-glib 0.12, telepathy-gabble 0.10
and Mission Control 5.6 stable branches) can be expected to support most of
the API from this spec release.

Semantic changes
----------------

• The timestamps used for "user action time", intended for focus-stealing
  prevention, are no longer interpreted as seconds since 1970. Instead, they
  should be interpreted as X-server time on X GUI platforms,
  with two special values (0 and the maximum 64-bit signed integer) having
  their own semantics.

Enhancements to core API
------------------------

• Connection now has Status, Interfaces properties
• ConnectionManager now has Protocol objects with more information about
  protocols (at the time of release, this is supported in telepathy-gabble
  0.9.x but not in most other connection managers)
• Account.ChangingPresence indicates when changes are being attempted
• Account.Service indicates a specific service such as "google-talk"
• Account has extensible details of the last connection error
• Observers can have a Recover flag, which provides best-effort crash recovery
• ChannelDispatchOperation.HandleWithTime can pass through a timestamp for
  focus-stealing prevention
• various new error codes

New optional interfaces
-----------------------

• Account.I.Storage indicates which backend an account is stored in
• Conn.I.Anonymity, Chan.I.Anonymity — controlling caller-ID and similar
  features
• Conn.I.Balance — machine-readable account balance, e.g. SkypeOut credit
• Conn.I.Cellular — extra information about cellular connections
• Conn.I.ContactInfo — information that contacts provide about themselves,
  in a vCard-like format
• Conn.I.ServicePoint, Chan.I.ServicePoint — emergency contact points
• Chan.T.ServerTLSConnection — interactive approval of any problematic
  TLS/SSL certificates
• Chan.T.ContactSearch — searching for contacts by name, address etc.
• Chan.I.Conference — multi-user text or media conferences
  which can be made by merging or upgrading 1-1 channels
• Chan.I.SMS — SMS-specific extensions to Text channels (currently only
  one property, indicating class 0 "flash" SMSs)

Enhancements to optional interfaces
-----------------------------------

• chat states are state-recoverable
• a new flag indicates whether Location can be set

Changes since 0.19.13
---------------------

• improve wording of experimental Conn.I.ClientTypes and Conn.I.PowerSaving
  interfaces (danni, wjt)

telepathy-spec 0.19.13 (2010-09-13)
===================================

The "breadless torment" release.

New API:

• Chan.I.Conference is now considered stable, with changes since draft 1. (wjt)
  › ChannelMerged has gained Channel_Specific_Handle and Properties arguments
  › ChannelRemoved has gained a Details map similar to the one in
    MembersChangedDetailed
  › The confusing SupportsNonMerges property has been removed
  › The OriginalChannels property has been added

• Chan.T.ServerTLSConnection and its helper object
  Authentication.TLSCertificate are now considered stable, with changes since
  draft 1. (cosimoc)
  › There can now be more than one rejection reason on a TLSCertificate: the
    first is assumed to be most important

telepathy-spec 0.19.12 (2010-09-10)
===================================

The “That was the most ridiculous thing I've ever done.” “You invaded
Afghanistan.” “That wasn't just me!” release.

New API:

☎ Connection.Interface.Cellular has grown a new OverrideMessageServiceCentre
  property. This is technically an API break — MessageServiceCentre is now
  ignored unless OverrideMessageServiceCentre is set to True — but it is
  trivial to update the few components in question appropriately. (fd.o#29555,
  wjt)

☎ The sole useful property from rtcom-telepathy-glib's Channel.Interface.SMS
  (namely Flash, to signal class 0 SMSes) has been imported to a new,
  immediately-undrafted Channel.Interface.SMS. (fd.o#24907, wjt)

☎ New error code NotYet for future use in ContactList (smcv)

☎ New type Object_Immutable_Properties_Map (cassidy)

☎ channel requests' immutable properties should be passed to observers and
  handlers (cassidy)

New experimental API:

☎ Account.I.MinimumPresence draft 2 - a way to request a minimal presence on an
  account, for instance to keep an address-book sync or Tubes active when
  the user would otherwise be offline (ptlo)

☎ fd.o #26866: Protocol.I.Addressing, Conn.I.Addressing and Chan.I.Addressing,
  each draft 1 - interfaces to request contact handles based on URIs and/or
  vCard fields (eeejay)

☎ fd.o #29914: Conn.I.PowerSaving draft 1 - ability to tell connections that
  a mobile device is idle (eeejay)

☎ fd.o #25018: prototype versions of CreateChannelWithHints,
  EnsureChannelWithHints and SucceededWithChannel (wjt, cassidy, smcv)

Changes to experimental API:

☎ Conn.I.ContactList: update to draft 3 (smcv)
  ☎ rename RequestContactList back to GetContactListAttributes, and switch to
    fast-return semantics
  ☎ add Unknown and RemovedRemotely subscription states
  ☎ add ContactListState
  ☎ rename boolean flags to CanChangeContactList and ContactListPersists
  ☎ adjust semantics to make it less likely that blocked contacts appear on
    the contact list

Fixes:

☎ The handler filter examples for StreamedMedia were subtly wrong. (wjt)

☎ fd.o #27393: add <tp:token-ref>, to cross-reference contact attributes and
  handler capability tokens (smcv)

telepathy-spec 0.19.11 (2010-08-09)
===================================

The “that's what the shovel is for, sandcastles” release.

New API:

⁜ CallState has a new Conference_Host flag (wjt)

⁜ fd.o #23931: new D-Bus errors CertInsecure, CertRevoked, CertLimitExceeded,
  with corresponding Connection_Status_Reason codes (cosimoc)

New experimental API:

⁜ TLSCertificate objects and Chan.T.ServerTLSConnection (draft 1), to check
  servers' TLS certificates interactively (cosimoc)

⁜ Chan.I.Room (draft 1), to clarify chatroom identity (jonny)

⁜ Conn.I.ClientTypes (draft 1), to identify other users' client types: phone,
  handheld, PC, games console etc. (jonny)

⁜ Content and Stream have gained the usual Interfaces property (wjt)

Fixes:

⁜ Fix a cut-and-paste typo in describing the Cert.SelfSigned error and the
  corresponding Connection_Status_Change_Reason (cosimoc)

⁜ Define a serialization for all of Protocol's properties, identical to the
  one implemented in telepathy-glib (smcv)

telepathy-spec 0.19.10 (2010-07-20)
===================================

The “approved by bunny” release.

New stable API:

➡ Channel.Type.ContactSearch is now considered stable. Changes since draft 2:
  ➾ Contact_Search_Result_Map keys are string identifiers, rather than
    handles (wjt)

➡ Protocol objects are now considered stable, with no changes

➡ fd.o #25636: Messages may have a 'supersedes' header

Clarifications:

➡ Various clarifications (wjt):
  ➾ A new introduction to Channel explains immutable properties, the Requests
    interface, and the ChannelDispatcher
  ➾ A new introduction to StreamedMedia explains how to request a call, how to
    detect an incoming call, and which incoming calls should be considered
    missed
  ➾ UpdateParameters' Reconnect_Required return value now has examples

Tools changes:

➡ <tp:dbus-ref>'s namespace attribute accepts "ofdT.…" as a synonym for
  "org.freedesktop.Telepathy.…" (wjt)

telepathy-spec 0.19.9 (2010-07-12)
==================================

The “Dr Pepper is pretty rough” release.

New stable API:

☭ New Delivery_Statuses, Message_Sending_Flags and
  Delivery_Reporting_Support_Flags members for indicating messages being read
  and deleted. (Eugene Agafonov, wjt)

telepathy-spec 0.19.8 (2010-06-30)
==================================

The “to both sides, dear” release.

New stable API:

✑ fd.o #28197: Account.Interface.Storage, providing extra information regarding
  the storage backend for a particular account (eeejay)

✑ fd.o #24910: Conn.I.Cellular, extra information about cellular connections
  (compatible with draft 1, with the addition of the MessageReducedCharacterSet
  property) (wjt)

✑ fd.o #28812: Account.Service, a property containing the name of a service —
  such as "google-talk" — to provide more specific information on the nature of
  the account than just the protocol (wjt)

✑ Rationale blocks are now collapsible, if your browser supports Javascript,
  which makes the spec easier to read if you don't care about them (wjt)

✑ A new string typedef, Protocol_Content_Identifier, has been added to refer to
  the strings used for the 'identifier' field in message body parts (wjt)

✑ Arrays of Protocol_Message_Token are now specified as being possible (wjt)

Deprecations:

✑ Conn.I.Capabilities is deprecated: use Conn.I.ContactCapabilities instead.
  CMs implementing Capabilities must now also implement ContactCapabilities.
  (cassidy)

New experimental API:

✑ Protocol: new objects on a ConnectionManager, with parameter details and
  other information (smcv)

Changes to experimental API:

✑ Conn.I.ContactList: update to draft 2 (smcv)
  ✒ rename GetContactListAttributes to RequestContactList

Fixes:

✑ Messages: improve layout and clarity, and add more tp:simple-type types
  (wjt)

✑ ConnectionStatus, ConnectionStatusReason: add tp:type annotations (wjt)

telepathy-spec 0.19.7 (2010-06-14)
==================================

The "stay away from the blue" release.

New stable API:

⌖ fd.o #21200: the detailed ConnectionError signal added in 0.17.x
  is now mirrored by ConnectionError, ConnectionErrorDetails properties
  on the Account (smcv)

⌖ fd.o #24905: the ServicePoint interfaces added in 0.19.6 are now
  considered stable, with no substantive changes

⌖ fd.o #24909: the Anonymity interfaces added in 0.19.6 are now
  considered stable, with some minor changes:
  ⌁ operations that would break mandatory anonymity fail with
    a new WouldBreakAnonymity error, instead of NotAvailable (smcv)
  ⌁ the Conn.I.Anonymity.Mandatory property is now called
    Conn.I.Anonymity.AnonymityMandatory (smcv)

⌖ fd.o #24882: chat states are state-recoverable via a new ChatStates
  property (smcv)

Tools changes:

⌖ fd.o #28111: make page titles fit better in browser tabs (wjt)

⌖ Switch to shorter HTML filenames in output, which don't change when the
  interface is undrafted (smcv)

telepathy-spec 0.19.6 (2010-05-25)
==================================

The "minor bun engine" release.

Changes to stable API:

* The Account property must be set when calling AddRequest. This was already
  true whenever Mission Control called this method. (cassidy)

* The timestamps used for "user action time", which were intended for
  focus-stealing prevention, turned out not to be suitable for the intended
  purpose if they were Unix timestamps. Their semantics have been changed to
  be X server time on X GUI platforms, or undefined otherwise, with 0 and
  2**31-1 as special values. (cassidy)

New stable API:

* fd.o #28092: SupportedLocationFeatures property, with a Can_Set flag (wjt)

* Contact info is now available as a ".../info" contact attribute (andrunko)

* support for multiple/precomposed dial strings in the DTMF interface (ptlo)

* sender-nickname as a key in message headers (jonny)

* a specified serialization for Recover and BypassApproval in .client files
  (wjt)

* Account.ChangingPresence property, which is true when attempts are being
  made to change the account's presence (andrunko)

* ChannelDispatchOperation.HandleWithTime method, which is like HandleWith
  but takes a user action time argument (cassidy)

New experimental API:

* ServicePoint interfaces (draft 1) for emergency contact points (dilinger/ptlo)

* Mute interface (draft 1) for muting calls (dilinger/ptlo)

* Forwarding interface (draft 1) for call-forwarding (ptlo)

* Cellular interface (draft 1) for miscellaneous cellular-specific
  functionality (ptlo)

* Anonymity interfaces (draft 1) for anonymity enhancements such as disabling
  caller-ID (ptlo)

* ContactList and ContactGroups interfaces (draft 1) to replace the ContactList
  channel type (smcv)

Fixes:

* Add some tp:type annotations to Call where needed for telepathy-qt4
  (andrunko)

* Annotate the "...Capabilities/caps" contact attribute's tp:type correctly
  (smcv)

Tools changes:

* specparser: numerous extra sanity checks (smcv)
  - fd.o #24085: check consistency of type and tp:type
  - require types to be interoperable with telepathy-qt4 (they must either
    be on the list of types it supports specifically, or have a tp:type)
  - disallow empty structs, which are not allowed in current D-Bus
  - disallow unversioned added/deprecated/changed annotations
  - disallow <arg> with an inappropriate direction
  - disallow <tp:mapping> with fewer or more than two members

* specparser: name <tp:type>s with their short name, since conceptually they
  form a global flat namespace, and list them all in the index (smcv)

* Remove various tools that are no longer used (wjt)

telepathy-spec 0.19.5 (2010-04-15)
==================================

The "error-driven development" release.

Corrections and clarifications:

* fd.o #13350: make Contact_Info_Flags a <tp:flags> as intended, not a
  <tp:enum>

Tools changes:

* specparser: reject <tp:enum>s that look as though they should have been flags

telepathy-spec 0.19.4 (2010-04-15)
==================================

The "tastes of ACTUAL strawberry" release.

New stable API:

* fd.o #13350: ContactInfo is now considered stable. Changes since the draft
  seen in 0.18:

  - the summary explains how to use ContactInfo without causing lots of
    network traffic
  - GetContactInfo no longer re-fetches from the server, so clients can
    call it as often as they need to
  - a new RefreshContactInfo method can be used occasionally to refresh
    cached contact info
  - the Contact_Info_Flag type is now called Contact_Info_Flags
  - the examples have been extended
  - Parameters_Mandatory is now called Parameters_Exact

  (andrunko/wjt/smcv)

* fd.o #24768: Observers can have a Recover flag, which causes the
  channel dispatcher to restart them if they crash, and provides a best-effort
  way to catch up on existing channels (ptlo)

Corrections and clarifications:

* fd.o #27200: MailNotification.UnreadMails may have fewer than
  UnreadMailCount messages (for instance, Google Talk limits to 30 threads)
  (stormer)

telepathy-spec 0.19.3 (2010-03-31)
==================================

The "day's a write-off" release.

Corrections and clarifications:

* Fix the released-version annotations for 0.19.2 (smcv)

Tools changes:

* Don't allow the same mistake in future releases (smcv)

telepathy-spec 0.19.2 (2010-03-31)
==================================

Changes to stable API:

* fd.o #26837: rename Sent_Message_Token to Protocol_Message_Token (smcv)

* fd.o #27325: specify GetContactAttributes to be more tolerant (wjt)

New stable API:

* fd.o #26842: add Connection.Status, Connection.Interfaces properties (smcv)

* fd.o #26837: add a protocol-token key to Messages headers, which doesn't
  have the impractical uniqueness requirements of message-token, but is
  still a useful way to distinguish between similar messages (smcv)

* fd.o #27262: add an optional 'thumbnail' key to Messages body parts (wjt)

Corrections and clarifications:

* fd.o #27022: document .client file format correctly (smcv)

* fd.o #24252: clarify GetContactCapabilities to be consistent with
  the /capabilities contact-attribute (smcv)

* fd.o #26591: clarify InitiatorHandle's meaning on chatrooms (smcv)

* Document how to represent vCards sent via SMS on the Messages
  interface (wjt)

* fd.o #27391 (partial): document what a typical StreamedMedia Handler should
  look like (wjt)

* fd.o #27282: specify when MessageSent should be emitted (maiku/sjoerd)

Changes to experimental API:

* explicitly allow Conference.InitialChannels, InitialInviteeIDs and
  InitialInviteeHandles to be combined (smcv)

* fd.o #27335: use handler capability tokens, not InitialAudio/InitialVideo,
  to advertise support for audio/video Call channels (wjt)

New experimental API:

* add a Call.Content.Remove method (Maiku)

Tools changes:

* fd.o #26136: provide anchors for chapter headings (wjt)

* Allow <tp:hct> as an abbreviation for <tp:handler-capability-token> (wjt)

telepathy-spec 0.19.1 (2010-02-24)
==================================

The "BLINGY BLINGY envelope icon" release.

New experimental API:

* fd.o #13349: Connection.Interface.MailNotification (stormer/smcv/wjt,
  based on earlier work from oggis)

New stable API:

* added 'mxit' and 'yahoojp' to the list of well-known protocol names, and
  explicitly included SIMPLE (as seen in libpurple's prpl-simple) in the
  scope of 'sip' (smcv)

Fixes:

* fixed incorrect documentation of Call.Ringing's interaction with CallState
  (dilinger)

* fixed some incorrect formatting, resulting in more spec text
  appearing in the HTML version (smcv)

Tools changes:

* specparser now checks for text and HTML appearing outside a <tp:docstring>,
  which would prevent them from being output correctly

telepathy-spec 0.19.0 (2009-12-01)
==================================

The "horses are interesting, if brittle, animals" release.

New stable API:

* fd.o #24903: Connection.Interface.Balance, an API for machine-readable
  account balance (e.g. SkypeOut credit) (mikhailz, Naveen)

* fd.o #24938: added 'skype' (Skype) and 'tel' (telephony) to the list of
  well-known protocol names (smcv)

New experimental API:

* fd.o #24906, fd.o #24939: Conference (draft 1), an interface for multi-user
  text or media conferences that can be made by merging or upgrading 1-1
  channels (smcv)

* fd.o #24906: MergeableConference (draft 1), an extra interface for Conference
  channels that can have additional 1-1 channels merged into them

* fd.o #24906: Splittable (draft 1), an interface for 1-1 channels that can be
  removed from a Conference

* fd.o #24936: Call (draft 1), a channel type for calls (and a collection of
  subsidiary objects in the org.freedesktop.Telepathy.Call namespace),
  which will eventually replace StreamedMedia (and MediaSignalling where
  applicable) (sjoerd, smcv)

* fd.o #24661: EnsureSidecar, a method to request extra one-per-connection
  objects (conceptually the same as Connection interfaces, but implementable
  as plugins) (wjt)

Experimental API removed:

* Channel.Interface.CallMerging has been superseded by Conference and removed

Clarifications:

* fd.o #24004: specified that PreferredHandler applies even if that handler's
  filter doesn't match the channel, which has been implemented since
  telepathy-mission-control 5.3.2 (wjt)

* fd.o #24851: declared that ChatState makes no sense without Text, validating
  the decision to put ChatState API on Tp::TextChannel in telepathy-qt4 (smcv)

* fd.o #25316: specified that TargetHandleType should be a fixed property
  in all ContactCapabilities, and defined a meaning for non-CONTACT entries
  in ContactCapabilities (smcv)

* fixed some confusing typos (sjoerd, smcv)

Tools changes:

* The old single-page HTML spec has been replaced by a simple redirect to the
  multi-page version

* The spec parser correctly verifies that every method, signal and property
  has tp:name-for-bindings, which is necessary for good code generation

telepathy-spec 0.18.0 (2009-09-24)
==================================

This is a new stable version of telepathy-spec, intended to serve as a
reference point for future work. The D-Bus API is identical to 0.17.28
(the only changes were some improvements to the documentation tools, by wjt).

This spec version is supported by the upcoming 0.8.x stable branch of
telepathy-glib.

The versions of connection managers recommended for use with GNOME 2.28 and
Maemo 5 can be expected to support most of 0.18.0, with the notable exception
of ContactCapabilities (which was finished slightly too late). Connection
managers that support "most of" 0.18.0, except for ContactCapabilities, include:

* telepathy-gabble >= 0.8.0 (stable branch)
* telepathy-salut >= 0.3.10
* telepathy-sofiasip >= 0.5.18
* telepathy-haze >= 0.3.2
* telepathy-idle >= 0.1.5
* telepathy-butterfly >= 0.5.0

There have been many changes since the 0.16.0 stable release (almost two years
ago!), here's a summary:

Connection managers
-------------------

Significant API changes include:

* Several new calling conventions were introduced for StreamedMedia channels,
  while continuing to support everything that already worked. Details at:
  <http://telepathy.freedesktop.org/wiki/Requesting%20StreamedMedia%20channels>
* Channels are not guaranteed to be unique per (channel type, handle type,
  handle) triple, even if the handle type is nonzero
* Channel.Interface.Hold has changed considerably
* Text.SendError has different semantics (which match what was actually
  implemented in practice)
* GetKnownAvatarTokens' special behaviour for the self-handle has different
  semantics (which, again, match what was actually implemented)
* The allowed characters in connection manager and protocol names are
  explicitly specified to be a subset of what D-Bus would allow

New stable API includes, in no particular order:

* mandatory InitiatorHandle, InitiatorID and TargetID properties on all
  channels
* the mandatory Contacts interface on Connection, for round-trip reduction
  when inspecting batches of contacts
* the mandatory Requests interface on Connection, an extensible version of
  the old RequestChannel/ListChannels/NewChannel functionality with better
  sematics
* the SimplePresence interface on Connection, replacing Presence
* the ContactCapabilities interface on Connection, intended to replace
  Capabilities (not yet implemented in all connection managers, though)
* the Location interface on Connection, for geolocation
* StreamTube and DBusTube channels (one channel per tube), deprecating the
  Tubes channel type
* the FileTransfer channel type
* change notification for the self-handle (mainly for IRC)
* the Messages interface on Text channels, which supports extensible metadata,
  MIME-style attachments and alternatives, and extensible delivery-reports,
  and lays the foundations for future support for formatted messages
* the "rescued" and "scrollback" message flags
* removing the SelfHandle from a Group, a newly documented way to depart
  gracefully
* an optional CallState interface on StreamedMedia channels
* Hold support in MediaSignalling (and its related objects)
* the Busy presence type
* more well-known protocol names
* a Secret flag for CM parameters that represent a password, private key etc.
* CM parameters that are also D-Bus properties, and so can be changed by the
  account manager while remaining online
* the .manager file syntax (previously undocumented)
* D-Bus core Properties on several interfaces (most notably Group and Channel),
  for round-trip reduction
* Text channels that "respawn" when closed with unacknowledged messages, to
  avoid data loss on race conditions by behaving as if Close() had won the race
* the Destroyable interface, to circumvent the "respawn" mechanism and forcibly
  close a channel with possible data loss, intended for use by the
  ChannelDispatcher when no Handler can deal with a channel
* many new D-Bus error names
* the "stored" ContactList

Deprecations include:

* the Tubes channel type (use StreamTube and DBusTube instead)
* the Presence interface (use SimplePresence instead)
* RequestChannel, ListChannels and NewChannel (use Requests instead)
* handle = 0 in the Capabilities interface, which we never actually implemented
* passing clear=TRUE to Text.ListPendingMessages, which was never really safe

Account Manager
---------------

The new AccountManager service, and its AccountManager and Account objects,
replace part of the functionality of Mission Control 4's D-Bus and C API.

Mission Control 5.x provides a reference implementation of this service.

Channel Dispatcher
------------------

The new ChannelDispatcher service, and its ChannelDispatcher,
ChannelDispatchOperation and ChannelRequest objects, replace the rest of the
functionality of Mission Control 4's D-Bus and C API.

Again, Mission Control 5.x provides a reference implementation of this service.

Clients that handle channels are now expected to implement the Handler
interface, which replaces the ChannelHandler interface used by MC 4.

The concepts of Observers, Approvers and Handlers have been introduced,
together with common functionality in the Client interface. These describe
Telepathy clients which interact with channels, and can interact with the
ChannelDispatcher to provide user interfaces, logging and other functionality.

Tools and code generation
-------------------------

The canonical form of the HTML documentation generated from the XML spec is now
a multi-page document; the old single-page version is still generated, for now,
but expect it to be removed early in 0.19.

Unstable and experimental interfaces are explicitly marked as such. Various
existing interfaces that were never actually implemented have been marked as
experimental.

The spec is much more informative, with syntax for too much new stuff to
describe here.
