Version 0.2

A big update over 0.1, 0.2 comes almost 5 months after the previous release. More than 300 commits have landed in the master branch since then, with 50+ feature requests and bugs closed. The primary goal was to get more Matrix features available (notably, CS API coverage is now much wider), with stability and memory footprint being the close second priority.

As the library matures, so the development process around it does. The libqmatrixclient project has been registered at a Core Infrastructure Initiative Best Practices website (under a cool number 1023=2¹⁰-1) and is now proudly wearing the badge with the Passing status.

Thanks

This release is a collective effort of: Kitsune Ral (@KitsuneRal), Roman Plášil (@Quiark), Lewis Rockliffe (@r0kk3rz) and others. Many thanks to all of you, as well as authors and users of client applications based on libQMatrixClient - your feedback is invaluable!

Compatibility

0.2 breaks API compatibility with 0.1; there's no guarantee that clients compiled with version 0.1 will compile with 0.2. See diffs in header files to track the changes and update the client code accordingly; these release notes highlight most prominent API changes.

Micro-versions in 0.2.x will maintain the API; ABI compatibility is still not enforced (the primary linkage of the library is still static).

Toolchain (see also README.md)

Qt 5.6 is the oldest supported; Qt 5.10 is recommended. GCC 5+, Clang 5+, MSVC 2015+ are officially supported; GCC 4.9.2 and Clang 3.8 still work. The library uses C++14 for the language standard now.

Integration

Same as 0.1, version 0.2 is mainly used in static build configuration but is usable as a dynamic library as well. QML code can use most library facilities, assuming respective types are registered (see the code of uMatriks for an example how to do that).

Note that the compiled library name is now capitalised as libQMatrixClient.*, following Qt's naming conventions, instead of libqmatrixclient.*.

Features

The full list of changes can be found in the commit log; you can also find the list of GitHub issues closed in the release.

New features enabled, along with key library API for them:

• Redactions
  • Processing (#117): Room::RedactionEvent, Room::replacedEvent()
  • Sending (#118): Room::redactEvent()
• Files transfer (only mxc://, no freeform URLs - see #153):
  • Downloading (#121): GetContent*Job, DownloadFileJob, Connection::getContent(), Connection::downloadFile(), Room::downloadFile(), Room::*ToDownload() (#168)
  • Uploading (#122): UploadContentJob, Connection::uploadContent(), Connection::uploadFile(), Room::uploadFile()
  • Progress tracking: Connection::upload/downloadProgress(), Room::fileTransfer*() signals family, Room::fileTransferInfo(), Room::cancelFileTransfer()
• Setting an avatar from the local file (implicitly uploads the file to content repo (#150): User::setAvatar()
• Saving the range of shown events in the room object (#151): Room::*DisplayedEvent*() accessors and signals
• Rooms creation (#34): CreateRoomJob, Connection::createRoom() and Connection::createdRoom()
• Changing the room state: SetRoomStateJob, Room::setName(), Room::setCanonicalAlias()
• Per-room user properties (display names and avatars) support (#141): almost all methods of User now get a room object as a parameter; clients are advised to add this parameter to the existing calls of User but the previous signatures work too (handling the most used display name/avatar; before it was the one last encountered in /sync response).
• Account data (#123 and #152):
  • Room tags support (#134): TagEvent, various accessors and signals (Connection::tag*() and Room::tag*()), Connection::roomsWithTag(), Room::add/removeTag(), Room::setTags(), Room::isFavourite() and Room::isLowPriority() (just because The Spec explicitly mentions these two tags)
  • Server-side read marker support (aka "m.fully_read", #183): no changes to the library read marker API, it's now automatically synchronised with the server; ReadMarkerEvent and PostReadMarkersJob for those who need to deal with the synchronisation logic
  • Direct chats support (#163): DirectChatEvent; in Connection, directChats(), directChatUsers(), addTo/removeFromDirectChats(), isDirectChat() (with the counterpart in Room), directChatsListChanged(); requestDirectChat() to get a hold of the direct chat room object (directChatAvailable() is the corresponding signal and User::requestDirectChat() is a shortcut if you have a user object at hand); alternatively, doInDirectChat() can be used for continuation-styled operations on a direct chat
  • Generic account data: Room::accountData() and Room::accountdataChanged(), SetAccountDataJob, SetAccountDataPerRoomJob
• New CS API coverage (#128, see the issue for specific class names): 3PID administration, room directory, sending typing notifications, getting protocol versions from the server, "whoami" request for access tokens - all this is in addition to operations mentioned above
• Unread messages are counted now: Room::unreadCount() (saved in cache so that clients could provide reasonably accurate estimates - "as in Slack or better" - on the next run without saving the messages themselves)
• API change: Client callbacks for SSL errors and proxy authentication (#143): NetworkAccessManager::instance() and NetworkAccessManager::sslErrors()
  • The library no more suppresses self-signed certificate errors etc. (#144), clients should explicitly process those (quotient-im/Quaternion#250 gives an example)
  • Speaking of proxy servers, clients can now use the NetworkSettings class to store network proxy settings.
• API change: all network request (job) classes now follow the camelCase naming convention (no snake_case parameters sneaking in).
• API change: initial job state is now Pending rather than NoError (this allows to distinguish between "no result yet" and "good result" but breaks clients that checked for NoError before job completion).

Other changes:

• Feature: plain text with URLs can be pretty-printed into HTML using Room::prettyPrint()
• Feature: many more Q_PROPERTYs exposed for use in QML
• Feature: Connection::room() and Connection::invitation() to get an (existing) Room object for the specified room id and join state mask; no more need to run Connection::roomMap() (that has linear complexity, btw) only to access a single room object
• Enhancement: bridged Telegram users are recognised as such, with (Telegram) suffix removed from their names
• Enhancement (#109): workaround losing connectivity due to poor Qt bearer management
• Enhancement: network requests (jobs) can now use arbitrary data streams derived from QIODevice (including local files) for the request body (enables file uploading mentioned above and other useful cases)
• Enhancement: Room and User objects now have QObject names, making them more readable in debugging views of Qt Creator and other Qt-aware IDEs
• Enhancement (#179): caching through Connection::saveState() now uses Qt's binary representation of JSON (making it unreadable but considerably faster); set "libqmatrixclient/cache_type" (also programmatically accessible through QMatrixClient::Settings or QSettings) to "json" to use the plain-text JSON format for the cache
• Enhancement (#186): network requests respect rate limiting imposed by the server and will retry according to the provided timeout (some requests fall victim to matrix-org/synapse#3054 though)
• Fix (#119): homeserver names are resolved properly
• Fix (#115): fake state events (having no state_key) do not cause state changes
• Fix (#148): prev_content is properly searched in incoming events
• Fix (#138): trying to send a (non-encrypted) message to an encrypted room will cause a complaint in the logs but no observable action; use Room::usesEncryption() and Room::encryption() to check whether the room is encrypted
• Massive work on improving stability and plugging memory leaks; the CI script on Linux and OSX now includes running qmc-example under Valgrind; CI for Windows is introduced for the library
• More documentation work, both in doc-comments and .md files