mastodon-cpp  0.16.1
Classes | Public Types | Public Member Functions | Static Public Member Functions | List of all members
Mastodon::API Class Reference

Class for the Mastodon API. More...

#include <mastodon-cpp.hpp>

Inheritance diagram for Mastodon::API:
Mastodon::Easy

Classes

class  http
 http class. Do not use this directly. More...
 

Public Types

enum  v1 {
  accounts_id, accounts_verify_credentials, accounts_id_followers, accounts_id_following,
  accounts_id_statuses, accounts_relationships, accounts_search, blocks,
  domain_blocks, favourites, follow_requests, instance,
  custom_emojis, lists, accounts_id_lists, lists_id_accounts,
  lists_id, mutes, notifications, notifications_id,
  reports, search, statuses_id, statuses_id_context,
  statuses_id_card, statuses_id_reblogged_by, statuses_id_favourited_by, timelines_home,
  timelines_public, timelines_tag_hashtag, timelines_list_list_id, accounts_update_credentials,
  accounts_id_follow, accounts_id_unfollow, accounts_id_block, accounts_id_unblock,
  accounts_id_mute, accounts_id_unmute, apps, follow_requests_id_authorize,
  follow_requests_id_reject, follows, media, notifications_clear,
  notifications_dismiss, statuses, statuses_id_reblog, statuses_id_unreblog,
  statuses_id_favourite, statuses_id_unfavourite, statuses_id_pin, statuses_id_unpin,
  statuses_id_mute, statuses_id_unmute, media_id, streaming_user,
  streaming_public, streaming_public_local, streaming_hashtag, streaming_list,
  push_subscription
}
 A list of all API calls. More...
 
enum  v2 { search }
 
typedef std::map< string, std::vector< string > > parametermap
 Used for passing parameters. More...
 

Public Member Functions

 API (const string &instance, const string &access_token)
 Constructs a new API object. More...
 
const void set_useragent (const string &useragent)
 Sets the useragent. Default is mastodon-cpp/version. More...
 
const string get_useragent () const
 Gets the useragent. More...
 
const string get_instance () const
 Returns the instance. More...
 
const uint_fast16_t register_app1 (const string &client_name, const string &redirect_uri, const string &scopes, const string &website, string &client_id, string &client_secret, string &url)
 Register application, step 1/2. More...
 
const uint_fast16_t register_app1 (const string &instance, const string &client_name, const string &redirect_uri, const string &scopes, const string &website, string &client_id, string &client_secret, string &url)
 
const uint_fast16_t register_app2 (const string &client_id, const string &client_secret, const string &redirect_uri, const string &code, string &access_token)
 Register application, step 2/2. More...
 
const uint_fast16_t register_app2 (const string &instance, const string &client_id, const string &client_secret, const string &redirect_uri, const string &code, string &access_token)
 
const string get_header (const string &header) const
 Gets the header from the last answer. More...
 
bool exceptions (const bool &value)
 Turn exceptions on or off. Defaults to off. More...
 
const bool exceptions () const
 Returns true if exceptions are turned on, false otherwise.
 
const void set_proxy (const string &proxy, const string &userpw="")
 Sets the proxy. More...
 
const void get_proxy (string &proxy, string &userpw) const
 For internal use. More...
 
const uint_fast16_t get (const Mastodon::API::v1 &call, string &answer)
 Make a GET request which doesn't require parameters. More...
 
const uint_fast16_t get (const Mastodon::API::v1 &call, const parametermap &parameters, string &answer)
 Make a GET request which requires parameters. More...
 
const uint_fast16_t get (const Mastodon::API::v2 &call, const parametermap &parameters, string &answer)
 Make a GET request which requires parameters. More...
 
const uint_fast16_t get (const string &call, string &answer)
 Make a custom GET request. More...
 
const uint_fast16_t get (const Mastodon::API::v1 &call, const string &argument, string &answer)
 
const uint_fast16_t get (const Mastodon::API::v1 &call, const string &argument, const parametermap &parameters, string &answer)
 
const uint_fast16_t get_stream (const Mastodon::API::v1 &call, const parametermap &parameters, string &answer, std::unique_ptr< Mastodon::API::http > &ptr)
 Make a streaming GET request. More...
 
const uint_fast16_t get_stream (const Mastodon::API::v1 &call, string &answer, std::unique_ptr< Mastodon::API::http > &ptr)
 Make a streaming GET request. More...
 
const uint_fast16_t get_stream (const string &call, string &answer, std::unique_ptr< Mastodon::API::http > &ptr)
 Make a streaming GET request. More...
 
const uint_fast16_t get_stream (const Mastodon::API::v1 &call, const string &argument, string &answer, std::unique_ptr< Mastodon::API::http > &ptr)
 
const uint_fast16_t patch (const Mastodon::API::v1 &call, const parametermap &parameters, string &answer)
 Make a PATCH request. More...
 
const uint_fast16_t post (const Mastodon::API::v1 &call, string &answer)
 Make a POST request which doesn't require parameters. More...
 
const uint_fast16_t post (const Mastodon::API::v1 &call, const parametermap &parameters, string &answer)
 Make a POST request which requires parameters. More...
 
const uint_fast16_t post (const string &call, const parametermap &parameters, string &answer)
 Make a custom POST request. More...
 
const uint_fast16_t post (const Mastodon::API::v1 &call, const string &argument, string &answer)
 
const uint_fast16_t post (const Mastodon::API::v1 &call, const string &argument, const parametermap &parameters, string &answer)
 
const uint_fast16_t put (const Mastodon::API::v1 &call, const parametermap &parameters, string &answer)
 Make a PUT request which requires a parameters. More...
 
const uint_fast16_t put (const string &call, const parametermap &parameters, string &answer)
 Make a custom PUT request. More...
 
const uint_fast16_t put (const Mastodon::API::v1 &call, const string &argument, const parametermap &parameters, string &answer)
 
const uint_fast16_t del (const Mastodon::API::v1 &call, const parametermap &parameters)
 Make a DELETE request which requires parameters. More...
 
const uint_fast16_t del (const string &call, const parametermap &parameters, string &answer)
 Make a custom DELETE request. More...
 
const uint_fast16_t del (const Mastodon::API::v1 &call, const string &argument)
 
const uint_fast16_t del (const Mastodon::API::v1 &call, const string &argument, const parametermap &parameters)
 

Static Public Member Functions

static const string urlencode (const string &str)
 Percent-encodes a string. This is done automatically, unless you make a custom request. More...
 
static const string unescape_html (const string &html)
 Replaces HTML entities with UTF-8 characters. More...
 

Detailed Description

Class for the Mastodon API.

All input is expected to be UTF-8. Binary data must be base64-encoded or a filename. It appears that media attachements can not be base64 encoded.

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 Cancelled by user
15 Network error (curlpp exception)
100 - 999 HTTP status codes
65535 Unknown error
Examples:
example01_dump_json.cpp, example02_parse_account.cpp, example03_mastocron.cpp, example04_update_credentials.cpp, example05_follow_unfollow.cpp, example06_toot_delete-toot.cpp, example07_register_app.cpp, example08_rate_limiting.cpp, example09_streaming_api.cpp, example10_simplify.cpp, example11_post_media.cpp, example12_easy_laststatus.cpp, example13_easy_stream.cpp, example14_easy_treeview.cpp, example15_proxy.cpp, and example16_account_fields.cpp.

Member Typedef Documentation

◆ parametermap

typedef std::map<string, std::vector<string> > Mastodon::API::parametermap

Used for passing parameters.

Example:

parametermap p =
{
{"field1", { "value1", "value2" } },
{"field2", { "value" } }
}

Member Enumeration Documentation

◆ v1

enum Mastodon::API::v1
strong

A list of all API calls.

The original / are substituted by _.

185  {
186  accounts_id,
187  accounts_verify_credentials,
188  accounts_id_followers,
189  accounts_id_following,
190  accounts_id_statuses,
191  accounts_relationships,
192  accounts_search,
193  blocks,
194  domain_blocks,
195  favourites,
196  follow_requests,
197  instance,
198  custom_emojis,
199  lists,
200  accounts_id_lists,
201  lists_id_accounts,
202  lists_id,
203  mutes,
204  notifications,
205  notifications_id,
206  reports,
207  search,
208  statuses_id,
209  statuses_id_context,
210  statuses_id_card,
211  statuses_id_reblogged_by,
212  statuses_id_favourited_by,
213  timelines_home,
214  timelines_public,
215  timelines_tag_hashtag,
216  timelines_list_list_id,
217  // PATCH
218  accounts_update_credentials,
219  // POST
220  accounts_id_follow,
221  accounts_id_unfollow,
222  accounts_id_block,
223  accounts_id_unblock,
224  accounts_id_mute,
225  accounts_id_unmute,
226  apps,
227  follow_requests_id_authorize,
228  follow_requests_id_reject,
229  follows,
230  media,
231  notifications_clear,
232  notifications_dismiss,
233  statuses,
234  statuses_id_reblog,
235  statuses_id_unreblog,
236  statuses_id_favourite,
237  statuses_id_unfavourite,
238  statuses_id_pin,
239  statuses_id_unpin,
240  statuses_id_mute,
241  statuses_id_unmute,
242  // PUT
243  media_id,
244  // Streaming
245  streaming_user,
246  streaming_public,
247  streaming_public_local,
248  streaming_hashtag,
249  streaming_list,
250  // Push
251  push_subscription
252  };

Constructor & Destructor Documentation

◆ API()

API::API ( const string &  instance,
const string &  access_token 
)
explicit

Constructs a new API object.

To register your application, leave access_token blank and call register_app1() and register_app2().

Parameters
instanceThe hostname of your instance
access_tokenYour access token.
Examples:
example10_simplify.cpp.
31 : _instance(instance)
32 , _access_token(access_token)
33 , _useragent(string("mastodon-cpp/") + global::version)
34 , _http(*this, instance, access_token)
35 , _exceptions(false)
36 , _proxy("")
37 , _proxy_userpw("")
38 {
39  //
40 }

Member Function Documentation

◆ del() [1/2]

const uint_fast16_t API::del ( const Mastodon::API::v1 &  call,
const parametermap &  parameters 
)

Make a DELETE request which requires parameters.

Parameters
callA call defined in Mastodon::API::v1
parametersA Mastodon::API::parametermap containing parameters
Returns
Error code.
Examples:
example06_toot_delete-toot.cpp.
25 {
26  string strcall = "";
27  string strid = "";
28 
29  // The ID is part of the path
30  const auto &it = parameters.find("id");
31  if (it != parameters.end())
32  {
33  strid = it->second[0];
34  }
35 
36  switch (call)
37  {
38  case v1::domain_blocks:
39  strcall = "/api/v1/domain_blocks";
40  break;
41  case v1::lists_id:
42  strcall = "/api/v1/lists/" + strid;
43  break;
44  case v1::lists_id_accounts:
45  strcall = "/api/v1/lists/" + strid + "/accounts";
46  break;
47  case v1::statuses_id:
48  strcall = "/api/v1/statuses/" + strid;
49  break;
50  case v1::push_subscription:
51  strcall = "/api/v1/push/subscription";
52  break;
53  default:
54  ttdebug << "ERROR: Invalid call.\n";
55  return 11;
56  break;
57  }
58 
59  string answer;
60  return del(strcall, parameters, answer);
61 }
Mastodon::API::del
const uint_fast16_t del(const Mastodon::API::v1 &call, const parametermap &parameters)
Make a DELETE request which requires parameters.
Definition: delete.cpp:23

◆ del() [2/2]

const uint_fast16_t Mastodon::API::del ( const string &  call,
const parametermap &  parameters,
string &  answer 
)

Make a custom DELETE request.

Parameters
callString in the form /api/v1/example
parametersA Mastodon::API::parametermap containing parameters
answerThe answer from the server. Usually JSON. On error an empty string.
Returns
Error code. If the URL has permanently changed, 13 is returned and answer is set to the new URL.

◆ exceptions()

bool API::exceptions ( const bool &  value)

Turn exceptions on or off. Defaults to off.

This applies to exceptions from curlpp. curlpp::RuntimeError and curlpp::LogicError.

Parameters
valuetrue for on, false for off
Returns
true if exceptions are turned on, false otherwise
266 {
267  _exceptions = value;
268  return _exceptions;
269 }

◆ get() [1/4]

const uint_fast16_t API::get ( const Mastodon::API::v1 &  call,
string &  answer 
)

Make a GET request which doesn't require parameters.

Parameters
callA call defined in Mastodon::API::v1
answerThe answer from the server. Usually JSON. On error an empty string.
Returns
Error code.
Examples:
example01_dump_json.cpp, example02_parse_account.cpp, example03_mastocron.cpp, example07_register_app.cpp, example08_rate_limiting.cpp, and example15_proxy.cpp.
202 {
203  const parametermap p;
204  return get(call, p, answer);
205 }
Mastodon::API::parametermap
std::map< string, std::vector< string > > parametermap
Used for passing parameters.
Definition: mastodon-cpp.hpp:178

◆ get() [2/4]

const uint_fast16_t API::get ( const Mastodon::API::v1 &  call,
const parametermap &  parameters,
string &  answer 
)

Make a GET request which requires parameters.

Parameters
callA call defined in Mastodon::API::v1
parametersA Mastodon::API::parametermap containing parameters
answerThe answer from the server. Usually JSON. On error an empty string.
Returns
Error code. If the URL has permanently changed, 13 is returned and answer is set to the new URL.
26 {
27  string strcall = "";
28  string strid = "";
29 
30  // The ID is part of the path
31  const auto &it = parameters.find("id");
32  if (it != parameters.end())
33  {
34  strid = it->second[0];
35  }
36 
37  switch (call)
38  {
39  case v1::accounts_verify_credentials:
40  strcall = "/api/v1/accounts/verify_credentials";
41  break;
42  case v1::blocks:
43  strcall = "/api/v1/blocks";
44  break;
45  case v1::domain_blocks:
46  strcall = "/api/v1/domain_blocks";
47  break;
48  case v1::favourites:
49  strcall = "/api/v1/favourites";
50  break;
51  case v1::follow_requests:
52  strcall = "/api/v1/follow_requests";
53  break;
54  case v1::instance:
55  strcall = "/api/v1/instance";
56  break;
57  case v1::custom_emojis:
58  strcall = "/api/v1/custom_emojis";
59  break;
60  case v1::lists:
61  strcall = "/api/v1/lists";
62  break;
63  case v1::mutes:
64  strcall = "/api/v1/mutes";
65  break;
66  case v1::notifications:
67  strcall = "/api/v1/notifications";
68  break;
69  case v1::reports:
70  strcall = "/api/v1/reports";
71  break;
72  case v1::timelines_home:
73  strcall = "/api/v1/timelines/home";
74  break;
75  case v1::timelines_public:
76  strcall = "/api/v1/timelines/public";
77  break;
78  case v1::accounts_relationships:
79  strcall = "/api/v1/accounts/relationships";
80  break;
81  case v1::accounts_id:
82  strcall = "/api/v1/accounts/" + strid;
83  break;
84  case v1::accounts_id_followers:
85  strcall = "/api/v1/accounts/" + strid + "/followers";
86  break;
87  case v1::accounts_id_following:
88  strcall = "/api/v1/accounts/" + strid + "/following";
89  break;
90  case v1::accounts_id_statuses:
91  strcall = "/api/v1/accounts/" + strid + "/statuses";
92  break;
93  case v1::accounts_search:
94  strcall = "/api/v1/accounts/search";
95  break;
96  case v1::accounts_id_lists:
97  strcall = "/api/v1/accounts/" + strid + "/lists";
98  break;
99  case v1::lists_id_accounts:
100  strcall = "/api/v1/lists/" + strid + "/accounts";
101  break;
102  case v1::lists_id:
103  strcall = "/api/v1/lists/" + strid;
104  break;
105  case v1::notifications_id:
106  strcall = "/api/v1/notifications/" + strid;
107  break;
108  case v1::search:
109  strcall = "/api/v1/search";
110  break;
111  case v1::statuses_id:
112  strcall = "/api/v1/statuses/" + strid;
113  break;
114  case v1::statuses_id_context:
115  strcall = "/api/v1/statuses/" + strid + "/context";
116  break;
117  case v1::statuses_id_card:
118  strcall = "/api/v1/statuses/" + strid + "/card";
119  break;
120  case v1::statuses_id_reblogged_by:
121  strcall = "/api/v1/statuses/" + strid + "/reblogged_by";
122  break;
123  case v1::statuses_id_favourited_by:
124  strcall = "/api/v1/statuses/" + strid + "/favourited_by";
125  break;
126  case v1::timelines_tag_hashtag:
127  {
128  // The hashtag is part of the path
129  const auto &it = parameters.find("hashtag");
130  if (it != parameters.end())
131  {
132  strcall = "/api/v1/timelines/tag/" + urlencode(it->second[0]);
133  }
134  else
135  {
136  ttdebug << "ERROR: Invalid call.\n";
137  return 11;
138  }
139  }
140  break;
141  case v1::timelines_list_list_id:
142  strcall = "/api/v1/timelines/list/" + strid;
143  break;
144  case v1::push_subscription:
145  strcall = "/api/v1/push/subscription";
146  break;
147  default:
148  ttdebug << "ERROR: Invalid call.\n";
149  return 11;
150  break;
151  }
152 
153  if (parameters.size() > 0)
154  {
155  // Delete the parameters that are already in strcall
156  parametermap newparameters = parameters;
157  newparameters.erase("id");
158  newparameters.erase("hashtag");
159  strcall += maptostr(newparameters);
160  }
161 
162  return get(strcall, answer);
163 }
Mastodon::API::urlencode
static const string urlencode(const string &str)
Percent-encodes a string. This is done automatically, unless you make a custom request.
Definition: mastodon-cpp.cpp:134
Mastodon::API::parametermap
std::map< string, std::vector< string > > parametermap
Used for passing parameters.
Definition: mastodon-cpp.hpp:178

◆ get() [3/4]

const uint_fast16_t API::get ( const Mastodon::API::v2 &  call,
const parametermap &  parameters,
string &  answer 
)

Make a GET request which requires parameters.

Since
0.16.0
167 {
168  string strcall = "";
169  string strid = "";
170 
171  // The ID is part of the path
172  const auto &it = parameters.find("id");
173  if (it != parameters.end())
174  {
175  strid = it->second[0];
176  }
177 
178  switch (call)
179  {
180  case v2::search:
181  strcall = "/api/v2/search";
182  break;
183  default:
184  ttdebug << "ERROR: Invalid call.\n";
185  return 11;
186  break;
187  }
188 
189  if (parameters.size() > 0)
190  {
191  // Delete the parameters that are already in strcall
192  parametermap newparameters = parameters;
193  newparameters.erase("id");
194  newparameters.erase("hashtag");
195  strcall += maptostr(newparameters);
196  }
197 
198  return get(strcall, answer);
199 }
Mastodon::API::parametermap
std::map< string, std::vector< string > > parametermap
Used for passing parameters.
Definition: mastodon-cpp.hpp:178

◆ get() [4/4]

const uint_fast16_t Mastodon::API::get ( const string &  call,
string &  answer 
)

Make a custom GET request.

Parameters
callString in the form /api/v1/example
answerThe answer from the server. Usually JSON. On error an empty string.
Returns
Error code. If the URL has permanently changed, 13 is returned and answer is set to the new URL.

◆ get_header()

const string API::get_header ( const string &  header) const

Gets the header from the last answer.

Parameters
headerThe header to get
Returns
The header, or "" on error.
Examples:
example08_rate_limiting.cpp.
251 {
252  string headers;
253  _http.get_headers(headers);
254  size_t startpos = headers.find(header + ':');
255  if (startpos != std::string::npos)
256  {
257  startpos = headers.find(':', startpos) + 2;
258  size_t endpos = headers.find("\r\n", startpos);
259  return headers.substr(startpos, endpos - startpos);
260  }
261 
262  return "";
263 }
Mastodon::API::http::get_headers
const void get_headers(string &headers) const
Get all headers in a string.
Definition: http.cpp:189

◆ get_instance()

const string API::get_instance ( ) const

Returns the instance.

Returns
The instance.
53 {
54  return _instance;
55 }

◆ get_proxy()

const void API::get_proxy ( string &  proxy,
string &  userpw 
) const

For internal use.

Parameters
proxyURL
userpwusername:password
Since
0.15.1
584 {
585  if (!_proxy.empty())
586  {
587  proxy = _proxy;
588  if (!_proxy_userpw.empty())
589  {
590  userpw = _proxy_userpw;
591  }
592  }
593 }

◆ get_stream() [1/3]

const uint_fast16_t API::get_stream ( const Mastodon::API::v1 &  call,
const parametermap &  parameters,
string &  answer,
std::unique_ptr< Mastodon::API::http > &  ptr 
)

Make a streaming GET request.

Parameters
callA call defined in Mastodon::API::v1
parametersA Mastodon::API::parametermap containing parameters
answerThe answer from the server. Events with JSON-payload.
ptrPointer to the http object. Can be used to call ptr->cancel_stream()
Returns
Error code. If the URL has permanently changed, 13 is returned and answer is set to the new URL.
Examples:
example09_streaming_api.cpp.
28 {
29  string strcall = "";
30 
31  switch (call)
32  {
33  case v1::streaming_user:
34  strcall = "/api/v1/streaming/user";
35  break;
36  case v1::streaming_public:
37  strcall = "/api/v1/streaming/public";
38  break;
39  case v1::streaming_public_local:
40  strcall = "/api/v1/streaming/public/local";
41  break;
42  case v1::streaming_hashtag:
43  strcall = "/api/v1/streaming/hashtag";
44  break;
45  case v1::streaming_list:
46  strcall = "/api/v1/streaming/list";
47  break;
48  default:
49  ttdebug << "ERROR: Invalid call.\n";
50  return 11;
51  break;
52  }
53 
54  if (parameters.size() > 0)
55  {
56  strcall += maptostr(parameters);
57  }
58 
59  return get_stream(strcall, answer, ptr);
60 }
Mastodon::API::get_stream
const uint_fast16_t get_stream(const Mastodon::API::v1 &call, const parametermap &parameters, string &answer, std::unique_ptr< Mastodon::API::http > &ptr)
Make a streaming GET request.
Definition: get_stream.cpp:24

◆ get_stream() [2/3]

const uint_fast16_t API::get_stream ( const Mastodon::API::v1 &  call,
string &  answer,
std::unique_ptr< Mastodon::API::http > &  ptr 
)

Make a streaming GET request.

Parameters
callA call defined in Mastodon::API::v1
answerThe answer from the server. Events with JSON-payload.
ptrPointer to the http object. Can be used to call ptr->cancel_stream()
Returns
Error code. If the URL has permanently changed, 13 is returned and answer is set to the new URL.
65 {
66  parametermap p = {};
67  return get_stream(call, p, answer, ptr);
68 }
Mastodon::API::get_stream
const uint_fast16_t get_stream(const Mastodon::API::v1 &call, const parametermap &parameters, string &answer, std::unique_ptr< Mastodon::API::http > &ptr)
Make a streaming GET request.
Definition: get_stream.cpp:24
Mastodon::API::parametermap
std::map< string, std::vector< string > > parametermap
Used for passing parameters.
Definition: mastodon-cpp.hpp:178

◆ get_stream() [3/3]

const uint_fast16_t Mastodon::API::get_stream ( const string &  call,
string &  answer,
std::unique_ptr< Mastodon::API::http > &  ptr 
)

Make a streaming GET request.

Parameters
callString in the form /api/v1/example
answerThe answer from the server. Usually JSON. On error an empty string.
ptrPointer to the http object. Can be used to call ptr->cancel_stream()
Returns
Error code. If the URL has permanently changed, 13 is returned and answer is set to the new URL.

◆ get_useragent()

const string API::get_useragent ( ) const

Gets the useragent.

Returns
The useragent.
48 {
49  return _useragent;
50 }

◆ patch()

const uint_fast16_t API::patch ( const Mastodon::API::v1 &  call,
const parametermap &  parameters,
string &  answer 
)

Make a PATCH request.

Binary data must be base64-encoded or a filename.

Parameters
callA call defined in Mastodon::API::v1
parametersA Mastodon::API::parametermap containing parameters
answerThe answer from the server. Usually JSON. On error an empty string.
Returns
Error code. If the URL has permanently changed, 13 is returned and answer is set to the new URL.
Examples:
example04_update_credentials.cpp.
27 {
28  string strcall = "";
29  switch (call)
30  {
31  case v1::accounts_update_credentials:
32  strcall = "/api/v1/accounts/update_credentials";
33  break;
34  default:
35  ttdebug << "ERROR: Invalid call.\n";
36  return 11;
37  break;
38  }
39 
40  return _http.request(API::http::method::PATCH,
41  strcall, maptoformdata(parameters), answer);
42 }

◆ post() [1/3]

const uint_fast16_t API::post ( const Mastodon::API::v1 &  call,
string &  answer 
)

Make a POST request which doesn't require parameters.

Parameters
callA call defined in Mastodon::API::v1
answerThe answer from the server. Usually JSON. On error an empty string.
Returns
Error code. If the URL has permanently changed, 13 is returned and answer is set to the new URL.
Examples:
example05_follow_unfollow.cpp, example06_toot_delete-toot.cpp, example10_simplify.cpp, and example11_post_media.cpp.
129 {
130  const parametermap p;
131  return post(call, p, answer);
132 }
Mastodon::API::post
const uint_fast16_t post(const Mastodon::API::v1 &call, string &answer)
Make a POST request which doesn&#39;t require parameters.
Definition: post.cpp:128
Mastodon::API::parametermap
std::map< string, std::vector< string > > parametermap
Used for passing parameters.
Definition: mastodon-cpp.hpp:178

◆ post() [2/3]

const uint_fast16_t API::post ( const Mastodon::API::v1 &  call,
const parametermap &  parameters,
string &  answer 
)

Make a POST request which requires parameters.

Binary data must be base64-encoded or a filename.

Parameters
callA call defined in Mastodon::API::v1
parametersA Mastodon::API::parametermap containing parameters
answerThe answer from the server. Usually JSON. On error an empty string.
Returns
Error code. If the URL has permanently changed, 13 is returned and answer is set to the new URL.
25 {
26  string strcall = "";
27  string strid = "";
28 
29  // The ID is part of the path
30  const auto &it = parameters.find("id");
31  if (it != parameters.end())
32  {
33  strid = it->second[0];
34  }
35 
36  switch (call)
37  {
38  case v1::apps:
39  strcall = "/api/v1/apps";
40  break;
41  case v1::domain_blocks:
42  strcall = "/api/v1/domain_blocks";
43  break;
44  case v1::follows:
45  strcall = "/api/v1/follows";
46  break;
47  case v1::lists:
48  strcall = "/api/v1/lists";
49  break;
50  case v1::media:
51  strcall = "/api/v1/media";
52  break;
53  case v1::notifications_clear:
54  strcall = "/api/v1/notifications/clear";
55  break;
56  case v1::notifications_dismiss:
57  strcall = "/api/v1/notifications/dismiss";
58  break;
59  case v1::reports:
60  strcall = "/api/v1/reports";
61  break;
62  case v1::statuses:
63  strcall = "/api/v1/statuses";
64  break;
65  case v1::accounts_id_follow:
66  strcall = "/api/v1/accounts/" + strid + "/follow";
67  break;
68  case v1::accounts_id_unfollow:
69  strcall = "/api/v1/accounts/" + strid + "/unfollow";
70  break;
71  case v1::accounts_id_block:
72  strcall = "/api/v1/accounts/" + strid + "/block";
73  break;
74  case v1::accounts_id_unblock:
75  strcall = "/api/v1/accounts/" + strid + "/unblock";
76  break;
77  case v1::accounts_id_mute:
78  strcall = "/api/v1/accounts/" + strid + "/mute";
79  break;
80  case v1::accounts_id_unmute:
81  strcall = "/api/v1/accounts/" + strid + "/unmute";
82  break;
83  case v1::follow_requests_id_authorize:
84  strcall = "/api/v1/folow_requests/" + strid + "/authorize";
85  break;
86  case v1::follow_requests_id_reject:
87  strcall = "/api/v1/folow_requests/" + strid + "/reject";
88  break;
89  case v1::lists_id_accounts:
90  strcall = "/api/v1/lists/" + strid + "/accounts";
91  break;
92  case v1::statuses_id_reblog:
93  strcall = "/api/v1/statuses/" + strid + "/reblog";
94  break;
95  case v1::statuses_id_unreblog:
96  strcall = "/api/v1/statuses/" + strid + "/unreblog";
97  break;
98  case v1::statuses_id_favourite:
99  strcall = "/api/v1/statuses/" + strid + "/favourite";
100  break;
101  case v1::statuses_id_unfavourite:
102  strcall = "/api/v1/statuses/" + strid + "/unfavourite";
103  break;
104  case v1::statuses_id_pin:
105  strcall = "/api/v1/statuses/" + strid + "/pin";
106  break;
107  case v1::statuses_id_unpin:
108  strcall = "/api/v1/statuses/" + strid + "/unpin";
109  break;
110  case v1::statuses_id_mute:
111  strcall = "/api/v1/statuses/" + strid + "/mute";
112  break;
113  case v1::statuses_id_unmute:
114  strcall = "/api/v1/statuses/" + strid + "/unmute";
115  break;
116  case v1::push_subscription:
117  strcall = "/api/v1/push/subscription";
118  break;
119  default:
120  ttdebug << "ERROR: Invalid call.\n";
121  return 11;
122  break;
123  }
124 
125  return post(strcall, parameters, answer);
126 }
Mastodon::API::post
const uint_fast16_t post(const Mastodon::API::v1 &call, string &answer)
Make a POST request which doesn&#39;t require parameters.
Definition: post.cpp:128

◆ post() [3/3]

const uint_fast16_t API::post ( const string &  call,
const parametermap &  parameters,
string &  answer 
)

Make a custom POST request.

Binary data must be base64-encoded or a filename.

Parameters
callString in the form /api/v1/example
parametersA Mastodon::API::parametermap containing parameters
answerThe answer from the server. Usually JSON. On error an empty string.
Returns
Error code. If the URL has permanently changed, 13 is returned and answer is set to the new URL.
136 {
137 
138  return _http.request(http::method::POST, call,
139  maptoformdata(parameters), answer);
140 }

◆ put() [1/2]

const uint_fast16_t API::put ( const Mastodon::API::v1 &  call,
const parametermap &  parameters,
string &  answer 
)

Make a PUT request which requires a parameters.

Parameters
callA call defined in Mastodon::API::v1
parametersA Mastodon::API::parametermap containing parameters
answerThe answer from the server. Usually JSON. On error an empty string.
Returns
Error code. If the URL has permanently changed, 13 is returned and answer is set to the new URL.
25 {
26  string strcall = "";
27  string strid = "";
28 
29  // The ID is part of the path
30  const auto &it = parameters.find("id");
31  if (it != parameters.end())
32  {
33  strid = it->second[0];
34  }
35 
36  switch (call)
37  {
38  case v1::lists_id:
39  strcall = "/api/v1/lists/" + strid;
40  break;
41  case v1::media_id:
42  strcall = "/api/v1/media/" + strid;
43  break;
44  case v1::push_subscription:
45  strcall = "/api/v1/push/subscription";
46  break;
47  default:
48  ttdebug << "ERROR: Invalid call.\n";
49  return 11;
50  break;
51  }
52 
53  return put(strcall, parameters, answer);
54 }
Mastodon::API::put
const uint_fast16_t put(const Mastodon::API::v1 &call, const parametermap &parameters, string &answer)
Make a PUT request which requires a parameters.
Definition: put.cpp:23

◆ put() [2/2]

const uint_fast16_t API::put ( const string &  call,
const parametermap &  parameters,
string &  answer 
)

Make a custom PUT request.

Parameters
callString in the form /api/v1/example
parametersA Mastodon::API::parametermap containing parameters
answerThe answer from the server. Usually JSON. On error an empty string.
Returns
Error code. If the URL has permanently changed, 13 is returned and answer is set to the new URL.
58 {
59 
60  return _http.request(http::method::PUT, call,
61  maptoformdata(parameters), answer);
62 }

◆ register_app1()

const uint_fast16_t API::register_app1 ( const string &  client_name,
const string &  redirect_uri,
const string &  scopes,
const string &  website,
string &  client_id,
string &  client_secret,
string &  url 
)

Register application, step 1/2.

Parameters
client_nameThe name of the application
redirect_uriurn:ietf:wg:oauth:2.0:oob for none
scopesScopes (read, write, follow, push; space separated)
websiteThe website of the application
client_idReturned
client_secretReturned
urlReturned, used to generate code for register_app2
Returns
Error code. If the URL has permanently changed, 13 is returned and url is set to the new URL.
Examples:
example07_register_app.cpp.
158 {
159  API::parametermap parameters =
160  {
161  { "client_name", { client_name } },
162  { "redirect_uris", { redirect_uri } },
163  { "scopes", { scopes } },
164  { "website", { website } }
165  };
166 
167  string answer;
168  uint_fast16_t ret = post(API::v1::apps, parameters, answer);
169 
170  if (ret == 0)
171  {
172  std::smatch match;
173  std::regex reid("client_id\":\"([0-9a-fA-F]+)\"");
174  std::regex resecret("client_secret\":\"([0-9a-fA-F]+)\"");
175 
176  std::regex_search(answer, match, reid);
177  client_id = match[1].str();
178  std::regex_search(answer, match, resecret);
179  client_secret = match[1].str();
180 
181  url = "https://" + _instance + "/oauth/authorize" +
182  "?scope=" + urlencode(scopes) + "&response_type=code" +
183  "&redirect_uri=" + urlencode(redirect_uri) +
184  "&client_id=" + client_id;
185  if (!website.empty())
186  {
187  url += "&website=" + urlencode(website);
188  }
189 
190  return 0;
191  }
192  else if (ret == 13)
193  {
194  url = answer;
195  return ret;
196  }
197  else
198  {
199  std::cerr << "Error code: " << ret << '\n';
200  return ret;
201  }
202 
203 }
Mastodon::API::urlencode
static const string urlencode(const string &str)
Percent-encodes a string. This is done automatically, unless you make a custom request.
Definition: mastodon-cpp.cpp:134
Mastodon::API::post
const uint_fast16_t post(const Mastodon::API::v1 &call, string &answer)
Make a POST request which doesn&#39;t require parameters.
Definition: post.cpp:128
Mastodon::API::parametermap
std::map< string, std::vector< string > > parametermap
Used for passing parameters.
Definition: mastodon-cpp.hpp:178

◆ register_app2()

const uint_fast16_t API::register_app2 ( const string &  client_id,
const string &  client_secret,
const string &  redirect_uri,
const string &  code,
string &  access_token 
)

Register application, step 2/2.

The access token will be used in all subsequent calls.

Parameters
client_id
client_secret
redirect_uriurn:ietf:wg:oauth:2.0:oob for none
codeThe code generated by the website
access_tokenReturned
Returns
Error code.
Examples:
example07_register_app.cpp.
220 {
221  API::parametermap parameters =
222  {
223  { "client_id", { client_id } },
224  { "client_secret", { client_secret } },
225  { "grant_type", { "authorization_code" } },
226  { "redirect_uri", { redirect_uri } },
227  { "code", { code } },
228  };
229 
230  std::string answer;
231  uint_fast16_t ret = post("/oauth/token", parameters, answer);
232  if (ret == 0)
233  {
234  std::smatch match;
235  std::regex retoken("access_token\":\"([0-9a-fA-F]+)\"");
236 
237  std::regex_search(answer, match, retoken);
238  access_token = match[1].str();
239  _access_token = access_token;
240 
241  return 0;
242  }
243  else
244  {
245  std::cerr << "Error code: " << ret << '\n';
246  return ret;
247  }
248 }
Mastodon::API::post
const uint_fast16_t post(const Mastodon::API::v1 &call, string &answer)
Make a POST request which doesn&#39;t require parameters.
Definition: post.cpp:128
Mastodon::API::parametermap
std::map< string, std::vector< string > > parametermap
Used for passing parameters.
Definition: mastodon-cpp.hpp:178

◆ set_proxy()

const void API::set_proxy ( const string &  proxy,
const string &  userpw = "" 
)

Sets the proxy.

Since mastodon-cpp is built on libcurl, it respects the same proxy environment variables. See man curl.

Parameters
proxySee man 3 CURLOPT_PROXY
userpwSee man 3 CURLOPT_PROXYUSERPWD (optional)
Since
0.15.0
Examples:
example15_proxy.cpp.
578 {
579  _proxy = proxy;
580  _proxy_userpw = userpw;
581 }

◆ set_useragent()

const void API::set_useragent ( const string &  useragent)

Sets the useragent. Default is mastodon-cpp/version.

Parameters
useragentThe useragent
Examples:
example01_dump_json.cpp, example04_update_credentials.cpp, example05_follow_unfollow.cpp, example06_toot_delete-toot.cpp, example07_register_app.cpp, example08_rate_limiting.cpp, and example09_streaming_api.cpp.
43 {
44  _useragent = useragent;
45 }

◆ unescape_html()

const string API::unescape_html ( const string &  html)
static

Replaces HTML entities with UTF-8 characters.

Supports named and numbered entities, decimal and hexadecimal.

Since
0.12.0
277 {
278  string buffer = html;
279  string output = "";
280 
281  // Used to convert int to utf-8 char
282  std::wstring_convert<std::codecvt_utf8<char32_t>, char32_t> u8c;
283  // Matches numbered entities between 1 and 8 digits, decimal or hexadecimal
284  std::regex re_entity("&#(x)?(\\d{1,8});");
285  std::smatch match;
286 
287  while (std::regex_search(buffer, match, re_entity))
288  {
289  char32_t codepoint = 0;
290  // 'x' in front of the number means it's hexadecimal, else decimal.
291  if (match[1].length() == 1)
292  {
293  codepoint = std::stoi(match[2].str(), nullptr, 16);
294  }
295  else
296  {
297  codepoint = std::stoi(match[2].str(), nullptr, 10);
298  }
299  output += match.prefix().str() + u8c.to_bytes(codepoint);
300  buffer = match.suffix().str();
301  }
302  output += buffer;
303 
304  // Source: https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_
305  // entity_references#Character_entity_references_in_HTML
306  const std::array<const std::pair<const string, const char32_t>, 258> names =
307  {{
308  { "exclamation", 0x0021 },
309  { "quot", 0x0022 },
310  { "percent", 0x0025 },
311  { "amp", 0x0026 },
312  { "apos", 0x0027 },
313  { "add", 0x002B },
314  { "lt", 0x003C },
315  { "equal", 0x003D },
316  { "gt", 0x003E },
317  { "nbsp", 0x00A0 },
318  { "iexcl", 0x00A1 },
319  { "cent", 0x00A2 },
320  { "pound", 0x00A3 },
321  { "curren", 0x00A4 },
322  { "yen", 0x00A5 },
323  { "brvbar", 0x00A6 },
324  { "sect", 0x00A7 },
325  { "uml", 0x00A8 },
326  { "copy", 0x00A9 },
327  { "ordf", 0x00AA },
328  { "laquo", 0x00AB },
329  { "not", 0x00AC },
330  { "shy", 0x00AD },
331  { "reg", 0x00AE },
332  { "macr", 0x00AF },
333  { "deg", 0x00B0 },
334  { "plusmn", 0x00B1 },
335  { "sup2", 0x00B2 },
336  { "sup3", 0x00B3 },
337  { "acute", 0x00B4 },
338  { "micro", 0x00B5 },
339  { "para", 0x00B6 },
340  { "middot", 0x00B7 },
341  { "cedil", 0x00B8 },
342  { "sup1", 0x00B9 },
343  { "ordm", 0x00BA },
344  { "raquo", 0x00BB },
345  { "frac14", 0x00BC },
346  { "frac12", 0x00BD },
347  { "frac34", 0x00BE },
348  { "iquest", 0x00BF },
349  { "Agrave", 0x00C0 },
350  { "Aacute", 0x00C1 },
351  { "Acirc", 0x00C2 },
352  { "Atilde", 0x00C3 },
353  { "Auml", 0x00C4 },
354  { "Aring", 0x00C5 },
355  { "AElig", 0x00C6 },
356  { "Ccedil", 0x00C7 },
357  { "Egrave", 0x00C8 },
358  { "Eacute", 0x00C9 },
359  { "Ecirc", 0x00CA },
360  { "Euml", 0x00CB },
361  { "Igrave", 0x00CC },
362  { "Iacute", 0x00CD },
363  { "Icirc", 0x00CE },
364  { "Iuml", 0x00CF },
365  { "ETH", 0x00D0 },
366  { "Ntilde", 0x00D1 },
367  { "Ograve", 0x00D2 },
368  { "Oacute", 0x00D3 },
369  { "Ocirc", 0x00D4 },
370  { "Otilde", 0x00D5 },
371  { "Ouml", 0x00D6 },
372  { "times", 0x00D7 },
373  { "Oslash", 0x00D8 },
374  { "Ugrave", 0x00D9 },
375  { "Uacute", 0x00DA },
376  { "Ucirc", 0x00DB },
377  { "Uuml", 0x00DC },
378  { "Yacute", 0x00DD },
379  { "THORN", 0x00DE },
380  { "szlig", 0x00DF },
381  { "agrave", 0x00E0 },
382  { "aacute", 0x00E1 },
383  { "acirc", 0x00E2 },
384  { "atilde", 0x00E3 },
385  { "auml", 0x00E4 },
386  { "aring", 0x00E5 },
387  { "aelig", 0x00E6 },
388  { "ccedil", 0x00E7 },
389  { "egrave", 0x00E8 },
390  { "eacute", 0x00E9 },
391  { "ecirc", 0x00EA },
392  { "euml", 0x00EB },
393  { "igrave", 0x00EC },
394  { "iacute", 0x00ED },
395  { "icirc", 0x00EE },
396  { "iuml", 0x00EF },
397  { "eth", 0x00F0 },
398  { "ntilde", 0x00F1 },
399  { "ograve", 0x00F2 },
400  { "oacute", 0x00F3 },
401  { "ocirc", 0x00F4 },
402  { "otilde", 0x00F5 },
403  { "ouml", 0x00F6 },
404  { "divide", 0x00F7 },
405  { "oslash", 0x00F8 },
406  { "ugrave", 0x00F9 },
407  { "uacute", 0x00FA },
408  { "ucirc", 0x00FB },
409  { "uuml", 0x00FC },
410  { "yacute", 0x00FD },
411  { "thorn", 0x00FE },
412  { "yuml", 0x00FF },
413  { "OElig", 0x0152 },
414  { "oelig", 0x0153 },
415  { "Scaron", 0x0160 },
416  { "scaron", 0x0161 },
417  { "Yuml", 0x0178 },
418  { "fnof", 0x0192 },
419  { "circ", 0x02C6 },
420  { "tilde", 0x02DC },
421  { "Alpha", 0x0391 },
422  { "Beta", 0x0392 },
423  { "Gamma", 0x0393 },
424  { "Delta", 0x0394 },
425  { "Epsilon", 0x0395 },
426  { "Zeta", 0x0396 },
427  { "Eta", 0x0397 },
428  { "Theta", 0x0398 },
429  { "Iota", 0x0399 },
430  { "Kappa", 0x039A },
431  { "Lambda", 0x039B },
432  { "Mu", 0x039C },
433  { "Nu", 0x039D },
434  { "Xi", 0x039E },
435  { "Omicron", 0x039F },
436  { "Pi", 0x03A0 },
437  { "Rho", 0x03A1 },
438  { "Sigma", 0x03A3 },
439  { "Tau", 0x03A4 },
440  { "Upsilon", 0x03A5 },
441  { "Phi", 0x03A6 },
442  { "Chi", 0x03A7 },
443  { "Psi", 0x03A8 },
444  { "Omega", 0x03A9 },
445  { "alpha", 0x03B1 },
446  { "beta", 0x03B2 },
447  { "gamma", 0x03B3 },
448  { "delta", 0x03B4 },
449  { "epsilon", 0x03B5 },
450  { "zeta", 0x03B6 },
451  { "eta", 0x03B7 },
452  { "theta", 0x03B8 },
453  { "iota", 0x03B9 },
454  { "kappa", 0x03BA },
455  { "lambda", 0x03BB },
456  { "mu", 0x03BC },
457  { "nu", 0x03BD },
458  { "xi", 0x03BE },
459  { "omicron", 0x03BF },
460  { "pi", 0x03C0 },
461  { "rho", 0x03C1 },
462  { "sigmaf", 0x03C2 },
463  { "sigma", 0x03C3 },
464  { "tau", 0x03C4 },
465  { "upsilon", 0x03C5 },
466  { "phi", 0x03C6 },
467  { "chi", 0x03C7 },
468  { "psi", 0x03C8 },
469  { "omega", 0x03C9 },
470  { "thetasym", 0x03D1 },
471  { "upsih", 0x03D2 },
472  { "piv", 0x03D6 },
473  { "ensp", 0x2002 },
474  { "emsp", 0x2003 },
475  { "thinsp", 0x2009 },
476  { "zwnj", 0x200C },
477  { "zwj", 0x200D },
478  { "lrm", 0x200E },
479  { "rlm", 0x200F },
480  { "ndash", 0x2013 },
481  { "mdash", 0x2014 },
482  { "horbar", 0x2015 },
483  { "lsquo", 0x2018 },
484  { "rsquo", 0x2019 },
485  { "sbquo", 0x201A },
486  { "ldquo", 0x201C },
487  { "rdquo", 0x201D },
488  { "bdquo", 0x201E },
489  { "dagger", 0x2020 },
490  { "Dagger", 0x2021 },
491  { "bull", 0x2022 },
492  { "hellip", 0x2026 },
493  { "permil", 0x2030 },
494  { "prime", 0x2032 },
495  { "Prime", 0x2033 },
496  { "lsaquo", 0x2039 },
497  { "rsaquo", 0x203A },
498  { "oline", 0x203E },
499  { "frasl", 0x2044 },
500  { "euro", 0x20AC },
501  { "image", 0x2111 },
502  { "weierp", 0x2118 },
503  { "real", 0x211C },
504  { "trade", 0x2122 },
505  { "alefsym", 0x2135 },
506  { "larr", 0x2190 },
507  { "uarr", 0x2191 },
508  { "rarr", 0x2192 },
509  { "darr", 0x2193 },
510  { "harr", 0x2194 },
511  { "crarr", 0x21B5 },
512  { "lArr", 0x21D0 },
513  { "uArr", 0x21D1 },
514  { "rArr", 0x21D2 },
515  { "dArr", 0x21D3 },
516  { "hArr", 0x21D4 },
517  { "forall", 0x2200 },
518  { "part", 0x2202 },
519  { "exist", 0x2203 },
520  { "empty", 0x2205 },
521  { "nabla", 0x2207 },
522  { "isin", 0x2208 },
523  { "notin", 0x2209 },
524  { "ni", 0x220B },
525  { "prod", 0x220F },
526  { "sum", 0x2211 },
527  { "minus", 0x2212 },
528  { "lowast", 0x2217 },
529  { "radic", 0x221A },
530  { "prop", 0x221D },
531  { "infin", 0x221E },
532  { "ang", 0x2220 },
533  { "and", 0x2227 },
534  { "or", 0x2228 },
535  { "cap", 0x2229 },
536  { "cup", 0x222A },
537  { "int", 0x222B },
538  { "there4", 0x2234 },
539  { "sim", 0x223C },
540  { "cong", 0x2245 },
541  { "asymp", 0x2248 },
542  { "ne", 0x2260 },
543  { "equiv", 0x2261 },
544  { "le", 0x2264 },
545  { "ge", 0x2265 },
546  { "sub", 0x2282 },
547  { "sup", 0x2283 },
548  { "nsub", 0x2284 },
549  { "sube", 0x2286 },
550  { "supe", 0x2287 },
551  { "oplus", 0x2295 },
552  { "otimes", 0x2297 },
553  { "perp", 0x22A5 },
554  { "sdot", 0x22C5 },
555  { "lceil", 0x2308 },
556  { "rceil", 0x2309 },
557  { "lfloor", 0x230A },
558  { "rfloor", 0x230B },
559  { "lang", 0x2329 },
560  { "rang", 0x232A },
561  { "loz", 0x25CA },
562  { "spades", 0x2660 },
563  { "clubs", 0x2663 },
564  { "hearts", 0x2665 },
565  { "diams", 0x2666 }
566  }};
567 
568  for (auto &pair : names)
569  {
570  const std::regex re('&' + pair.first + ';');
571  output = std::regex_replace(output, re, u8c.to_bytes(pair.second));
572  }
573 
574  return output;
575 }

◆ urlencode()

const std::string API::urlencode ( const string &  str)
static

Percent-encodes a string. This is done automatically, unless you make a custom request.

Calls curlpp::escape(str)

The only time you should use this, is if you use get(const string &call, string &answer).

See RFC 3986 section 2.1 for more info.

Parameters
strThe string
Returns
The percent-encoded string
135 {
136  return curlpp::escape(str);
137 }
The documentation for this class was generated from the following files:
Generated by   doxygen 1.8.14