Version 0.3

It didn't take too long since 0.2.1, did it? Despite that, version 0.3 includes 200+ new commits, featuring a lot of new network job classes. In fact, the entire (non-deprecated) CS API, as defined by the newest version of The Spec, is now covered with network jobs! This means that you get full (even if low-level) access to the documented Matrix CS API - be that device and key management, or user registration, or pushrules configuration. This, of course, comes along the usual work on bugfixing and other less prominent features, while keeping memory footprint and performance under control.

GTAD

All those new jobs (and most of older ones added before 0.2.1) are actually generated code. This has been made possible thanks to GTAD - Generate Things from API Descriptions, another project of @KitsuneRal. GTAD 0.6 allows you to get code in C/C++ (and possibly other languages) for the whole CS API using OpenAPI files provided by the Matrix project and Mustache template files you define. Feel free to try it; get help at #gtad:matrix.org.

Compatibility

Version 0.3 breaks API compatibility with previous versions; unless your client used very basic functionality, you may need to adapt it to the new interface. As usual, 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.3.x will maintain the API and ABI. Version 0.4 will break either API or ABI or both.

Toolchain (see also README.md)

No changes since version 0.2 - 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.

Integration

Version 0.3 can be compiled either in static or (Linux-only so far) dynamic build configuration. QML code can use most library facilities, assuming respective types are registered - you need a shim in C/C++ for that (see the code of uMatriks for an example how to do that).

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

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:

• New network jobs (#212): GetNotificationsJob (/notifications), GetWhoIsJob (/admin/whois), GetEventContextJob (/context), SearchJob (/search), GetTurnServerJob (/voip/turn), PeekEventsJob (/peek), ReportContentJob (/report), GetOneEventJob (/events), GetMembersByRoomJob (/members) and GetJoinedMembersByRoomJob (/joined_members), jobs for /presence, /pushrules, /filter, /state, /register, /devices, /keys.
• GTAD configuration and templates have been added to the master branch; job classes are now (re-)generated on a regular basis, getting updates from the most recent (or whichever you choose for your branch) OpenAPI files. Note that the current set of job classes in the master branch is generated from QMatrixClient/matrix-doc fork rather than from vanilla files at matrix-org/matrix-doc. Details on how to use GTAD in libQMatrixClient are covered in CONTRIBUTING.md

API changes:

• Most of network job classes (specifically - all classes generated by GTAD) now reside in csapi/ instead of jobs/. A small number of manually written jobs (with better interface than the one provided by generated ones - notably, SyncJob and MediaThumbnailJob) stay in jobs/.
• If you happened to use RoomMessagesJob directly, rather than Room::getPreviousContent() - this job is no more, use GetRoomEventsJob instead.
• JoinRoomJob, while keeping the name, now resides in csapi/joining.h and accepts a slightly different set of arguments. You better use Connection::joinRoom() anyway which has been there for some time already.
• Similarly, SetRoomStateJob is now two jobs residing in csapi/room_state.h. Room::set* methods provide a more stable API for you (including the newly introduced Room::setMemberState()).
• EventsBatch<> template is dismissed, and EventsArray<> (a typedef for std::vector of event pointers) is used instead.
• Connection::createRoom now accepts QStringList instead of QVector<QString> for the list of invitees. Jobs that used to get or return QVector<QString> also use QStringList now (GetVersionsJob, e.g.).
• Connection::networkError now carries the error message and details, in case a client wants to log intermittent errors.
• Jobs in content-repo.* now return their result in data() instead of content() - a side-effect from using a unified name for single return parameters in GTAD. If you used MediaThumbnailJob and DownloadFileJob (or method wrappers in Connection and Room), you're not affected.

Smaller changes:

• Feature (#206): the library now exposes a single signal, Connection::requestFailed(), for any failure of a network job that cannot or wasn't fixed by retrying (e.g. malformed requests, trying to send a message over continuously unavailable network, not found resources etc.). Clients can use it to provide error messages to the user in a unified way; just make sure to be not too obtrusive with those.
• Feature (#211): a new Connection::loadedRoomState() signal is emitted as soon as a new room is not only created but its initial state from the nearest sync is entirely processed. This is useful, e.g., to only show the just-created room after it's been filled with some state. The library uses this signal in its own testsuite, qmc-example.
• Feature: BaseJob::statusChanged signal to track job state transitions.
• Feature: you can access isFavourite/isLowPriority as properties and isDirectChat as a function from QML.
• Enhancement: TimelineItem (the wrapper class for events stored in the Room timeline) has got a facility method viewAs<> that unwraps the event and casts it to the desired pointer type with const qualifier. Instead of writing static_cast<const WhateverEvent*>(ti->event()) you can just do ti->viewAs<WhateverEvent>() now.
• Enhancement (#207): "Consent not given" error has a special status code (BaseJob::UserConsentRequiredError); BaseJob::errorUrl() returns the consent page URL.
• Enhancement: network jobs now can be started as either as "foreground" or "background" - generally, the idea is that "foreground" network requests are directly concerned with user interaction, while background requests serve supplementary role. Connection::sync and (by default) Connection::getThumbnail start background requests; others are foreground. Quaternion uses this distinction to decide whether or not an error message from a request should be shown to the user,
• More work on improving stability and memory footprint
• More work in .md files, in particular on using GTAD.