mastodon-cpp is a C++ wrapper for the Mastodon API. The library takes care of the network stuff. You submit a query and get the raw JSON. You can then put that JSON into easy to use classes.
-
TODO-list
-
Usage
-
The HTML reference can be generated with build_doc.sh
, if doxygen is installed. It is also available at tastytea.github.io/mastodon-cpp/. There are examples in examples/
.
-
Upgrading from below 0.13.0
-
-- You have to recompile all applications linking against this library.
-- We use a mutex now to guard the string that is being written to. You can get a reference to it with
Mastodon::API::http::get_mutex()
(see examples 9 and 13 for more info). This is only relevant for streams.
-
-
Upgrading from below 0.10.0
-
Mastodon::API::get
, ::get_stream
, ::post
, ::put
and ::del
don't take std::string
as parameter to API-calls anymore, only parametermap
s. The old behaviour is still supported but is deprecated and will be removed in version 1.0.0.
-
Upgrading from below 0.7.0
-
Your projects will break, sorry. Here are the important changes:
-
-- The header location has changed. They are now in
mastodon-cpp/
.
-- Specific network error messages have been replaced by 15, "Network error". You can get the exceptions from curlpp with
Mastodon::API::exceptions(true)
.
-
-
Most basic example
-
{C++}
#include <iostream>
#include <string>
#include <mastodon-cpp/mastodon-cpp.hpp>
int main()
{
Mastodon::API masto("social.example.com", "auth_token");
std::string answer;
masto.get(Mastodon::API::v1::accounts_verify_credentials, answer);
std::cout << answer << '\n';
}
Another simple example
-
Using the Easy
-class.
-
{C++}
#include <iostream>
#include <string>
#include <vector>
#include <mastodon-cpp/mastodon-cpp.hpp>
#include <mastodon-cpp/easy/all.hpp>
using Mastodon::Easy;
int main()
{
Easy masto("social.example", "");
std::string answer;
masto.get(Mastodon::API::v1::timelines_public, answer);
for (const std::string &str : Easy::json_array_to_vector(answer))
{
Easy::Status status(str);
std::cout << " " << status.account().acct() << " wrote:\n";
std::cout << status.content() << '\n';
}
}
Compiling your project
-
A project consisting of one file can be compiled as follows:
g++ -std=c++14 -lmastodon-cpp example.cpp
-
Error codes
-
mastodon-cpp will never use error codes below 11, except 0.
-
-
-Code | Explanation |
-
-0 | No error |
-
-11 | Invalid call |
-
-12 | Not implemented |
-
-13 | URL changed (HTTP 301 or 308) |
-
-14 | Aborted by user |
-
-15 | Network error (curlpp exception) |
-
-~~20~~ | ~~Failed to connect~~ |
-
-~~21~~ | ~~Couldn't resolve host~~ |
-
-~~22~~ | ~~Network is unreachable~~ |
-
-~~23~~ | ~~Transfer interrupted~~ |
-
-~~24~~ | ~~SSL error~~ |
-
-~~25~~ | ~~Timeout~~ |
-
-100 - 999 | HTTP status codes |
-
-65535 | Unknown error |
-
-
If you use a debug build, you get more verbose error messages. Errors 20-25 are no longer in use (since 0.8.9).
-
Useful links
-
-- https://github.com/tootsuite/documentation/blob/master/Using-the-API/API.md "Mastodon API reference"
-- https://github.com/tootsuite/documentation/blob/master/Using-the-API/Streaming-API.md "Mastodon streaming API reference"
-
-
Install
-
Packages
-
Every release includes packages for the package managers of Gentoo, Debian and Red Hat.
-
Gentoo
-
Put the ebuild into your local overlay and run ebuild <ebuild path> manifest
. Install with emerge mastodon-cpp
.
-
Or add my repository and install it from there.
eselect repository add tastytea git https://git.tastytea.de/repos/overlay-tastytea.git
-echo 'dev-cpp/mastodon-cpp ~amd64' >> /etc/portage/package.keywords/mastodon-cpp
-emaint sync -r tastytea
-emerge -a dev-cpp/mastodon-cpp
-
DEB and RPM
-
Prebuilt DEB and RPM packages for x86_64(amd64) are provided with each release. These packages are automatically built and not tested. Install with dpkg -i
or rpm -i
, respectively.
-
To use the DEB package on stretch, you will need libcurlpp0 from buster or jessie.
-
From source
-
Dependencies
-
-- Tested OS: Linux
-- C++ compiler (tested: gcc 6.4 / 5.4, clang 5.0)
-- cmake (tested: 3.9.6)
-- libcurl (tested: 7.58.0 / 7.35.0)
-- curlpp (tested: 0.8.1 / 0.7.3)
-- Optional
-- Easy interface & Examples: jsoncpp (tested: 1.8.1 / 1.7.2)
-- Documentation: doxygen (tested: 1.8.13)
-- DEB package: dpkg (tested: 1.19.0.5)
-- RPM package: rpm (tested: 4.11.0.1)
-
-
-
-
Get sourcecode
-
Release
-
Download the current release at GitHub.
-
Development version
-
git clone https://schlomp.space/tastytea/mastodon-cpp.git
-
Compile
-
mkdir build
-cd build/
-cmake ..
-make
-
cmake options:
-
--DCMAKE_BUILD_TYPE=Debug
for a debug build
--DWITHOUT_EASY=ON
to not build the Easy abstractions and to get rid of the jsoncpp-dependency (not recommended)
--DWITH_EXAMPLES=ON
if you want to compile the examples
--DWITH_TESTS=ON
if you want to compile the tests
--DWITH_DOC=ON
if you want to compile the HTML reference
--DWITH_DEB=ON
if you want to be able to generate a deb-package
--DWITH_RPM=ON
if you want to be able to generate an rpm-package
-
-
You can run the tests with ctest ..
inside the build directory. To install, run make install
.
-
Packages
-
Gentoo
-
Put the ebuild from packages/gentoo
into your local overlay and rename it to match the desired version or use the live-ebuild (mastodon-cpp-9999.ebuild
) to install the development version.
-
DEB and RPM
-
Compile with -DWITH_DEB=ON
or -DWITH_RPM=ON
. Run make package
from the build directory to generate a DEB/RPM package.
-
Other
-
Run make package
from the build directory to generate a tar.gz archive.
-
Status of implementation
-
Feature complete as of Mastodon 2.4.0
-
-- [x] GET /api/v1/accounts/:id
-- [x] GET /api/v1/accounts/verify_credentials
-- [x] PATCH /api/v1/accounts/update_credentials
-- [x] GET /api/v1/accounts/:id/followers
-- [x] GET /api/v1/accounts/:id/following
-- [x] GET /api/v1/accounts/:id/statuses
-- [x] POST /api/v1/accounts/:id/follow
-- [x] POST /api/v1/accounts/:id/unfollow
-- [x] POST /api/v1/accounts/:id/block
-- [x] POST /api/v1/accounts/:id/unblock
-- [x] POST /api/v1/accounts/:id/mute
-- [x] POST /api/v1/accounts/:id/unmute
-- [x] GET /api/v1/accounts/relationships
-- [x] GET /api/v1/accounts/search
-- [x] POST /api/v1/apps
-- [x] GET /api/v1/blocks
-- [x] GET /api/v1/domain_blocks
-- [x] POST /api/v1/domain_blocks
-- [x] DELETE /api/v1/domain_blocks
-- [x] GET /api/v1/favourites
-- [x] GET /api/v1/follow_requests
-- [x] POST /api/v1/follow_requests/:id/authorize
-- [x] POST /api/v1/follow_requests/:id/reject
-- [x] POST /api/v1/follows
-- [x] GET /api/v1/instance
-- [x] GET /api/v1/custom_emojis
-- [x] GET /api/v1/lists
-- [x] GET /api/v1/accounts/:id/lists
-- [x] GET /api/v1/lists/:id/accounts
-- [x] GET /api/v1/lists/:id
-- [x] POST /api/v1/lists
-- [x] PUT /api/v1/lists/:id
-- [x] DELETE /api/v1/lists/:id
-- [x] POST /api/v1/lists/:id/accounts
-- [x] DELETE /api/v1/lists/:id/accounts
-- [x] POST /api/v1/media
-- [x] PUT /api/v1/media/:id
-- [x] GET /api/v1/mutes
-- [x] GET /api/v1/notifications
-- [x] GET /api/v1/notifications/:id
-- [x] POST /api/v1/notifications/clear
-- [x] POST /api/v1/notifications/dismiss
-- [x] GET /api/v1/reports
-- [x] POST /api/v1/reports
-- [x] GET /api/v1/search
-- [x] GET /api/v1/statuses/:id
-- [x] GET /api/v1/statuses/:id/context
-- [x] GET /api/v1/statuses/:id/card
-- [x] GET /api/v1/statuses/:id/reblogged_by
-- [x] GET /api/v1/statuses/:id/favourited_by
-- [x] POST /api/v1/statuses
-- [x] DELETE /api/v1/statuses/:id
-- [x] POST /api/v1/statuses/:id/reblog
-- [x] POST /api/v1/statuses/:id/unreblog
-- [x] POST /api/v1/statuses/:id/favourite
-- [x] POST /api/v1/statuses/:id/unfavourite
-- [x] POST /api/v1/statuses/:id/pin
-- [x] POST /api/v1/statuses/:id/unpin
-- [x] POST /api/v1/statuses/:id/mute
-- [x] POST /api/v1/statuses/:id/unmute
-- [x] GET /api/v1/timelines/home
-- [x] GET /api/v1/timelines/public
-- [x] GET /api/v1/timelines/tag/:hashtag
-- [x] GET /api/v1/timelines/list/:list_id
-- [x] GET /api/v1/streaming/user
-- [x] GET /api/v1/streaming/public
-- [x] GET /api/v1/streaming/public/local
-- [x] GET /api/v1/streaming/hashtag
-- [x] GET /api/v1/streaming/list
-- [x] POST /api/v1/push/subscription
-- [x] GET /api/v1/push/subscription
-- [x] PUT /api/v1/push/subscription
-- [x] DELETE /api/v1/push/subscription
-
-
Copyright
-
Copyright © 2018 tastytea <tastytea@tastytea.de>.
-License GPLv3: GNU GPL version 3 <https://www.gnu.org/licenses/gpl-3.0.html>.
-This program comes with ABSOLUTELY NO WARRANTY. This is free software,
-and you are welcome to redistribute it under certain conditions.