tastytea
/
mastodon-cpp
Archived
1
0
Fork 0
Code Issues 2 Pull Requests Releases 26 Wiki Activity

Added documentation for return_base and return_call.

This commit is contained in:
tastytea 2019-03-30 13:06:57 +01:00
parent da1ee09640
commit c854230f95
Signed by: tastytea
GPG Key ID: CFC39497F1B26E07
1 changed files with 98 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

135
src/mastodon-cpp.hpp
View File

@ -39,43 +39,104 @@ using std::string;
namespace Mastodon namespace Mastodon
{ {
/*! /*!
* Base return type. * @brief Basis for return types.
* @since 0.100.0 *
* @since 0.100.0
*/ */
typedef struct return_base typedef struct return_base
{ {
uint8_t error_code = 0; // NOTE: http://mazack.org/unix/errno.php /*!
* @brief @ref error "Error code".
*
* @since 0.100.0
*/
uint8_t error_code = 0;
/*!
* @brief The error message, or "".
*
* @since 0.100.0
*/
string error_message; string error_message;
/*!
* @brief true if return_base::error_code is 0, otherwise false.
*
* @since 0.100.0
*/
operator bool(); operator bool();
/*!
* @brief Same as return_base::error_code.
*
* @since 0.100.0
*/
operator uint8_t(); operator uint8_t();
} return_base; } return_base;
/*! /*!
* Return type for API calls. * @brief Return type for API calls.
* @since 0.100.0 *
* Example:
* @code
* Mastodon::return_call ret = masto.get(Mastodon::API::v1::instance);
* if (!ret) // Or ret.error_code != 0
* {
* cout << "Error " << std::to_string(ret.error_code);
* cout << " (HTTP " << std::to_string(ret.http_error_code) << "): ";
* cout << ret.error_message << endl
* }
* else
* {
* cout << ret << endl; // Or ret.answer
* }
* @endcode
*
* @since 0.100.0
*/ */
typedef struct return_call : return_base typedef struct return_call : return_base
{ {
/*!
* @brief HTTP error code.
*
* @since 0.100.0
*/
uint16_t http_error_code = 0; uint16_t http_error_code = 0;
/*!
* @brief The response from the server.
*
* @since 0.100.0
*/
string answer; string answer;
return_call(); return_call();
return_call(const uint8_t ec, const string &em, return_call(const uint8_t ec, const string &em,
const uint16_t hec, const string &a); const uint16_t hec, const string &a);
/*!
* @brief Same es return_call::answer.
*
* @since 0.100.0
*/
operator const string() const; operator const string() const;
/*!
* @brief Same es return_call::answer.
*
* @since 0.100.0
*/
friend std::ostream &operator <<(std::ostream &out, friend std::ostream &operator <<(std::ostream &out,
const return_call &ret); const return_call &ret);
} return_call; } return_call;
/*! /*!
* @brief Interface to the Mastodon API. * @brief Interface to the Mastodon API.
* *
* All input is expected to be UTF-8. Binary data must be * All input is expected to be UTF-8. Binary data must be
* base64-encoded or a filename. * base64-encoded or a filename.
* It appears that media attachements can not be base64 encoded. * It appears that media attachements can not be base64 encoded.
* *
* @section error Error codes * @section error Error codes
* | Code | Explanation | * | Code | Explanation |
* | --------: |:-------------------------------------------| * | --------: |:-------------------------------------------|
@ -87,7 +148,7 @@ namespace Mastodon
* | 192 | curlpp runtime error | * | 192 | curlpp runtime error |
* | 193 | curlpp logic error | * | 193 | curlpp logic error |
* | 255 | Unknown error | * | 255 | Unknown error |
* *
* @since before 0.11.0 * @since before 0.11.0
*/ */
class API class API
@ -95,7 +156,7 @@ class API
public: public:
/*! /*!
* @brief http class. Do not use this directly. * @brief http class. Do not use this directly.
* *
* @since before 0.11.0 * @since before 0.11.0
*/ */
class http class http
@ -129,7 +190,7 @@ public:
* *
* @return @ref error "Error code". If the URL has permanently changed, * @return @ref error "Error code". If the URL has permanently changed,
* 13 is returned and answer is set to the new URL. * 13 is returned and answer is set to the new URL.
* *
* @since before 0.11.0 * @since before 0.11.0
*/ */
return_call request(const method &meth, return_call request(const method &meth,
@ -143,24 +204,24 @@ public:
/*! /*!
* @brief Cancels the stream. Use only with streams. * @brief Cancels the stream. Use only with streams.
* *
* Cancels the stream next time data comes in. Can take a few * Cancels the stream next time data comes in. Can take a few
* seconds. * seconds.
* This works only with streams, because only streams have an * This works only with streams, because only streams have an
* own http object. * own http object.
* *
* @since 0.12.2 * @since 0.12.2
*/ */
void cancel_stream(); void cancel_stream();
/*! /*!
* @brief Gets the mutex guarding the string that is written to. * @brief Gets the mutex guarding the string that is written to.
* *
* The mutex guards the function that writes to the string you * The mutex guards the function that writes to the string you
* specified in get_stream(). * specified in get_stream().
* *
* @return A reference of the mutex. * @return A reference of the mutex.
* *
* @since 0.12.3 * @since 0.12.3
*/ */
std::mutex &get_mutex(); std::mutex &get_mutex();
@ -181,7 +242,7 @@ public:
/*! /*!
* @brief Used for passing parameters. * @brief Used for passing parameters.
* *
* Example: * Example:
* @code * @code
* parametermap p = * parametermap p =
@ -190,16 +251,16 @@ public:
* {"field2", { "value" } } * {"field2", { "value" } }
* } * }
* @endcode * @endcode
* *
* @since before 0.11.0 * @since before 0.11.0
*/ */
typedef std::map<string, std::vector<string>> parametermap; typedef std::map<string, std::vector<string>> parametermap;
/*! /*!
* @brief A list of all v1 API calls. * @brief A list of all v1 API calls.
* *
* The original `/` are substituted by `_`. * The original `/` are substituted by `_`.
* *
* @since before 0.11.0 * @since before 0.11.0
*/ */
enum class v1 enum class v1
@ -308,9 +369,9 @@ public:
/*! /*!
* @brief A list of all v2 API calls. * @brief A list of all v2 API calls.
* *
* The original `/` are substituted by `_`. * The original `/` are substituted by `_`.
* *
* @since 0.16.0 * @since 0.16.0
*/ */
enum class v2 enum class v2
@ -326,7 +387,7 @@ public:
* *
* @param instance The hostname of your instance * @param instance The hostname of your instance
* @param access_token Your access token. * @param access_token Your access token.
* *
* @since before 0.11.0 * @since before 0.11.0
*/ */
explicit API(const string &instance, const string &access_token); explicit API(const string &instance, const string &access_token);
@ -342,7 +403,7 @@ public:
* @brief Sets the useragent. Default is mastodon-cpp/version. * @brief Sets the useragent. Default is mastodon-cpp/version.
* *
* @param useragent The useragent * @param useragent The useragent
* *
* @since before 0.11.0 * @since before 0.11.0
*/ */
void set_useragent(const string &useragent); void set_useragent(const string &useragent);
@ -351,7 +412,7 @@ public:
* @brief Gets the useragent. * @brief Gets the useragent.
* *
* @return The useragent. * @return The useragent.
* *
* @since before 0.11.0 * @since before 0.11.0
*/ */
const string get_useragent() const; const string get_useragent() const;
@ -360,7 +421,7 @@ public:
* @brief Returns the instance. * @brief Returns the instance.
* *
* @return The instance. * @return The instance.
* *
* @since before 0.11.0 * @since before 0.11.0
*/ */
const string get_instance() const; const string get_instance() const;
@ -368,18 +429,18 @@ public:
/*! /*!
* @brief Percent-encodes a string. This is done automatically, unless you * @brief Percent-encodes a string. This is done automatically, unless you
* make a custom request. * make a custom request.
* *
* Calls curlpp::escape(str) * Calls curlpp::escape(str)
* *
* The only time you should use this, is if you use * The only time you should use this, is if you use
* get(const string &call, string &answer). * get(const string &call, string &answer).
* *
* See RFC 3986 section 2.1 for more info. * See RFC 3986 section 2.1 for more info.
* *
* @param str The string * @param str The string
* *
* @return The percent-encoded string * @return The percent-encoded string
* *
* @since before 0.11.0 * @since before 0.11.0
*/ */
static const string urlencode(const string &str); static const string urlencode(const string &str);
@ -413,7 +474,7 @@ public:
* *
* @return @ref error "Error code". If the URL has permanently changed, 13 * @return @ref error "Error code". If the URL has permanently changed, 13
* is returned and url is set to the new URL. * is returned and url is set to the new URL.
* *
* @since before 0.11.0 * @since before 0.11.0
*/ */
return_call register_app1(const string &client_name, return_call register_app1(const string &client_name,
@ -427,17 +488,17 @@ public:
/*! /*!
* @brief Register application, step 2/2 * @brief Register application, step 2/2
* *
* The access token will be used in all subsequent calls. * The access token will be used in all subsequent calls.
* *
* @param client_id * @param client_id
* @param client_secret * @param client_secret
* @param redirect_uri urn:ietf:wg:oauth:2.0:oob for none * @param redirect_uri urn:ietf:wg:oauth:2.0:oob for none
* @param code The code generated by the website * @param code The code generated by the website
* @param access_token Returned * @param access_token Returned
* *
* @return @ref error "Error code". * @return @ref error "Error code".
* *
* @since before 0.11.0 * @since before 0.11.0
*/ */
return_call register_app2(const string &client_id, return_call register_app2(const string &client_id,
@ -452,21 +513,21 @@ public:
* @param header The header to get * @param header The header to get
* *
* @return The header, or "" on error. * @return The header, or "" on error.
* *
* @since before 0.11.0 * @since before 0.11.0
*/ */
const string get_header(const string &header) const; const string get_header(const string &header) const;
/*! /*!
* @brief Turn exceptions on or off. Defaults to off. * @brief Turn exceptions on or off. Defaults to off.
* *
* This applies to exceptions from curlpp. curlpp::RuntimeError and * This applies to exceptions from curlpp. curlpp::RuntimeError and
* curlpp::LogicError. * curlpp::LogicError.
* *
* @param value true for on, false for off * @param value true for on, false for off
* *
* @return true if exceptions are turned on, false otherwise * @return true if exceptions are turned on, false otherwise
* *
* @since before 0.11.0 * @since before 0.11.0
*/ */
bool exceptions(const bool &value); bool exceptions(const bool &value);
@ -480,7 +541,7 @@ public:
* @brief Replaces HTML entities with UTF-8 characters * @brief Replaces HTML entities with UTF-8 characters
* *
* Supports named and numbered entities, decimal and hexadecimal. * Supports named and numbered entities, decimal and hexadecimal.
* *
* @since 0.12.0 * @since 0.12.0
*/ */
static const string unescape_html(const string &html); static const string unescape_html(const string &html);