monero_c_utils.h

Go to the documentation of this file.

 
#ifndef MONERO_C_UTILS_H
#define MONERO_C_UTILS_H
 
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
 
#if defined(_WIN32) || defined(__CYGWIN__)
  #ifdef MONERO_C_BUILD
    #define MONERO_EXPORT __declspec(dllexport)
  #else
    #define MONERO_EXPORT __declspec(dllimport)
  #endif
#else
  #define MONERO_EXPORT __attribute__((visibility("default")))
#endif
 
#ifdef __cplusplus
extern "C" {
#endif
 
// ------------------------------- RESULT CODES -------------------------------
 
// returned by every function that can fail. On MONERO_ERROR, call monero_last_error()
// for a human-readable message. The pointer outputs of a failed call are set to NULL and the
// counts to 0, even when the failure is a NULL argument. Scalar outputs are left unchanged
typedef enum monero_result {
  MONERO_OK = 0,
  MONERO_ERROR = -1
} monero_result;
 
// mirrors monero_network_type in monero-cpp (daemon/monero_daemon_model.h):
// values must stay numerically identical since they're cast directly across the bridge
// REGTEST has no monero-cpp value. It maps to mainnet, whose address format a regtest node uses, and
// the wallets on it are created with the regtest flag of monero-cpp
typedef enum monero_utils_network_type {
  MONERO_UTILS_NETWORK_MAINNET = 0,
  MONERO_UTILS_NETWORK_TESTNET = 1,
  MONERO_UTILS_NETWORK_STAGENET = 2,
  MONERO_UTILS_NETWORK_REGTEST = 3
} monero_utils_network_type;
 
// ---------------------------- ERROR / MEMORY --------------------------------
 
MONERO_EXPORT const char* monero_last_error(void);
 
MONERO_EXPORT void monero_utils_free(void* ptr);
 
// ---------------------------------- VERSION ---------------------------------
 
// the version of the C ABI, as major.minor.patch like the releases of monero-cpp. While the major
// version is 0, a change of the minor version can break callers. From 1, only a change of the major
// version breaks callers, and the minor version grows when functions are added. The patch version
// changes for fixes that leave the ABI as it is
#define MONERO_C_ABI_VERSION_MAJOR 0
#define MONERO_C_ABI_VERSION_MINOR 1
#define MONERO_C_ABI_VERSION_PATCH 1
 
MONERO_EXPORT monero_result monero_utils_get_abi_version(uint32_t* out_major, uint32_t* out_minor, uint32_t* out_patch);
 
// --------------------------------- LOGGING ----------------------------------
 
MONERO_EXPORT void monero_utils_set_log_level(int32_t level);
 
MONERO_EXPORT void monero_utils_set_log_categories(const char* categories);
 
MONERO_EXPORT void monero_utils_configure_logging(const char* path, bool console);
 
// -------------------------------- VALIDATION --------------------------------
// pure predicates: never fail, false just means "invalid"
 
MONERO_EXPORT bool monero_utils_is_valid_address(const char* address, int32_t network_type);
 
MONERO_EXPORT bool monero_utils_is_valid_private_view_key(const char* private_view_key);
 
MONERO_EXPORT bool monero_utils_is_valid_private_spend_key(const char* private_spend_key);
 
MONERO_EXPORT bool monero_utils_is_valid_public_view_key(const char* public_view_key);
 
MONERO_EXPORT bool monero_utils_is_valid_public_spend_key(const char* public_spend_key);
 
MONERO_EXPORT bool monero_utils_is_valid_payment_id(const char* payment_id);
 
MONERO_EXPORT bool monero_utils_is_valid_mnemonic(const char* mnemonic, const char* language);
 
MONERO_EXPORT bool monero_utils_is_valid_language(const char* language);
 
// same checks as above, but on failure they return MONERO_ERROR and set monero_last_error()
 
MONERO_EXPORT monero_result monero_utils_validate_address(const char* address, int32_t network_type);
 
MONERO_EXPORT monero_result monero_utils_validate_private_view_key(const char* private_view_key);
 
MONERO_EXPORT monero_result monero_utils_validate_private_spend_key(const char* private_spend_key);
 
MONERO_EXPORT monero_result monero_utils_validate_public_view_key(const char* public_view_key);
 
MONERO_EXPORT monero_result monero_utils_validate_public_spend_key(const char* public_spend_key);
 
MONERO_EXPORT monero_result monero_utils_validate_payment_id(const char* payment_id);
 
MONERO_EXPORT monero_result monero_utils_validate_mnemonic(const char* mnemonic, const char* language);
 
// --------------------------- INTEGRATED ADDRESS / URIS ----------------------
// structured in/out values cross the bridge as JSON (monero-cpp's own
// serializable_struct::serialize()/::deserialize() format), so the C side
// doesn't need to mirror every C++ model struct field by field
 
MONERO_EXPORT monero_result monero_utils_get_integrated_address(int32_t network_type, const char* standard_address, const char* payment_id, char** out_json);
 
MONERO_EXPORT monero_result monero_utils_get_payment_uri(const char* tx_config_json, int32_t network_type, char** out_uri);
 
MONERO_EXPORT monero_result monero_utils_parse_payment_uri(const char* uri, int32_t network_type, char** out_tx_config_json);
 
// ----------------------------- JSON / BINARY RPC ----------------------------
// binary payloads (as used by monerod's .bin RPC endpoints) are not
// null-terminated text, so they cross the bridge as explicit (data, length) pairs
 
MONERO_EXPORT monero_result monero_utils_json_to_binary(const char* json, uint8_t** out_data, size_t* out_len);
 
MONERO_EXPORT monero_result monero_utils_binary_to_json(const uint8_t* data, size_t len, char** out_json);
 
MONERO_EXPORT monero_result monero_utils_binary_blocks_to_json(const uint8_t* data, size_t len, char** out_json);
 
MONERO_EXPORT monero_result monero_utils_binary_blocks_fast_to_json(const uint8_t* data, size_t len, char** out_json);
 
// -------------------------------- AMOUNTS / IDS -----------------------------
 
MONERO_EXPORT monero_result monero_utils_xmr_to_atomic_units(double amount_xmr, uint64_t* out_atomic_units);
 
MONERO_EXPORT double monero_utils_atomic_units_to_xmr(uint64_t amount_atomic_units);
 
MONERO_EXPORT bool monero_utils_parse_payment_id_long(const char* payment_id_str, uint8_t out_payment_id[32]);
 
MONERO_EXPORT bool monero_utils_parse_payment_id_short(const char* payment_id_str, uint8_t out_payment_id[8]);
 
MONERO_EXPORT bool monero_utils_is_valid_payment_id_long(const char* payment_id_str);
 
MONERO_EXPORT bool monero_utils_is_valid_payment_id_short(const char* payment_id_str);
 
MONERO_EXPORT monero_result monero_utils_validate_payment_id_long(const char* payment_id_str);
 
MONERO_EXPORT monero_result monero_utils_validate_payment_id_short(const char* payment_id_str);
 
MONERO_EXPORT int32_t monero_utils_get_ring_size(void);
 
#ifdef __cplusplus
}
#endif
 
#endif // MONERO_C_UTILS_H