Metadatum¶

typedef struct cardano_metadatum_t cardano_metadatum_t¶

A type corresponding to the metadatum type.

Use this type to build metadata structures that you want to be representable on-chain.

cardano_error_t cardano_metadatum_new_map(cardano_metadatum_map_t *map, cardano_metadatum_t **metadatum)¶

Creates and initializes a new instance of a metadatum from a metadatum_map.

This function creates and initializes a new instance of a cardano_metadatum_t object from a given cardano_metadatum_map_t object. It essentially converts a metadatum map into a metadatum. It returns an error code to indicate the success or failure of the operation.

Usage Example:

cardano_metadatum_map_t* map = cardano_metadatum_map_new(...);
cardano_metadatum_t* metadatum = NULL;

// Attempt to create a new metadatum from a metadatum_map
cardano_error_t result = cardano_metadatum_new_map(map, &metadatum);

if (result == CARDANO_SUCCESS)
{
  // Use the metadatum

  // Once done, ensure to clean up and release the metadatum
  cardano_metadatum_unref(&metadatum);
}

// Clean up the metadatum_map object once done
cardano_metadatum_map_unref(&map);

Parameters:¶

cardano_metadatum_map_t *map¶

[in] A pointer to the cardano_metadatum_map_t object from which the metadatum will be created.

cardano_metadatum_t **metadatum¶

[out] On successful initialization, this will point to a newly created cardano_metadatum_t object. This object represents a “strong reference” to the metadatum, meaning that it is fully initialized and ready for use. The caller is responsible for managing the lifecycle of this object. Specifically, once the metadatum is no longer needed, the caller must release it by calling cardano_metadatum_unref.

Returns:¶

CARDANO_SUCCESS if the metadatum was successfully created, or an appropriate error code indicating the failure reason.

cardano_error_t cardano_metadatum_new_list(cardano_metadatum_list_t *list, cardano_metadatum_t **metadatum)¶

Creates and initializes a new instance of a metadatum from a metadatum list.

This function creates and initializes a new instance of a cardano_metadatum_t object from a given cardano_metadatum_list_t object. It essentially converts a metadatum list into a metadatum. It returns an error code to indicate the success or failure of the operation.

Usage Example:

cardano_metadatum_list_t* list = cardano_metadatum_list_new(...);
cardano_metadatum_t* metadatum = NULL;

// Attempt to create a new metadatum from a metadatum_list
cardano_error_t result = cardano_metadatum_new_list(list, &metadatum);

if (result == CARDANO_SUCCESS)
{
  // Use the metadatum

  // Once done, ensure to clean up and release the metadatum
  cardano_metadatum_unref(&metadatum);
}

// Clean up the metadatum_list object once done
cardano_metadatum_list_unref(&list);

Parameters:¶

cardano_metadatum_list_t *list¶

[in] A pointer to the cardano_metadatum_list_t object from which the metadatum will be created. The object must not be NULL.

cardano_metadatum_t **metadatum¶

[out] On successful initialization, this will point to a newly created cardano_metadatum_t object. This object represents a “strong reference” to the metadatum, meaning that it is fully initialized and ready for use. The caller is responsible for managing the lifecycle of this object. Specifically, once the metadatum is no longer needed, the caller must release it by calling cardano_metadatum_unref.

Returns:¶

CARDANO_SUCCESS if the metadatum was successfully created, or an appropriate error code indicating the failure reason.

cardano_error_t cardano_metadatum_new_integer(const cardano_bigint_t *bigint, cardano_metadatum_t **metadatum)¶

Creates and initializes a new instance of metadatum from a bigint object.

This function creates and initializes a new instance of a cardano_metadatum_t object from a given bigint object.

Usage Example:

// Assume bigint is already initialized and set to a value
cardano_bigint_t* bigint = ...;
cardano_metadatum_t* metadatum = NULL;

// Attempt to create a new metadatum from a bigint
cardano_error_t result = cardano_metadatum_new_integer(bigint, &metadatum);

if (result == CARDANO_SUCCESS)
{
  // Use the metadatum

  // Once done, ensure to clean up and release the metadatum
  cardano_metadatum_unref(&metadatum);
}

Parameters:¶

const cardano_bigint_t *bigint¶

[in] A constant pointer to the cardano_bigint_t object from which the metadatum will be created.

cardano_metadatum_t **metadatum¶

[out] On successful initialization, this will point to a newly created cardano_metadatum_t object. This object represents a “strong reference” to the metadatum, meaning that it is fully initialized and ready for use. The caller is responsible for managing the lifecycle of this object. Specifically, once the metadatum is no longer needed, the caller must release it by calling cardano_metadatum_unref.

Returns:¶

CARDANO_SUCCESS if the metadatum was successfully created, or an appropriate error code indicating the failure reason.

cardano_error_t cardano_metadatum_new_integer_from_int(int64_t integer, cardano_metadatum_t **metadatum)¶

Creates and initializes a new instance of metadatum from an integer value.

This function creates and initializes a new instance of a cardano_metadatum_t object from a given int64_t integer. It converts an integer into a metadatum object, suitable for transactions and other blockchain-related operations. It returns an error code to indicate the success or failure of the operation.

Usage Example:

int64_t integer_value = 42; // Example integer value
cardano_metadatum_t* metadatum = NULL;

// Attempt to create a new metadatum from an integer value
cardano_error_t result = cardano_metadatum_new_integer_from_int(integer_value, &metadatum);

if (result == CARDANO_SUCCESS)
{
  // Use the metadatum

  // Once done, ensure to clean up and release the metadatum
  cardano_metadatum_unref(&metadatum);
}

Parameters:¶

int64_t integer¶

[in] The int64_t integer value from which the metadatum will be created.

cardano_metadatum_t **metadatum¶

[out] On successful initialization, this will point to a newly created cardano_metadatum_t object. This object represents a “strong reference” to the metadatum, meaning that it is fully initialized and ready for use. The caller is responsible for managing the lifecycle of this object. Specifically, once the metadatum is no longer needed, the caller must release it by calling cardano_metadatum_unref.

Returns:¶

CARDANO_SUCCESS if the metadatum was successfully created, or an appropriate error code indicating the failure reason.

cardano_error_t cardano_metadatum_new_integer_from_uint(uint64_t integer, cardano_metadatum_t **metadatum)¶

Creates and initializes a new instance of metadatum from an unsigned integer value.

This function creates and initializes a new instance of a cardano_metadatum_t object from a given uint64_t integer.

Usage Example:

uint64_t integer_value = 18446744073709551615u; // Example unsigned integer value
cardano_metadatum_t* metadatum = NULL;

// Attempt to create a new metadatum from an unsigned integer value
cardano_error_t result = cardano_metadatum_new_integer_from_uint(integer_value, &metadatum);

if (result == CARDANO_SUCCESS)
{
  // Use the metadatum

  // Once done, ensure to clean up and release the metadatum
  cardano_metadatum_unref(&metadatum);
}

Parameters:¶

uint64_t integer¶

[in] The uint64_t integer value from which the metadatum will be created.

cardano_metadatum_t **metadatum¶

[out] On successful initialization, this will point to a newly created cardano_metadatum_t object. This object represents a “strong reference” to the metadatum, meaning that it is fully initialized and ready for use. The caller is responsible for managing the lifecycle of this object. Specifically, once the metadatum is no longer needed, the caller must release it by calling cardano_metadatum_unref.

Returns:¶

CARDANO_SUCCESS if the metadatum was successfully created, or an appropriate error code indicating the failure reason.

cardano_error_t cardano_metadatum_new_integer_from_string(const char *string, size_t size, int32_t base, cardano_metadatum_t **metadatum)¶

Creates and initializes a new instance of Plutus data from a string representation of an integer in a specified base.

This function creates and initializes a new instance of a cardano_metadatum_t object from a given string representing an integer, interpreted according to the specified base (e.g., 10 for decimal, 16 for hexadecimal).

Usage Example:

const char* integer_str = "12345678901234567890"; // Example large integer value in string form
cardano_metadatum_t* metadatum = NULL;
int32_t base = 10; // Decimal base

// Attempt to create a new metadatum from a string representation of an integer in decimal
cardano_error_t result = cardano_metadatum_new_integer_from_string(integer_str, strlen(integer_str), base, &metadatum);

if (result == CARDANO_SUCCESS)
{
  // Use the metadatum

  // Once done, ensure to clean up and release the metadatum
  cardano_metadatum_unref(&metadatum);
}

Parameters:¶

const char *string¶

[in] A pointer to the character string containing the numeric representation of the integer.

size_t size¶

[in] The number of characters in the string, excluding the null terminator.

int32_t base¶

[in] The numerical base in which the string representation is expressed. Valid values are between 2 and 36.

cardano_metadatum_t **metadatum¶

[out] On successful initialization, this will point to a newly created cardano_metadatum_t object. This object represents a “strong reference” to the metadatum, meaning that it is fully initialized and ready for use. The caller is responsible for managing the lifecycle of this object. Specifically, once the metadatum is no longer needed, the caller must release it by calling cardano_metadatum_unref.

Returns:¶

CARDANO_SUCCESS if the metadatum was successfully created, or an appropriate error code indicating the failure reason.

cardano_error_t cardano_metadatum_new_bytes(const byte_t *bytes, size_t size, cardano_metadatum_t **metadatum)¶

Creates and initializes a new instance of a metadatum from a byte array.

This function creates and initializes a new instance of a cardano_metadatum_t object from a given byte array. It essentially converts a byte array into a metadatum. It returns an error code to indicate the success or failure of the operation.

Usage Example:

const byte_t bytes[] = {0x01, 0x02, 0x03, 0x04}; // Example byte array
size_t size = sizeof(bytes) / sizeof(byte_t); // Calculate the size of the byte array
cardano_metadatum_t* metadatum = NULL;

// Attempt to create a new metadatum from a byte array
cardano_error_t result = cardano_metadatum_new_bytes(bytes, size, &metadatum);

if (result == CARDANO_SUCCESS)
{
  // Use the metadatum

  // Once done, ensure to clean up and release the metadatum
  cardano_metadatum_unref(&metadatum);
}

Parameters:¶

const byte_t *bytes¶

[in] A pointer to the byte array from which the metadatum will be created. The byte array must not be NULL.

size_t size¶

[in] The size of the byte array.

cardano_metadatum_t **metadatum¶

[out] On successful initialization, this will point to a newly created cardano_metadatum_t object. This object represents a “strong reference” to the metadatum, meaning that it is fully initialized and ready for use. The caller is responsible for managing the lifecycle of this object. Specifically, once the metadatum is no longer needed, the caller must release it by calling cardano_metadatum_unref.

Returns:¶

CARDANO_SUCCESS if the metadatum was successfully created, or an appropriate error code indicating the failure reason.

cardano_error_t cardano_metadatum_new_bytes_from_hex(const char *hex, size_t size, cardano_metadatum_t **metadatum)¶

Creates and initializes a new instance of a metadatum from a hexadecimal string.

This function creates and initializes a new instance of a cardano_metadatum_t object from a given hexadecimal string. It essentially converts a hexadecimal string into a metadatum, treating each pair of characters as a byte. It returns an error code to indicate the success or failure of the operation.

Usage Example:

const char* hex_string = "0123456789abcdef"; // Example hexadecimal string
size_t size = strlen(hex_string); // Calculate the size of the string
cardano_metadatum_t* metadatum = NULL;

// Attempt to create a new metadatum from a hexadecimal string
cardano_error_t result = cardano_metadatum_new_bytes_from_hex(hex_string, size, &metadatum);

if (result == CARDANO_SUCCESS)
{
  // Use the metadatum

  // Once done, ensure to clean up and release the metadatum
  cardano_metadatum_unref(&metadatum);
}

Parameters:¶

const char *hex¶

[in] A pointer to the hexadecimal string from which the metadatum will be created. The hexadecimal string must not be NULL.

size_t size¶

[in] The size of the hexadecimal string.

cardano_metadatum_t **metadatum¶

[out] On successful initialization, this will point to a newly created cardano_metadatum_t object. This object represents a “strong reference” to the metadatum, meaning that it is fully initialized and ready for use. The caller is responsible for managing the lifecycle of this object. Specifically, once the metadatum is no longer needed, the caller must release it by calling cardano_metadatum_unref.

Returns:¶

CARDANO_SUCCESS if the metadatum was successfully created, or an appropriate error code indicating the failure reason.

cardano_error_t cardano_metadatum_new_string(const char *string, size_t size, cardano_metadatum_t **metadatum)¶

Creates and initializes a new instance of a metadatum from a string.

This function creates and initializes a new instance of a cardano_metadatum_t object from a given string.

Usage Example:

const char* string = "hello world"; // Example string
size_t size = strlen(string); // Calculate the size of the string
cardano_metadatum_t* metadatum = NULL;

// Attempt to create a new metadatum from a string
cardano_error_t result = cardano_metadatum_new_string(string, size, &metadatum);

if (result == CARDANO_SUCCESS)
{
  // Use the metadatum

  // Once done, ensure to clean up and release the metadatum
  cardano_metadatum_unref(&metadatum);
}

Parameters:¶

const char *string¶

[in] A pointer to the string from which the metadatum will be created. The string must not be NULL.

size_t size¶

[in] The size of the string.

cardano_metadatum_t **metadatum¶

[out] On successful initialization, this will point to a newly created cardano_metadatum_t object. This object represents a “strong reference” to the metadatum, meaning that it is fully initialized and ready for use. The caller is responsible for managing the lifecycle of this object. Specifically, once the metadatum is no longer needed, the caller must release it by calling cardano_metadatum_unref.

Returns:¶

CARDANO_SUCCESS if the metadatum was successfully created, or an appropriate error code indicating the failure reason.

cardano_error_t cardano_metadatum_from_cbor(cardano_cbor_reader_t *reader, cardano_metadatum_t **metadatum)¶

Creates a metadatum from a CBOR reader.

This function parses CBOR data using a provided cardano_cbor_reader_t and constructs a cardano_metadatum_t object. It assumes that the CBOR reader is set up correctly and that the CBOR data corresponds to the structure expected for a metadatum.

Usage Example:

cardano_cbor_reader_t* reader = cardano_cbor_reader_new(cbor_data, data_size);
cardano_metadatum_t* metadatum = NULL;

cardano_error_t result = cardano_metadatum_from_cbor(reader, &metadatum);

if (result == CARDANO_SUCCESS)
{
  // Use the metadatum

  // Once done, ensure to clean up and release the metadatum
  cardano_metadatum_unref(&metadatum);
}
else
{
  const char* error = cardano_cbor_reader_get_last_error(reader);
  printf("Failed to decode metadatum: %s\n", error);
}

cardano_cbor_reader_unref(&reader); // Cleanup the CBOR reader

Note

If the function fails, the last error can be retrieved by calling cardano_cbor_reader_get_last_error with the reader. The caller is responsible for freeing the created cardano_metadatum_t object by calling cardano_metadatum_unref when it is no longer needed.

Parameters:¶

cardano_cbor_reader_t *reader¶

[in] A pointer to an initialized cardano_cbor_reader_t that is ready to read the CBOR-encoded metadatum.

cardano_metadatum_t **metadatum¶

[out] A pointer to a pointer of cardano_metadatum_t that will be set to the address of the newly created metadatum object upon successful decoding.

Returns:¶

A cardano_error_t value indicating the outcome of the operation. Returns CARDANO_SUCCESS if the metadatum was successfully created, or an appropriate error code if an error occurred.

cardano_error_t cardano_metadatum_from_json(const char *json, size_t json_size, cardano_metadatum_t **metadatum)¶

Creates a metadatum from a JSON string.

This function parses JSON data using a provided JSON string and constructs a cardano_metadatum_t object. It assumes that the JSON data corresponds to the structure expected for a metadatum.

Usage Example:

const char* json_data = "{...}"; // Assume this contains valid JSON-encoded metadatum data
size_t data_size = strlen(json_data);
cardano_metadatum_t* metadatum = NULL;

cardano_error_t result = cardano_metadatum_from_json(json_data, data_size, &metadatum);

if (result == CARDANO_SUCCESS)
{
  // Use the metadatum

  // Once done, ensure to clean up and release the metadatum
  cardano_metadatum_unref(&metadatum);
}
else
{
  // Handle error
  printf("Failed to decode metadatum: %s\n", cardano_error_to_string(result));
}

Parameters:¶

const char *json¶

[in] A pointer to a character array containing the JSON-encoded metadatum data.

size_t json_size¶

[in] The size of the JSON data in bytes.

cardano_metadatum_t **metadatum¶

[out] A pointer to a pointer of cardano_metadatum_t that will be set to the address of the newly created metadatum object upon successful decoding.

Returns:¶

A cardano_error_t value indicating the outcome of the operation. Returns CARDANO_SUCCESS if the metadatum was successfully created, or an appropriate error code if an error occurred.

size_t cardano_metadatum_get_json_size(cardano_metadatum_t *metadatum)¶

Computes the size needed for the JSON string representation of a metadatum.

This function calculates the size in bytes required to represent a cardano_metadatum_t as a null-terminated JSON string, including the null terminator. This is useful for allocating an appropriately sized buffer before converting the metadatum to JSON using cardano_metadatum_to_json.

Usage Example:

// Assume metadatum is already initialized
cardano_metadatum_t* metadatum = ...;

size_t json_size = cardano_metadatum_get_json_size(metadatum);

if (json_size > 0)
{
  // json_size now contains the size needed to store the JSON string, including null terminator
  // You can allocate a buffer of this size for conversion
}
else
{
  printf("Failed to get the JSON size.\n");
  // Handle error
}

See also

cardano_metadatum_to_json

Note

The size returned includes space for the null terminator.

Parameters:¶

cardano_metadatum_t *metadatum¶

[in] A pointer to the cardano_metadatum_t instance whose JSON size is being queried. This parameter must not be NULL.

Returns:¶

The size in bytes required to represent the metadatum as a null-terminated JSON string, including the null terminator. Returns 0 if metadatum is NULL or if an error occurs.

cardano_error_t cardano_metadatum_to_json(cardano_metadatum_t *metadatum, char *json, size_t json_size)¶

Converts a metadatum object to a JSON string.

This function converts a cardano_metadatum_t object to its JSON representation. The resulting JSON string is stored in the provided buffer, which must be pre-allocated by the caller. The buffer must be large enough to hold the entire JSON string, including the null terminator.

To determine the required buffer size (including the null terminator), use cardano_metadatum_get_json_size before calling this function.

Usage Example:

// Assume metadatum is already initialized
cardano_metadatum_t* metadatum = ...;

// Get the size needed for the JSON string (including null terminator)
size_t json_size = cardano_metadatum_get_json_size(metadatum);
if (json_size == 0)
{
  printf("Failed to get the JSON size.\n");
  // Handle error
}
else
{
  // Allocate buffer for the JSON string
  char* json_buffer = (char*)malloc(json_size);
  if (json_buffer == NULL)
  {
    printf("Memory allocation failed.\n");
    // Handle memory allocation failure
  }
  else
  {
    // Convert the metadatum to JSON
    cardano_error_t result = cardano_metadatum_to_json(metadatum, json_buffer, json_size);
    if (result == CARDANO_SUCCESS)
    {
      printf("Metadatum as JSON: %s\n", json_buffer);
    }
    else
    {
      printf("Failed to convert metadatum to JSON: %s\n", cardano_error_to_string(result));
    }
    // Free the buffer when done
    free(json_buffer);
  }
}

// Clean up the metadatum object once done
cardano_metadatum_unref(&metadatum);

See also

cardano_metadatum_get_json_size

Note

The JSON string will be encoded in UTF-8.

Parameters:¶

cardano_metadatum_t *metadatum¶

[in] A pointer to the cardano_metadatum_t object to be converted. This parameter must not be NULL.

char *json¶

[out] A pointer to a character array where the null-terminated JSON string will be stored. The buffer must be allocated by the caller and have a size of at least json_size bytes. This parameter must not be NULL.

size_t json_size¶

[in] The size of the json buffer in bytes, including space for the null terminator.

Returns:¶

CARDANO_SUCCESS if the conversion was successful. Returns CARDANO_ERROR_POINTER_IS_NULL if metadatum or json is NULL. Returns CARDANO_ERROR_INSUFFICIENT_BUFFER_SIZE if json_size is insufficient to hold the JSON string.

cardano_error_t cardano_metadatum_to_cip116_json(const cardano_metadatum_t *metadatum, cardano_json_writer_t *writer)¶

Serializes a cardano_metadatum_t to CIP-116 JSON.

This function emits a single JSON object representing a Cardano transaction metadatum using the CIP-116 JSON shape.

The function always writes a complete JSON object (it begins with { and ends with }). It assumes writer is positioned where a value is valid (root, array element, or after a property name).

Note

Unlike on-chain CBOR encoding constraints, this JSON encoder does not enforce the 64-byte bounds on bytes/text metadata. It emits the full content as provided.

Parameters:¶

const cardano_metadatum_t *metadatum¶

[in] A valid pointer to the metadatum to serialize.

cardano_json_writer_t *writer¶

[inout] A valid JSON writer.

Returns:¶

CARDANO_SUCCESS on success.

Returns:¶

CARDANO_ERROR_POINTER_IS_NULL if any pointer parameter is NULL.

Returns:¶

CARDANO_ERROR_ENCODING on encoding errors (e.g., allocation failure or conversion failure).

cardano_error_t cardano_metadatum_to_cbor(const cardano_metadatum_t *metadatum, cardano_cbor_writer_t *writer)¶

Serializes a metadatum into CBOR format using a CBOR writer.

This function serializes the given cardano_metadatum_t object using a cardano_cbor_writer_t.

Usage Example:

cardano_metadatum_t* metadatum = ...;
cardano_cbor_writer_t* writer = cardano_cbor_writer_new();

if (writer)
{
  cardano_error_t result = cardano_metadatum_to_cbor(metadatum, writer);

  if (result == CARDANO_SUCCESS)
  {
    // Use the writer's buffer containing the serialized data
  }
  else
  {
    const char* error_message = cardano_cbor_writer_get_last_error(writer);
    printf("Serialization failed: %s\n", error_message);
  }

  cardano_cbor_writer_unref(&writer);
}

cardano_metadatum_unref(&metadatum);

Parameters:¶

const cardano_metadatum_t *metadatum¶

[in] A constant pointer to the cardano_metadatum_t object that is to be serialized.

cardano_cbor_writer_t *writer¶

[out] A pointer to a cardano_cbor_writer_t where the CBOR serialized data will be written. The writer must already be initialized and ready to accept the data.

Returns:¶

Returns CARDANO_SUCCESS if the serialization is successful. If the metadatum or writer is NULL, returns CARDANO_ERROR_POINTER_IS_NULL.

cardano_error_t cardano_metadatum_get_kind(const cardano_metadatum_t *metadatum, cardano_metadatum_kind_t *kind)¶

Retrieves the kind of the metadatum.

This function retrieves the kind of a given cardano_metadatum_t object and stores it in the provided output parameter. The metadatum kind is defined in the cardano_metadatum_kind_t enumeration, which specifies whether the metadatum represents an integer, byte array, or other types.

Usage Example:

cardano_metadatum_t* metadatum = cardano_metadatum_new_bytes_from_hex(...);
cardano_metadatum_kind_t kind;
cardano_error_t result = cardano_metadatum_get_kind(metadatum, &kind);

if (result == CARDANO_SUCCESS)
{
  if (kind == CARDANO_METADATUM_KIND_INTEGER)
  {
    // Handle integer type metadatum
  }
  else if (kind == CARDANO_METADATUM_KIND_BYTES)
  {
    // Handle byte array type metadatum
  }
  // Add more cases as needed for other kinds
}

// Clean up the metadatum object once done
cardano_metadatum_unref(&metadatum);

Parameters:¶

const cardano_metadatum_t *metadatum¶

[in] A constant pointer to the cardano_metadatum_t object from which the kind is to be retrieved. The object must not be NULL.

cardano_metadatum_kind_t *kind¶

[out] Pointer to a variable where the metadatum kind will be stored. This variable will be set to the value from the cardano_metadatum_kind_t enumeration.

Returns:¶

CARDANO_SUCCESS if the kind was successfully retrieved, or an appropriate error code if the input is NULL or any other error occurs.

cardano_error_t cardano_metadatum_to_map(cardano_metadatum_t *metadatum, cardano_metadatum_map_t **map)¶

Converts a metadatum object to a metadatum map object.

This function converts a cardano_metadatum_t object to a cardano_metadatum_map_t object. It essentially creates a metadatum map object from the given metadatum, allowing the conversion between different types of metadatum. It returns an error code to indicate the success or failure of the operation.

Usage Example:

cardano_metadatum_t* metadatum = ...; // Assume metadatum is a valid metadatum map object
cardano_metadatum_map_t* map = NULL;
cardano_error_t result = cardano_metadatum_to_map(metadatum, &map);

if (result == CARDANO_SUCCESS)
{
  // Use the metadatum_map

  // Once done, ensure to clean up and release the metadatum_map
  cardano_metadatum_map_unref(&map);
}

// Clean up the metadatum object once done
cardano_metadatum_unref(&metadatum);

Parameters:¶

cardano_metadatum_t *metadatum¶

[in] A constant pointer to the cardano_metadatum_t object to be converted. The object must not be NULL.

cardano_metadatum_map_t **map¶

[out] On successful conversion, this will point to a newly created cardano_metadatum_map_t object. This object represents a “strong reference” to the metadatum_map, meaning that it is fully initialized and ready for use. The caller is responsible for managing the lifecycle of this object. Specifically, once the metadatum_map is no longer needed, the caller must release it by calling cardano_metadatum_map_unref.

Returns:¶

CARDANO_SUCCESS if the conversion was successful, or an appropriate error code indicating the failure reason.

cardano_error_t cardano_metadatum_to_list(cardano_metadatum_t *metadatum, cardano_metadatum_list_t **list)¶

Converts a metadatum object to a metadatum list object.

This function converts a cardano_metadatum_t object to a cardano_metadatum_list_t object. It essentially creates a metadatum list object from the given metadatum, allowing the conversion between different types of metadatum. It returns an error code to indicate the success or failure of the operation.

Usage Example:

cardano_metadatum_t* metadatum = ...; // Assume metadatum is a valid metadatum list object
cardano_metadatum_list_t* list = NULL;
cardano_error_t result = cardano_metadatum_to_list(metadatum, &list);

if (result == CARDANO_SUCCESS)
{
  // Use the metadatum_list

  // Once done, ensure to clean up and release the metadatum_list
  cardano_metadatum_list_unref(&list);
}

// Clean up the metadatum object once done
cardano_metadatum_unref(&metadatum);

Parameters:¶

cardano_metadatum_t *metadatum¶

[in] A constant pointer to the cardano_metadatum_t object to be converted.

cardano_metadatum_list_t **list¶

[out] On successful conversion, this will point to a newly created cardano_metadatum_list_t object. This object represents a “strong reference” to the metadatum_list, meaning that it is fully initialized and ready for use. The caller is responsible for managing the lifecycle of this object. Specifically, once the metadatum_list is no longer needed, the caller must release it by calling cardano_metadatum_list_unref.

Returns:¶

CARDANO_SUCCESS if the conversion was successful, or an appropriate error code indicating the failure reason.

cardano_error_t cardano_metadatum_to_integer(const cardano_metadatum_t *metadatum, cardano_bigint_t **integer)¶

Converts a metadatum object to a bigint object.

This function converts a cardano_metadatum_t object to a cardano_bigint_t object.

Usage Example:

cardano_metadatum_t* metadatum = cardano_metadatum_new_integer_from_string("987456321478523698745");
cardano_bigint_t* bigint = NULL;
cardano_error_t result = cardano_metadatum_to_integer(metadatum, &bigint);

if (result == CARDANO_SUCCESS)
{
  // Use the bigint object
  const size_t size = cardano_bigint_get_string_size(bigint, 10);
  char* buffer = (char*)malloc(size);

  if (cardano_bigint_to_string(bigint, buffer, size, 10) == CARDANO_SUCCESS)
  {
    printf("Extracted bigint value: %s\n", buffer);
  }
}

// Clean up
cardano_metadatum_unref(&metadatum);
cardano_bigint_unref(&bigint);

Parameters:¶

const cardano_metadatum_t *metadatum¶

[in] A constant pointer to the cardano_metadatum_t object to be converted.

cardano_bigint_t **integer¶

[out] On successful conversion, this will point to a newly created cardano_bigint_t object representing the extracted integer value. The caller is responsible for managing the memory of this object, including releasing it when it is no longer needed.

Returns:¶

CARDANO_SUCCESS if the conversion was successful, or an appropriate error code indicating the failure reason.

cardano_error_t cardano_metadatum_to_bounded_bytes(cardano_metadatum_t *metadatum, cardano_buffer_t **bounded_bytes)¶

Converts a metadatum object to bounded bytes.

This function converts a cardano_metadatum_t object to bounded bytes. It extracts the bytes from the given metadatum, allowing the conversion between different types of metadatum. The resulting bytes are stored in a bounded bytes buffer. It returns an error code to indicate the success or failure of the operation.

Usage Example:

cardano_metadatum_t* metadatum = cardano_metadatum_new_bytes_from_hex("DEADBEEF", 8);
cardano_buffer_t* bounded_bytes = NULL;
cardano_error_t result = cardano_metadatum_to_bounded_bytes(metadatum, &bounded_bytes);

if (result == CARDANO_SUCCESS)
{
  // Use the bounded bytes
  printf("Extracted bounded bytes: ");

  for (size_t i = 0; i < cardano_buffer_get_size(bounded_bytes); ++i)
  {
    printf("%02X ", cardano_buffer_get_data(bounded_bytes)[i]);
  }

  printf("\n");

  // Once done, ensure to clean up and release the bounded bytes
  cardano_buffer_unref(&bounded_bytes);
}

// Clean up the metadatum object once done
cardano_metadatum_unref(&metadatum);

Parameters:¶

cardano_metadatum_t *metadatum¶

[in] A constant pointer to the cardano_metadatum_t object to be converted.

cardano_buffer_t **bounded_bytes¶

[out] On successful conversion, this will point to a newly created cardano_buffer_t object containing the extracted bytes. This object represents a “strong reference” to the bounded bytes, meaning that it is fully initialized and ready for use. The caller is responsible for managing the lifecycle of this object. Specifically, once the bounded bytes are no longer needed, the caller must release it by calling cardano_buffer_unref.

Returns:¶

CARDANO_SUCCESS if the conversion was successful, or an appropriate error code indicating the failure reason.

size_t cardano_metadatum_get_string_size(cardano_metadatum_t *metadatum)¶

Computes the size needed for the null-terminated string representation of a metadatum.

This function calculates the size in bytes required to represent a cardano_metadatum_t as a null-terminated string, including the null terminator. This is useful for allocating an appropriately sized buffer before converting the metadatum to a string using cardano_metadatum_to_string.

Usage Example:

// Assume metadatum is already initialized
cardano_metadatum_t* metadatum = ...;

size_t size = cardano_metadatum_get_string_size(metadatum);

if (size > 0)
{
    // size now contains the size needed to store the string, including null terminator
    // You can allocate a buffer of this size for conversion
}
else
{
    printf("Failed to get the string size.\n");
    // Handle error
}

See also

cardano_metadatum_to_string

Parameters:¶

cardano_metadatum_t *metadatum¶

[in] A pointer to the cardano_metadatum_t instance whose string size is being queried. This parameter must not be NULL.

Returns:¶

The size in bytes required to represent the metadatum as a null-terminated string, including the null terminator. Returns 0 if metadatum is NULL or if an error occurs.

cardano_error_t cardano_metadatum_to_string(cardano_metadatum_t *metadatum, char *buffer, size_t buffer_size)¶

Converts a metadatum object to a null-terminated C string.

This function converts a cardano_metadatum_t object to its string representation. The resulting string is stored in the provided buffer, which must be pre-allocated by the caller. The buffer must be large enough to hold the entire string, including the null terminator.

To determine the required buffer size (including the null terminator), use cardano_metadatum_get_string_size before calling this function.

Usage Example:

// Assume metadatum is already initialized
cardano_metadatum_t* metadatum = ...;

// Get the size needed for the string (including null terminator)
size_t string_size = cardano_metadatum_get_string_size(metadatum);
if (string_size == 0)
{
    printf("Failed to get the string size.\n");
    // Handle error
}
else
{
    // Allocate buffer for the string
    char* buffer = (char*)malloc(string_size);
    if (buffer == NULL)
    {
        printf("Memory allocation failed.\n");
        // Handle memory allocation failure
    }
    else
    {
        // Convert the metadatum to string
        cardano_error_t result = cardano_metadatum_to_string(metadatum, buffer, string_size);
        if (result == CARDANO_SUCCESS)
        {
            printf("Metadatum as string: %s\n", buffer);
        }
        else
        {
            printf("Failed to convert metadatum to string: %s\n", cardano_error_to_string(result));
        }
        // Free the buffer when done
        free(buffer);
    }
}

// Clean up the metadatum object once done
cardano_metadatum_unref(&metadatum);

See also

cardano_metadatum_get_string_size

Parameters:¶

cardano_metadatum_t *metadatum¶

[in] A pointer to the cardano_metadatum_t object to be converted. This parameter must not be NULL.

char *buffer¶

[out] A pointer to a character array where the null-terminated string will be stored. The buffer must be allocated by the caller and have a size of at least buffer_size bytes. This parameter must not be NULL.

size_t buffer_size¶

[in] The size of the buffer in bytes, including space for the null terminator.

Returns:¶

CARDANO_SUCCESS if the conversion was successful. Returns CARDANO_ERROR_POINTER_IS_NULL if metadatum or buffer is NULL. Returns CARDANO_ERROR_INSUFFICIENT_BUFFER_SIZE if buffer_size is insufficient to hold the string.

bool cardano_metadatum_equals(const cardano_metadatum_t *lhs, const cardano_metadatum_t *rhs)¶

Checks if two metadatum objects are equal.

This function compares two cardano_metadatum_t objects for equality. It checks if the contents of the two metadatum objects are identical.

Usage Example:

cardano_metadatum_t* metadatum1 = cardano_metadatum_new_bytes_from_hex("DEADBEEF", 8);
cardano_metadatum_t* metadatum2 = cardano_metadatum_new_bytes_from_hex("DEADBEEF", 8);

if (cardano_metadatum_equals(metadatum1, metadatum2))
{
  printf("metadatum1 is equal to metadatum2\n");
}
else
{
  printf("metadatum1 is not equal to metadatum2\n");
}

// Clean up the metadatum objects once done
cardano_metadatum_unref(&metadatum1);
cardano_metadatum_unref(&metadatum2);

Parameters:¶

const cardano_metadatum_t *lhs¶

[in] A constant pointer to the first cardano_metadatum_t object to be compared.

const cardano_metadatum_t *rhs¶

[in] A constant pointer to the second cardano_metadatum_t object to be compared.

Returns:¶

true if the two metadatum objects are equal (have the same contents), false otherwise.

void cardano_metadatum_unref(cardano_metadatum_t **metadatum)¶

Decrements the reference count of a metadatum object.

This function is responsible for managing the lifecycle of a cardano_metadatum_t object by decreasing its reference count. When the reference count reaches zero, the metadatum is finalized; its associated resources are released, and its memory is deallocated.

Usage Example:

cardano_metadatum_t* metadatum = cardano_metadatum_new();

// Perform operations with the metadatum...

cardano_metadatum_unref(&metadatum);
// At this point, metadatum is NULL and cannot be used.

Note

After calling cardano_metadatum_unref, the pointer to the cardano_metadatum_t object will be set to NULL to prevent its reuse.

Parameters:¶

cardano_metadatum_t **metadatum¶

[inout] A pointer to the pointer of the metadatum object. This double indirection allows the function to set the caller’s pointer to NULL, avoiding dangling pointer issues after the object has been freed.

void cardano_metadatum_ref(cardano_metadatum_t *metadatum)¶

Increases the reference count of the cardano_metadatum_t object.

This function is used to manually increment the reference count of a metadatum object, indicating that another part of the code has taken ownership of it. This ensures the object remains allocated and valid until all owners have released their reference by calling cardano_metadatum_unref.

Usage Example:

// Assuming metadatum is a previously created metadatum object

cardano_metadatum_ref(metadatum);

// Now metadatum can be safely used elsewhere without worrying about premature deallocation

Note

Always ensure that for every call to cardano_metadatum_ref there is a corresponding call to cardano_metadatum_unref to prevent memory leaks.

Parameters:¶

cardano_metadatum_t *metadatum¶

A pointer to the metadatum object whose reference count is to be incremented.

size_t cardano_metadatum_refcount(const cardano_metadatum_t *metadatum)¶

Retrieves the current reference count of the cardano_metadatum_t object.

This function returns the number of active references to a metadatum object. It’s useful for debugging purposes or managing the lifecycle of the object in complex scenarios.

Usage Example:

// Assuming metadatum is a previously created metadatum object

size_t ref_count = cardano_metadatum_refcount(metadatum);

printf("Reference count: %zu\n", ref_count);

Warning

This function does not account for transitive references. A transitive reference occurs when an object holds a reference to another object, rather than directly to the cardano_metadatum_t. As such, the reported count may not fully represent the total number of conceptual references in cases where such transitive relationships exist.

Parameters:¶

const cardano_metadatum_t *metadatum¶

A pointer to the metadatum object whose reference count is queried. The object must not be NULL.

Returns:¶

The number of active references to the specified metadatum object. If the object is properly managed (i.e., every cardano_metadatum_ref call is matched with a cardano_metadatum_unref call), this count should reach zero right before the object is deallocated.

void cardano_metadatum_set_last_error(cardano_metadatum_t *metadatum, const char *message)¶

Sets the last error message for a given metadatum object.

Records an error message in the metadatum’s last_error buffer, overwriting any existing message. This is useful for storing descriptive error information that can be later retrieved. The message is truncated if it exceeds the buffer’s capacity.

Note

The error message is limited to 1023 characters, including the null terminator, due to the fixed size of the last_error buffer.

Parameters:¶

cardano_metadatum_t *metadatum¶

[in] A pointer to the cardano_metadatum_t instance whose last error message is to be set. If NULL, the function does nothing.

const char *message¶

[in] A null-terminated string containing the error message. If NULL, the metadatum’s last_error is set to an empty string, indicating no error.

const char *cardano_metadatum_get_last_error(const cardano_metadatum_t *metadatum)¶

Retrieves the last error message recorded for a specific metadatum.

This function returns a pointer to the null-terminated string containing the last error message set by cardano_metadatum_set_last_error for the given metadatum. If no error message has been set, or if the last_error buffer was explicitly cleared, an empty string is returned, indicating no error.

Note

The returned string points to internal storage within the object and must not be modified by the caller. The string remains valid until the next call to cardano_metadatum_set_last_error for the same metadatum, or until the metadatum is deallocated.

Parameters:¶

const cardano_metadatum_t *metadatum¶

[in] A pointer to the cardano_metadatum_t instance whose last error message is to be retrieved. If the metadatum is NULL, the function returns a generic error message indicating the null metadatum.

Returns:¶

A pointer to a null-terminated string containing the last error message for the specified metadatum. If the metadatum is NULL, “Object is NULL.” is returned to indicate the error.