JSON Writer - Cardano C documentation

typedef struct cardano_json_writer_t cardano_json_writer_t¶

Provides a API for forward-only, non-cached writing of UTF-8 encoded JSON text.

cardano_json_writer_t *cardano_json_writer_new(cardano_json_format_t format)¶

Creates a new JSON writer instance.

This function initializes a new instance of a cardano_json_writer_t, which can be used to encode data into JSON format. The created writer manages its internal state and ensures that the generated JSON is syntactically valid.

The JSON writer can be used to encode JSON incrementally by invoking various write functions to add properties, values, and nested structures.

Usage Example:

cardano_json_writer_t* writer = cardano_json_writer_new();

if (writer == NULL)
{
  printf("Failed to create a JSON writer.\n");
  return EXIT_FAILURE;
}

// Use the writer to encode JSON data...

cardano_json_writer_unref(&writer); // Release resources when done

Note

The caller is responsible for managing the memory of the returned JSON writer instance. Use cardano_json_writer_unref to release resources when the writer is no longer needed.

Parameters:¶

cardano_json_format_t format¶: [in] The format of the JSON output (compact or pretty).

Returns:¶

A pointer to a newly allocated cardano_json_writer_t instance. Returns NULL if the creation fails due to insufficient memory or other initialization errors.

void cardano_json_writer_write_property_name(cardano_json_writer_t *writer, const char *name, size_t name_size)¶

Writes a property name to the JSON output.

This function writes the name of a JSON property to the output, preparing it for the subsequent value. Property names used within JSON objects must be followed by a value-writing function to form a valid key-value pair.

Usage Example:

cardano_json_writer_t* writer = cardano_json_writer_new();

cardano_json_writer_write_start_object(writer);
cardano_json_writer_write_property_name(writer, "name", 4); // Property: "name"
cardano_json_writer_write_string(writer, "John Doe", 8);    // Value: "John Doe"
cardano_json_writer_write_end_object(writer);

...

cardano_json_writer_unref(&writer); // Release resources

Parameters:¶

cardano_json_writer_t *writer¶: [in] A pointer to the cardano_json_writer_t instance.
const char *name¶: [in] A pointer to the property name string. The string does not need to be null-terminated, as its length is specified separately.
size_t name_size¶: [in] The size of the property name string in bytes.

Pre:¶

The JSON writer must currently be in an object context. Calling this function outside an object context will result in an error.

Pre:¶

The name string must not contain invalid JSON characters such as control characters.

void cardano_json_writer_write_bool(cardano_json_writer_t *writer, bool value)¶

Writes a boolean value to the JSON output.

This function writes a boolean value (true or false) as a JSON value. The value is represented in JSON’s boolean format, ensuring compatibility with all JSON parsers.

Usage Example:

// Create a new JSON writer
cardano_json_writer_t* writer = cardano_json_writer_new();

if (writer == NULL)
{
  printf("Failed to create JSON writer.\n");
  return EXIT_FAILURE;
}

// Start writing a JSON object
cardano_json_writer_write_start_object(writer);                  // Start object: {
cardano_json_writer_write_property_name(writer, "isEnabled", 9); // Property: "isEnabled"
cardano_json_writer_write_bool(writer, true);                    // Value: true
cardano_json_writer_write_end_object(writer);                    // End object: }

// Encode and print the resulting JSON
char buffer[128] = { 0 };
size_t encoded_size = cardano_json_writer_get_encoded_size(writer);

if (encoded_size > sizeof(buffer))
{
  printf("Buffer size is too small for the JSON output.\n");
  cardano_json_writer_unref(&writer);

  return EXIT_FAILURE;
}

cardano_error_t result = cardano_json_writer_encode(writer, (byte_t*)buffer, sizeof(buffer));
if (result != CARDANO_SUCCESS)
{
  printf("Failed to encode JSON.\n");
  printf("Error: %s\n", cardano_json_writer_get_last_error(writer));
  cardano_json_writer_unref(&writer);

  return EXIT_FAILURE;
}

printf("%s\n", buffer);

// Example output:
// {
//   "isEnabled": true
// }

// Clean up
cardano_json_writer_unref(&writer);

Note

If an error occurs during this function, the error is deferred until the user calls cardano_json_writer_encode or cardano_json_writer_encode_in_buffer. Once an error occurs, the writer enters an error state, and subsequent calls to writer functions will have no effect.

Parameters:¶

cardano_json_writer_t *writer¶: [in] A pointer to the cardano_json_writer_t instance. This must be a valid, non-NULL JSON writer.
bool value¶: [in] The boolean value to be written. Passing true writes the JSON literal true, and passing false writes the JSON literal false.

Pre:¶

The JSON writer must currently be in a valid context for writing a value (e.g., after a property name in an object or as an element in an array). Calling this function in an invalid context will result in deferred error reporting.

void cardano_json_writer_write_null(cardano_json_writer_t *writer)¶

Writes a JSON null value to the output.

This function writes the literal null value to the JSON output.

Usage Example:

cardano_json_writer_t* writer = cardano_json_writer_new();
if (writer == NULL)
{
  printf("Failed to create JSON writer.\n");
  return EXIT_FAILURE;
}

cardano_json_writer_write_start_object(writer);
cardano_json_writer_write_property_name(writer, "name", 4);
cardano_json_writer_write_null(writer); // Write "name": null
cardano_json_writer_write_end_object(writer);

char buffer[128];
size_t encoded_size = cardano_json_writer_get_encoded_size(writer);

if (encoded_size > sizeof(buffer))
{
  printf("Buffer size is too small for the JSON output.\n");
  cardano_json_writer_unref(&writer);

  return EXIT_FAILURE;
}

cardano_error_t result = cardano_json_writer_encode(writer, (byte_t*)buffer, sizeof(buffer));

if (result != CARDANO_SUCCESS)
{
  printf("Failed to encode JSON.\n");
  printf("Error: %s\n", cardano_json_writer_get_last_error(writer));
  cardano_json_writer_unref(&writer);
  return EXIT_FAILURE;
}

printf("%s\n", buffer);

// Example output:
// {
//  "name": null
// }

// Clean up
cardano_json_writer_unref(&writer);

Note

If an error occurs during this function, the error is deferred until the user calls cardano_json_writer_encode or cardano_json_writer_encode_in_buffer. Once an error occurs, the writer enters an error state, and subsequent calls to writer functions will have no effect.

Parameters:¶

cardano_json_writer_t *writer¶: [in] A pointer to the cardano_json_writer_t instance. This must be a valid, non-NULL JSON writer.

Pre:¶

The JSON writer must currently be in a valid context for writing a value (e.g., after a property name in an object or as an element in an array). Calling this function in an invalid context will result in error.

void cardano_json_writer_write_bigint(cardano_json_writer_t *writer, const cardano_bigint_t *bigint)¶

Writes a big integer value to the JSON output.

This function writes a big integer (cardano_bigint_t) as a JSON value. The value is encoded as a JSON string to ensure compatibility with JSON parsers that may not natively support extremely large integer values.

Usage Example:

 // Create a new JSON writer
 cardano_json_writer_t* writer = cardano_json_writer_new();

 if (writer == NULL)
 {
   printf("Failed to create JSON writer.\n");
   return EXIT_FAILURE;
 }

 // Create a big integer value
 cardano_bigint_t* bigint = cardano_bigint_from_string("123456789123456789");

 if (bigint == NULL)
 {
   printf("Failed to create big integer.\n");
   cardano_json_writer_unref(&writer);

   return EXIT_FAILURE;
 }

 cardano_json_writer_write_start_object(writer);
 cardano_json_writer_write_property_name(writer, "bigNumber", 9); // Property: "bigNumber"
 cardano_json_writer_write_bigint(writer, bigint);   // Value: "123456789123456789"
 cardano_json_writer_write_end_object(writer);

 // Encode and print the resulting JSON
 char buffer[128];
 size_t encoded_size = cardano_json_writer_get_encoded_size(writer);

 if (encoded_size > sizeof(buffer))
 {
   printf("Buffer size is too small for the JSON output.\n");
   cardano_bigint_unref(&bigint);
   cardano_json_writer_unref(&writer);

   return EXIT_FAILURE;
 }

 cardano_error_t result = cardano_json_writer_encode(writer, (byte_t*)buffer, sizeof(buffer));

 if (result != CARDANO_SUCCESS)
 {
   printf("Failed to encode JSON.\n");
   cardano_bigint_unref(&bigint);
   cardano_json_writer_unref(&writer);

   return EXIT_FAILURE;
 }

 printf("%s\n", buffer);

 // Example output:
 // {
 //   "bigNumber": "123456789123456789"
 // }

 // Clean up
 cardano_bigint_unref(&bigint);
 cardano_json_writer_unref(&writer);
}

Note

The big integer is serialized as a JSON string (e.g., "123456789123456789") to preserve its precision and avoid loss of information due to JSON’s numeric limitations.

Note

If an error occurs during this function, the error is deferred until the user calls cardano_json_writer_encode or cardano_json_writer_encode_in_buffer. Once an error occurs, the writer enters an error state, and subsequent calls to writer functions will have no effect.

Parameters:¶

cardano_json_writer_t *writer¶: [in] A pointer to the cardano_json_writer_t instance.
const cardano_bigint_t *bigint¶: [in] A pointer to the cardano_bigint_t instance representing the big integer to be written.

Pre:¶

The JSON writer must currently be in a valid context for writing a value (e.g., after a property name in an object or as an element in an array). Calling this function in an invalid context will result in deferred error reporting.

void cardano_json_writer_write_start_array(cardano_json_writer_t *writer)¶

Begins a JSON array in the output.

This function writes the opening bracket ([) of a JSON array. After calling this function, subsequent calls to writer functions can add elements to the array. The array must be closed with cardano_json_writer_write_end_array to produce a valid JSON structure.

Usage Example:

 cardano_json_writer_t* writer = cardano_json_writer_new();

 if (writer == NULL)
 {
   printf("Failed to create JSON writer.\n");

   return EXIT_FAILURE;
 }

 cardano_json_writer_write_start_object(writer);       // Start object: {
 cardano_json_writer_write_property_name(writer, "numbers", 7); // Property: "numbers"
 cardano_json_writer_write_start_array(writer);        // Start array: [
 cardano_json_writer_write_uint(writer, 1);         // Add element: 1
 cardano_json_writer_write_uint(writer, 2);         // Add element: 2
 cardano_json_writer_write_uint(writer, 3);         // Add element: 3
 cardano_json_writer_write_end_array(writer);          // End array: ]
 cardano_json_writer_write_end_object(writer);         // End object: }

 // Encode and print the resulting JSON
 char buffer[128];
 size_t encoded_size = cardano_json_writer_get_encoded_size(writer);

 if (encoded_size > sizeof(buffer))
 {
   printf("Buffer size is too small for the JSON output.\n");
   cardano_json_writer_unref(&writer);
   return EXIT_FAILURE;
 }

 cardano_error_t result = cardano_json_writer_encode(writer, (byte_t*)buffer, sizeof(buffer));
 if (result != CARDANO_SUCCESS)
 {
   printf("Failed to encode JSON.\n");
   printf("Error: %s\n", cardano_json_writer_get_last_error(writer));

   cardano_json_writer_unref(&writer);

   return EXIT_FAILURE;
 }

 printf("%s\n", buffer);

 // Example output:
 // {
 //  "numbers": [1, 2, 3]
 // }

 // Clean up
 cardano_json_writer_unref(&writer);
}

Note

If an error occurs during this function, the error is deferred until the user calls cardano_json_writer_encode or cardano_json_writer_encode_in_buffer. Once an error occurs, the writer enters an error state, and subsequent calls to writer functions will have no effect.

Parameters:¶

cardano_json_writer_t *writer¶: [in] A pointer to the cardano_json_writer_t instance. This must be a valid, non-NULL JSON writer.

Pre:¶

The JSON writer must currently be in a valid context for writing a value (e.g., after a property name in an object or as an element in another array). Calling this function in an invalid context will result in deferred error reporting.

void cardano_json_writer_write_end_array(cardano_json_writer_t *writer)¶

Ends a JSON array in the output.

This function writes the closing bracket (]) of a JSON array, marking the end of the array structure. It must be preceded by a corresponding call to cardano_json_writer_write_start_array.

Usage Example:

// Create a new JSON writer
cardano_json_writer_t* writer = cardano_json_writer_new();

if (writer == NULL)
{
 printf("Failed to create JSON writer.\n");
 return EXIT_FAILURE;
}

// Start writing a JSON object containing an array
cardano_json_writer_write_start_object(writer);      // Start object: {
cardano_json_writer_write_property_name(writer, "items", 5);  // Property: "items"
cardano_json_writer_write_start_array(writer);       // Start array: [
cardano_json_writer_write_string(writer, "item1", 5);      // Add element: "item1"
cardano_json_writer_write_string(writer, "item2", 5);      // Add element: "item2"
cardano_json_writer_write_end_array(writer);         // End array: ]
cardano_json_writer_write_end_object(writer);        // End object: }

char buffer[128];
size_t encoded_size = cardano_json_writer_get_encoded_size(writer);

if (encoded_size > sizeof(buffer))
{
 printf("Buffer size is too small for the JSON output.\n");
 cardano_json_writer_unref(&writer);
 return -1;
}

cardano_error_t result = cardano_json_writer_encode(writer, (byte_t*)buffer, sizeof(buffer));

if (result != CARDANO_SUCCESS)
{
  printf("Failed to encode JSON.\n");
  cardano_json_writer_unref(&writer);

  return -1;
}

printf("%s\n", buffer);

// Example output:
// {
//   "items": ["item1", "item2"]
// }

// Clean up
cardano_json_writer_unref(&writer);

Note

If an error occurs during this function, the error is deferred until the user calls cardano_json_writer_encode or cardano_json_writer_encode_in_buffer. Once an error occurs, the writer enters an error state, and subsequent calls to writer functions will have no effect.

Parameters:¶

cardano_json_writer_t *writer¶: [in] A pointer to the cardano_json_writer_t instance. This must be a valid, non-NULL JSON writer.

Pre:¶

The JSON writer must currently be in an array context. Calling this function outside an array context will result in deferred error reporting.

void cardano_json_writer_write_start_object(cardano_json_writer_t *writer)¶

Begins a JSON object in the output.

This function writes the opening curly brace ({) of a JSON object. After calling this function, subsequent calls to writer functions can add properties (key-value pairs) to the object. The object must be closed with cardano_json_writer_write_end_object to produce a valid JSON structure.

Usage Example:

// Create a new JSON writer
cardano_json_writer_t* writer = cardano_json_writer_new();
if (writer == NULL)
{
  printf("Failed to create JSON writer.\n");
  return EXIT_FAILURE;
}

// Start writing a JSON object
cardano_json_writer_write_start_object(writer);       // Start object: {
cardano_json_writer_write_property_name(writer, "name", 4); // Property: "name"
cardano_json_writer_write_string(writer, "John Doe", 8);    // Value: "John Doe"
cardano_json_writer_write_property_name(writer, "age", 3);  // Property: "age"
cardano_json_writer_write_uint(writer, 30);        // Value: 30
cardano_json_writer_write_end_object(writer);      // End object: }

// Encode and print the resulting JSON
char buffer[128];
size_t encoded_size = cardano_json_writer_get_encoded_size(writer);

if (encoded_size > sizeof(buffer))
{
  printf("Buffer size is too small for the JSON output.\n");
  cardano_json_writer_unref(&writer);
  return EXIT_FAILURE;
}

cardano_error_t result = cardano_json_writer_encode(writer, (byte_t*)buffer, sizeof(buffer));
if (result != CARDANO_SUCCESS)
{
  printf("Failed to encode JSON.\n");
  printf("Error: %s\n", cardano_json_writer_get_last_error(writer));

  cardano_json_writer_unref(&writer);
  return EXIT_FAILURE;
}

printf("%s\n", buffer);

// Example output:
// {
//   "name": "John Doe",
//   "age": 30
// }

// Clean up
cardano_json_writer_unref(&writer);

Note

If an error occurs during this function, the error is deferred until the user calls cardano_json_writer_encode or cardano_json_writer_encode_in_buffer. Once an error occurs, the writer enters an error state, and subsequent calls to writer functions will have no effect.

Parameters:¶

cardano_json_writer_t *writer¶: [in] A pointer to the cardano_json_writer_t instance. This must be a valid, non-NULL JSON writer.

Pre:¶

The JSON writer must currently be in a valid context for writing a value (e.g., after a property name in another object or as an element in an array). Calling this function in an invalid context will result in deferred error reporting.

void cardano_json_writer_write_end_object(cardano_json_writer_t *writer)¶

Ends a JSON object in the output.

This function writes the closing curly brace (}) of a JSON object, marking the end of the object structure. It must be preceded by a corresponding call to cardano_json_writer_write_start_object.

Usage Example:

cardano_json_writer_t* writer = cardano_json_writer_new();
if (writer == NULL)
{
  printf("Failed to create JSON writer.\n");
  return EXIT_FAILURE;
}

// Start writing a JSON object
cardano_json_writer_write_start_object(writer);       // Start object: {
cardano_json_writer_write_property_name(writer, "name", 4); // Property: "name"
cardano_json_writer_write_string(writer, "Alice", 5);    // Value: "Alice"
cardano_json_writer_write_property_name(writer, "age", 3);  // Property: "age"
cardano_json_writer_write_uint(writer, 25);        // Value: 25
cardano_json_writer_write_end_object(writer);      // End object: }

// Encode and print the resulting JSON
char buffer[128] = { 0 };
size_t encoded_size = cardano_json_writer_get_encoded_size(writer);

if (encoded_size > sizeof(buffer))
{
  printf("Buffer size is too small for the JSON output.\n");
  cardano_json_writer_unref(&writer);
  return EXIT_FAILURE;
}

cardano_error_t result = cardano_json_writer_encode(writer, (byte_t*)buffer, sizeof(buffer));
if (result != CARDANO_SUCCESS)
{
  printf("Failed to encode JSON.\n");
  printf("Error: %s\n", cardano_json_writer_get_last_error(writer));
  cardano_json_writer_unref(&writer);

  return EXIT_FAILURE;
}

printf("%s\n", buffer);

// Example output:
// {
//   "name": "Alice",
//   "age": 25
// }

// Clean up
cardano_json_writer_unref(&writer);

Note

If an error occurs during this function, the error is deferred until the user calls cardano_json_writer_encode or cardano_json_writer_encode_in_buffer. Once an error occurs, the writer enters an error state, and subsequent calls to writer functions will have no effect.

Parameters:¶

cardano_json_writer_t *writer¶: [in] A pointer to the cardano_json_writer_t instance. This must be a valid, non-NULL JSON writer.

Pre:¶

The JSON writer must currently be in an object context. Calling this function outside an object context will result in deferred error reporting.

void cardano_json_writer_write_raw_value(cardano_json_writer_t *writer, const char *data, size_t size)¶

Writes a raw JSON value directly to the output.

This function writes a raw JSON value to the output. The provided data must be a syntactically valid JSON value (e.g., a number, a string, a boolean, or a null). The JSON writer does not perform validation on the raw data; it assumes the caller has ensured the correctness of the value.

Usage Example:

// Create a new JSON writer
cardano_json_writer_t* writer = cardano_json_writer_new();

if (writer == NULL)
{
printf("Failed to create JSON writer.\n");
return EXIT_FAILURE;
}

// Start writing a JSON object
cardano_json_writer_write_start_object(writer);       // Start object: {
cardano_json_writer_write_property_name(writer, "rawData", 7); // Property: "rawData"
cardano_json_writer_write_raw_value(writer, "[1, 2, 3]", 9);   // Write raw value: [1, 2, 3]
cardano_json_writer_write_end_object(writer);         // End object: }

// Encode and print the resulting JSON
char buffer[128] = { 0 };

size_t encoded_size = cardano_json_writer_get_encoded_size(writer);

if (encoded_size > sizeof(buffer))
{
  printf("Buffer size is too small for the JSON output.\n");
  cardano_json_writer_unref(&writer);
  return -1;
}

cardano_error_t result = cardano_json_writer_encode(writer, (byte_t*)buffer, sizeof(buffer));

if (result != CARDANO_SUCCESS)
{
  printf("Failed to encode JSON.\n");
  cardano_json_writer_unref(&writer);
  return -1;
}

printf("%s\n", buffer);

// Example output:
// {
//  "rawData": [1, 2, 3]
// }

// Clean up
cardano_json_writer_unref(&writer);

Note

If an error occurs during this function, the error is deferred until the user calls cardano_json_writer_encode or cardano_json_writer_encode_in_buffer. Once an error occurs, the writer enters an error state, and subsequent calls to writer functions will have no effect.

Warning

The caller is responsible for ensuring the raw value is a valid JSON value. Invalid data may result in syntactically incorrect JSON output.

Parameters:¶

cardano_json_writer_t *writer¶: [in] A pointer to the cardano_json_writer_t instance. This must be a valid, non-NULL JSON writer.
const char *data¶: [in] A pointer to the raw JSON value as a string. The string does not need to be null-terminated, as its length is specified separately.
size_t size¶: [in] The size of the raw JSON value in bytes.

Pre:¶

The JSON writer must currently be in a valid context for writing a value (e.g., after a property name in an object or as an element in an array). Calling this function in an invalid context will result in deferred error reporting.

void cardano_json_writer_write_object(cardano_json_writer_t *writer, cardano_json_object_t *object)¶

Writes a JSON object to the writer.

This function serializes the contents of the provided cardano_json_object_t and writes it to the output stream managed by the writer.

Parameters:¶

cardano_json_writer_t *writer¶: [in] A pointer to the cardano_json_writer_t instance.
cardano_json_object_t *object¶: [in] A pointer to the cardano_json_object_t to be written.

void cardano_json_writer_write_uint(cardano_json_writer_t *writer, uint64_t value)¶

Writes an unsigned integer value to the JSON output.

This function writes an unsigned integer (uint64_t) as a JSON value. The value is written in its numeric representation, which is valid for all JSON parsers.

Usage Example:

// Create a new JSON writer
cardano_json_writer_t* writer = cardano_json_writer_new();

if (writer == NULL)
{
  printf("Failed to create JSON writer.\n");
  return EXIT_FAILURE;
}

// Start writing a JSON object
cardano_json_writer_write_start_object(writer);        // Start object
cardano_json_writer_write_property_name(writer, "count", 5); // Property: "count"
cardano_json_writer_write_uint(writer, 123456);        // Value: 123456
cardano_json_writer_write_end_object(writer);       // End object

// Encode and print the resulting JSON
char buffer[128] = { 0 };
size_t encoded_size = cardano_json_writer_get_encoded_size(writer);

if (encoded_size > sizeof(buffer))
{
  printf("Buffer size is too small for the JSON output.\n");
  cardano_json_writer_unref(&writer);

  return EXIT_FAILURE;
}

cardano_error_t result = cardano_json_writer_encode(writer, (byte_t*)buffer, sizeof(buffer));

if (result != CARDANO_SUCCESS)
{
  printf("Failed to encode JSON.\n");
  cardano_json_writer_unref(&writer);

  return EXIT_FAILURE;
}

printf("%s\n", buffer);

// Example output:
// {
//   "count": 123456
// }

// Clean up
cardano_json_writer_unref(&writer);

Note

If an error occurs during this function, the error is deferred until the user calls cardano_json_writer_encode or cardano_json_writer_encode_in_buffer. Once an error occurs, the writer enters an error state, and subsequent calls to writer functions will have no effect.

Parameters:¶

cardano_json_writer_t *writer¶: [in] A pointer to the cardano_json_writer_t instance. This must be a valid, non-NULL JSON writer.
uint64_t value¶: [in] The unsigned integer value to be written.

Pre:¶

The JSON writer must currently be in a valid context for writing a value (e.g., after a property name in an object or as an element in an array). Calling this function in an invalid context will result in deferred error reporting.

void cardano_json_writer_write_uint_as_string(cardano_json_writer_t *writer, uint64_t value)¶

Writes an unsigned integer value to the JSON output.

This function writes an unsigned integer (uint64_t) as a JSON string value. The value is written in its numeric representation as a string.

Usage Example:

// Create a new JSON writer
cardano_json_writer_t* writer = cardano_json_writer_new();

if (writer == NULL)
{
  printf("Failed to create JSON writer.\n");
  return EXIT_FAILURE;
}

// Start writing a JSON object
cardano_json_writer_write_start_object(writer);        // Start object
cardano_json_writer_write_property_name(writer, "count", 5); // Property: "count"
cardano_json_writer_write_uint(writer, 123456);        // Value: "123456"
cardano_json_writer_write_end_object(writer);       // End object

// Encode and print the resulting JSON
char buffer[128] = { 0 };
size_t encoded_size = cardano_json_writer_get_encoded_size(writer);

if (encoded_size > sizeof(buffer))
{
  printf("Buffer size is too small for the JSON output.\n");
  cardano_json_writer_unref(&writer);

  return EXIT_FAILURE;
}

cardano_error_t result = cardano_json_writer_encode(writer, (byte_t*)buffer, sizeof(buffer));

if (result != CARDANO_SUCCESS)
{
  printf("Failed to encode JSON.\n");
  cardano_json_writer_unref(&writer);

  return EXIT_FAILURE;
}

printf("%s\n", buffer);

// Example output:
// {
//   "count": "123456"
// }

// Clean up
cardano_json_writer_unref(&writer);

Note

If an error occurs during this function, the error is deferred until the user calls cardano_json_writer_encode or cardano_json_writer_encode_in_buffer. Once an error occurs, the writer enters an error state, and subsequent calls to writer functions will have no effect.

Parameters:¶

cardano_json_writer_t *writer¶: [in] A pointer to the cardano_json_writer_t instance. This must be a valid, non-NULL JSON writer.
uint64_t value¶: [in] The unsigned integer value to be written.

Pre:¶

The JSON writer must currently be in a valid context for writing a value (e.g., after a property name in an object or as an element in an array). Calling this function in an invalid context will result in deferred error reporting.

void cardano_json_writer_write_signed_int(cardano_json_writer_t *writer, int64_t value)¶

Writes an signed integer value to the JSON output.

This function writes an signed integer (int64_t) as a JSON value. The value is written in its numeric representation, which is valid for all JSON parsers.

Usage Example:

// Create a new JSON writer
cardano_json_writer_t* writer = cardano_json_writer_new();

if (writer == NULL)
{
  printf("Failed to create JSON writer.\n");
  return EXIT_FAILURE;
}

// Start writing a JSON object
cardano_json_writer_write_start_object(writer);        // Start object
cardano_json_writer_write_property_name(writer, "count", 5); // Property: "count"
cardano_json_writer_write_signed_int(writer, -123456);    // Value: -123456
cardano_json_writer_write_end_object(writer);       // End object

// Encode and print the resulting JSON
char buffer[128] = { 0 };
size_t encoded_size = cardano_json_writer_get_encoded_size(writer);

if (encoded_size > sizeof(buffer))
{
  printf("Buffer size is too small for the JSON output.\n");
  cardano_json_writer_unref(&writer);

  return EXIT_FAILURE;
}

cardano_error_t result = cardano_json_writer_encode(writer, (byte_t*)buffer, sizeof(buffer));

if (result != CARDANO_SUCCESS)
{
  printf("Failed to encode JSON.\n");
  cardano_json_writer_unref(&writer);

  return EXIT_FAILURE;
}

printf("%s\n", buffer);

// Example output:
// {
//   "count": -123456
// }

// Clean up
cardano_json_writer_unref(&writer);

Note

If an error occurs during this function, the error is deferred until the user calls cardano_json_writer_encode or cardano_json_writer_encode_in_buffer. Once an error occurs, the writer enters an error state, and subsequent calls to writer functions will have no effect.

Parameters:¶

cardano_json_writer_t *writer¶: [in] A pointer to the cardano_json_writer_t instance. This must be a valid, non-NULL JSON writer.
int64_t value¶: [in] The signed integer value to be written.

Pre:¶

The JSON writer must currently be in a valid context for writing a value (e.g., after a property name in an object or as an element in an array). Calling this function in an invalid context will result in deferred error reporting.

void cardano_json_writer_write_signed_int_as_string(cardano_json_writer_t *writer, int64_t value)¶

Writes an signed integer value to the JSON output.

This function writes an signed integer (int64_t) as a JSON string value. The value is written in its numeric representation as a string.

Usage Example:

// Create a new JSON writer
cardano_json_writer_t* writer = cardano_json_writer_new();

if (writer == NULL)
{
  printf("Failed to create JSON writer.\n");
  return EXIT_FAILURE;
}

// Start writing a JSON object
cardano_json_writer_write_start_object(writer);        // Start object
cardano_json_writer_write_property_name(writer, "count", 5); // Property: "count"
cardano_json_writer_write_signed_int_as_string(writer, -123456);    // Value: "-123456"
cardano_json_writer_write_end_object(writer);       // End object

// Encode and print the resulting JSON
char buffer[128] = { 0 };
size_t encoded_size = cardano_json_writer_get_encoded_size(writer);

if (encoded_size > sizeof(buffer))
{
  printf("Buffer size is too small for the JSON output.\n");
  cardano_json_writer_unref(&writer);

  return EXIT_FAILURE;
}

cardano_error_t result = cardano_json_writer_encode(writer, (byte_t*)buffer, sizeof(buffer));

if (result != CARDANO_SUCCESS)
{
  printf("Failed to encode JSON.\n");
  cardano_json_writer_unref(&writer);

  return EXIT_FAILURE;
}

printf("%s\n", buffer);

// Example output:
// {
//   "count": "-123456"
// }

// Clean up
cardano_json_writer_unref(&writer);

Note

If an error occurs during this function, the error is deferred until the user calls cardano_json_writer_encode or cardano_json_writer_encode_in_buffer. Once an error occurs, the writer enters an error state, and subsequent calls to writer functions will have no effect.

Parameters:¶

cardano_json_writer_t *writer¶: [in] A pointer to the cardano_json_writer_t instance. This must be a valid, non-NULL JSON writer.
int64_t value¶: [in] The signed integer value to be written.

Pre:¶

The JSON writer must currently be in a valid context for writing a value (e.g., after a property name in an object or as an element in an array). Calling this function in an invalid context will result in deferred error reporting.

void cardano_json_writer_write_double(cardano_json_writer_t *writer, double value)¶

Writes a double-precision floating-point value to the JSON output.

This function writes a double-precision floating-point number (double) as a JSON value. The value is written in its numeric representation, conforming to JSON’s number format.

Usage Example:

// Create a new JSON writer
cardano_json_writer_t* writer = cardano_json_writer_new();

if (writer == NULL)
{
  printf("Failed to create JSON writer.\n");

  return EXIT_FAILURE;
}

// Start writing a JSON object
cardano_json_writer_write_start_object(writer);           // Start object: {
cardano_json_writer_write_property_name(writer, "pi", 2); // Property: "pi"
cardano_json_writer_write_double(writer, 3.14159265359);  // Value: 3.14159265359
cardano_json_writer_write_property_name(writer, "e", 1);  // Property: "e"
cardano_json_writer_write_double(writer, 2.71828182845);  // Value: 2.71828182845
cardano_json_writer_write_end_object(writer);             // End object: }

// Encode and print the resulting JSON
char buffer[128] = { 0 };
size_t encoded_size = cardano_json_writer_get_encoded_size(writer);

if (encoded_size > sizeof(buffer))
{
  printf("Buffer size is too small for the JSON output.\n");
  cardano_json_writer_unref(&writer);

  return EXIT_FAILURE;
}

cardano_error_t result = cardano_json_writer_encode(writer, (byte_t*)buffer, sizeof(buffer));
if (result != CARDANO_SUCCESS)
{
  printf("Failed to encode JSON.\n");
  printf("Error: %s\n", cardano_json_writer_get_last_error(writer));
  cardano_json_writer_unref(&writer);

  return EXIT_FAILURE;
}

printf("%s\n", buffer);

// Example output:
// {
//   "pi": 3.14159265359,
//   "e": 2.71828182845
// }

// Clean up
cardano_json_writer_unref(&writer);

Note

If an error occurs during this function, the error is deferred until the user calls cardano_json_writer_encode or cardano_json_writer_encode_in_buffer. Once an error occurs, the writer enters an error state, and subsequent calls to writer functions will have no effect.

Parameters:¶

cardano_json_writer_t *writer¶: [in] A pointer to the cardano_json_writer_t instance. This must be a valid, non-NULL JSON writer.
double value¶: [in] The double value to be written.

Pre:¶

The JSON writer must currently be in a valid context for writing a value (e.g., after a property name in an object or as an element in an array). Calling this function in an invalid context will result in deferred error reporting.

void cardano_json_writer_write_double_as_string(cardano_json_writer_t *writer, double value)¶

Writes a double-precision floating-point value to the JSON output.

This function writes a double-precision floating-point number (double) as a string JSON value. The value is written in its numeric representation as a string.

Usage Example:

// Create a new JSON writer
cardano_json_writer_t* writer = cardano_json_writer_new();

if (writer == NULL)
{
  printf("Failed to create JSON writer.\n");

  return EXIT_FAILURE;
}

// Start writing a JSON object
cardano_json_writer_write_start_object(writer);           // Start object: {
cardano_json_writer_write_property_name(writer, "pi", 2); // Property: "pi"
cardano_json_writer_write_double_as_string(writer, "3.14159265359");  // Value: 3.14159265359
cardano_json_writer_write_property_name(writer, "e", 1);  // Property: "e"
cardano_json_writer_write_double_as_string(writer, "2.71828182845");  // Value: 2.71828182845
cardano_json_writer_write_end_object(writer);             // End object: }

// Encode and print the resulting JSON
char buffer[128] = { 0 };
size_t encoded_size = cardano_json_writer_get_encoded_size(writer);

if (encoded_size > sizeof(buffer))
{
  printf("Buffer size is too small for the JSON output.\n");
  cardano_json_writer_unref(&writer);

  return EXIT_FAILURE;
}

cardano_error_t result = cardano_json_writer_encode(writer, (byte_t*)buffer, sizeof(buffer));
if (result != CARDANO_SUCCESS)
{
  printf("Failed to encode JSON.\n");
  printf("Error: %s\n", cardano_json_writer_get_last_error(writer));
  cardano_json_writer_unref(&writer);

  return EXIT_FAILURE;
}

printf("%s\n", buffer);

// Example output:
// {
//   "pi": "3.14159265359",
//   "e": "2.71828182845"
// }

// Clean up
cardano_json_writer_unref(&writer);

Note

If an error occurs during this function, the error is deferred until the user calls cardano_json_writer_encode or cardano_json_writer_encode_in_buffer. Once an error occurs, the writer enters an error state, and subsequent calls to writer functions will have no effect.

Parameters:¶

cardano_json_writer_t *writer¶: [in] A pointer to the cardano_json_writer_t instance. This must be a valid, non-NULL JSON writer.
double value¶: [in] The double value to be written.

Pre:¶

The JSON writer must currently be in a valid context for writing a value (e.g., after a property name in an object or as an element in an array). Calling this function in an invalid context will result in deferred error reporting.

void cardano_json_writer_write_buffer_as_hex(cardano_json_writer_t *writer, const cardano_buffer_t *value)¶

Writes the contents of a buffer as a JSON string (hex encoded).

This function converts the binary data from the cardano_buffer_t into its hexadecimal string representation and writes it to the JSON output enclosed in quotes.

Note

If memory allocation for the hex string fails or the buffer-to-hex conversion fails, this function will set the writer's last error and return without writing to the JSON stream.

Parameters:¶

cardano_json_writer_t *writer¶: [in] A pointer to the cardano_json_writer_t instance.
const cardano_buffer_t *value¶: [in] The cardano_buffer_t containing the binary data to be written.

void cardano_json_writer_write_bytes_as_hex(cardano_json_writer_t *writer, const byte_t *bytes, size_t bytes_size)¶

Writes a raw byte array as a JSON string (hex encoded).

Note

If the bytes pointer is NULL, bytes_size is 0, or memory allocation for the temporary buffer fails, this function will set the writer's last error and return without writing to the JSON stream.

Parameters:¶

cardano_json_writer_t *writer¶: [in] A pointer to the cardano_json_writer_t instance.
const byte_t *bytes¶: [in] A pointer to the raw byte array to be written.
size_t bytes_size¶: [in] The number of bytes in the bytes array.

void cardano_json_writer_write_bytes_as_bech32(cardano_json_writer_t *writer, const char *hrp, size_t hrp_length, const byte_t *bytes, size_t bytes_size)¶

Writes a raw byte array as a quoted Bech32 string to the JSON output.

This function is a utility helper that converts a raw byte payload (hash or address data) into a Bech32 string using the specified Human-Readable Part (HRP) and writes the result as a JSON string literal (enclosed in quotes).

Parameters:¶

cardano_json_writer_t *writer¶: [in] A pointer to the cardano_json_writer_t instance.
const char *hrp¶: [in] The Human-Readable Part (HRP/prefix) for the Bech32 encoding (e.g., “stake1”, “pool1”).
size_t hrp_length¶: [in] The length of the HRP string.
const byte_t *bytes¶: [in] The raw byte array (data payload) to be encoded.
size_t bytes_size¶: [in] The size of the raw byte array.

void cardano_json_writer_write_buffer_as_bech32(cardano_json_writer_t *writer, const char *hrp, size_t hrp_length, const cardano_buffer_t *value)¶

Writes a raw byte array as a quoted Bech32 string to the JSON output.

This function is a utility helper that converts a raw byte payload (hash or address data) into a Bech32 string using the specified Human-Readable Part (HRP) and writes the result as a JSON string literal (enclosed in quotes).

Parameters:¶

cardano_json_writer_t *writer¶: [in] A pointer to the cardano_json_writer_t instance.
const char *hrp¶: [in] The Human-Readable Part (HRP/prefix) for the Bech32 encoding (e.g., “stake1”, “pool1”).
size_t hrp_length¶: [in] The length of the HRP string.
const cardano_buffer_t *value¶: [in] The cardano_buffer_t containing the binary data to be written.

void cardano_json_writer_write_string(cardano_json_writer_t *writer, const char *value, size_t value_size)¶

Writes a string value to the JSON output.

This function writes a string value to the JSON output. The string will be enclosed in double quotes and any necessary escaping for special characters (e.g., quotes, backslashes) will be handled automatically by the writer.

Usage Example:

// Create a new JSON writer
cardano_json_writer_t* writer = cardano_json_writer_new();

if (writer == NULL)
{
  printf("Failed to create JSON writer.\n");
  printf("Error: %s\n", cardano_json_writer_get_last_error(writer));

  return EXIT_FAILURE;
}

// Start writing a JSON object
cardano_json_writer_write_start_object(writer);                // Start object: {
cardano_json_writer_write_property_name(writer, "message", 7); // Property: "message"
cardano_json_writer_write_string(writer, "Hello, World!", 13); // Value: "Hello, World!"
cardano_json_writer_write_end_object(writer);                  // End object: }

// Encode and print the resulting JSON
char buffer[128] = { 0 };
size_t encoded_size = cardano_json_writer_get_encoded_size(writer);

if (encoded_size > sizeof(buffer))
{
 printf("Buffer size is too small for the JSON output.\n");
 printf("Error: %s\n", cardano_json_writer_get_last_error(writer));

 cardano_json_writer_unref(&writer);

 return EXIT_FAILURE;
}

cardano_error_t result = cardano_json_writer_encode(writer, (byte_t*)buffer, sizeof(buffer));

if (result != CARDANO_SUCCESS)
{
  printf("Failed to encode JSON.\n");
  cardano_json_writer_unref(&writer);

  return EXIT_FAILURE;
}

printf("%s\n", buffer);

// Example output:
// {
//   "message": "Hello, World!"
// }

// Clean up
cardano_json_writer_unref(&writer);

Note

If an error occurs during this function, the error is deferred until the user calls cardano_json_writer_encode or cardano_json_writer_encode_in_buffer. Once an error occurs, the writer enters an error state, and subsequent calls to writer functions will have no effect.

Note

The writer will handle UTF-8 encoded strings. It is the caller’s responsibility to ensure that the input string is valid UTF-8.

Parameters:¶

cardano_json_writer_t *writer¶: [in] A pointer to the cardano_json_writer_t instance. This must be a valid, non-NULL JSON writer.
const char *value¶: [in] A pointer to the string to be written. The string does not need to be null-terminated, as its length is specified separately.
size_t value_size¶: [in] The size of the string in bytes.

Pre:¶

The JSON writer must currently be in a valid context for writing a value (e.g., after a property name in an object or as an element in an array). Calling this function in an invalid context will result in deferred error reporting.

cardano_json_context_t cardano_json_writer_get_context(cardano_json_writer_t *writer)¶

Gets the current context of the JSON writer.

This function retrieves the current context of the JSON writer, indicating whether the writer is in a root state (brand new with no written output), inside an object, or inside an array. This information can be used by objects or arrays that write themselves to determine whether to initialize the root object or continue writing within an existing context.

Usage Example:

cardano_json_context_t context = cardano_json_writer_get_context(writer);

if (context == CARDANO_JSON_CONTEXT_ROOT)
{
  cardano_json_writer_write_start_object(writer);
}

cardano_json_writer_write_property_name(writer, "key", 3);
cardano_json_writer_write_string(writer, "value", 5);

if (context == CARDANO_JSON_CONTEXT_ROOT)
{
  // Close the root object if we opened it
  cardano_json_writer_write_end_object(writer);
}

Note

If the writer is in an error state or is NULL, the function returns CARDANO_JSON_CONTEXT_ROOT.

Parameters:¶

cardano_json_writer_t *writer¶: [in] A pointer to the cardano_json_writer_t instance. This must be a valid, non-NULL JSON writer.

Returns:¶

A cardano_json_context_t value representing the current context:

CARDANO_JSON_CONTEXT_ROOT: The writer is in the root state (no context set, no output started).
CARDANO_JSON_CONTEXT_OBJECT: The writer is inside an object.
CARDANO_JSON_CONTEXT_ARRAY: The writer is inside an array.

size_t cardano_json_writer_get_encoded_size(cardano_json_writer_t *writer)¶

Calculates the required buffer size for the encoded data.

This function determines the size of the buffer needed to store the data encoded by the writer. It is intended to be used before calling cardano_json_writer_encode to allocate a buffer of appropriate size.

Example usage:

cardano_json_writer_t* writer = cardano_json_writer_new();

// Assume writer has been used to encode some JSON data here

size_t required_size = cardano_json_writer_get_encoded_size(writer);

// Now required_size can be used to allocate a buffer of appropriate size
byte_t* data = (byte_t*)malloc(required_size);

if (byte_t != NULL)
{
  if (cardano_json_writer_encode(writer, data, required_size) == CARDANO_SUCCESS)
  {
    // Operate on the encoded data
  }

  free(data); // Free the allocated string after use
}

cardano_json_writer_unref(&writer); // Properly dispose of the writer after use

Parameters:¶

cardano_json_writer_t *writer¶: [in] The source writer whose encoded data size is being calculated.

Returns:¶

The size of the buffer required to store the writer’s encoded data. Returns 0 if the writer is NULL or contains no data.

cardano_error_t cardano_json_writer_encode(cardano_json_writer_t *writer, char *data, size_t size)¶

Encodes data from the writer’s context into JSON format and outputs it to a provided buffer.

This function encodes data prepared in the writer’s internal context into JSON format and writes it into an output buffer specified by the caller.

cardano_json_writer_t* writer = cardano_json_writer_new();

byte_t buffer[256]; // Pre-allocated buffer with sufficient space for the encoded data

cardano_error_t result = cardano_json_writer_encode(writer, buffer, sizeof(buffer));

if (result == CARDANO_SUCCESS)
{
  printf("Encoded JSON data successfully. Bytes written: %zu\n", sizeof(buffer));
}
else
{
  printf("Failed to encode JSON data. Error code: %d\n", result);
}

cardano_json_writer_unref(&writer); // Properly dispose of the writer after use

Parameters:¶

cardano_json_writer_t *writer¶: [in] A pointer to the cardano_json_writer_t structure representing the context and state for the JSON encoding operation.
char *data¶: [in] A pointer to a byte array where the encoded data will be written. The function will fill this buffer with the JSON-encoded data.
size_t size¶: [in] The size of the data byte array, indicating how much space is available for writing the encoded data.

Returns:¶

A cardano_error_t indicating the outcome of the operation. Returns CARDANO_SUCCESS if the data is successfully encoded into JSON format and stored in the provided buffer. If the operation fails, an error code is returned indicating the specific reason for failure. Detailed information on possible error codes and their meanings can be found in the cardano_error_t documentation.

cardano_error_t cardano_json_writer_encode_in_buffer(cardano_json_writer_t *writer, cardano_buffer_t **buffer)¶

Encodes data from the writer’s context into JSON format and outputs it into a new buffer.

This function encodes data prepared in the writer’s internal context into JSON format and writes it into a buffer. The function will create a new buffer instance to store the encoded data.

cardano_json_writer_t* writer = cardano_json_writer_new();
cardano_buffer_t* buffer = NULL; // Buffer will be allocated by the function

cardano_error_t result = cardano_json_writer_encode_in_buffer(writer, &buffer);

if (result == CARDANO_SUCCESS)
{
  printf("Encoded JSON data successfully. Bytes written: %zu\n", cardano_buffer_get_size(buffer));
}
else
{
  printf("Failed to encode JSON data. Error code: %d\n", result);
}

cardano_buffer_unref(&buffer); // Properly dispose of the buffer after use
cardano_json_writer_unref(&writer); // Properly dispose of the writer after use

Parameters:¶

cardano_json_writer_t *writer¶: [in] A pointer to the cardano_json_writer_t structure representing the context and state for the JSON encoding operation.
cardano_buffer_t **buffer¶: [out] A pointer to a cardano_buffer_t object where the encoded data will be stored. The function will allocate and fill this buffer with the JSON-encoded data. It is best to initialize this pointer as NULL. The caller is responsible for managing the lifecycle of the buffer, specifically releasing it by calling cardano_buffer_unref when it is no longer needed.

Returns:¶

A cardano_error_t indicating the outcome of the operation. Returns CARDANO_SUCCESS if the data is successfully encoded into JSON format and stored in the provided buffer. If the operation fails, an error code is returned indicating the specific reason for failure. Detailed information on possible error codes and their meanings can be found in the cardano_error_t documentation.

cardano_error_t cardano_json_writer_reset(cardano_json_writer_t *writer)¶

Resets the writer, clearing all written data.

This function resets the internal state of the JSON writer, effectively removing any data that has been written to it. This is useful for reusing a writer instance without needing to create a new one, especially when working with sequences of data encoding tasks.

cardano_json_writer_t* writer = cardano_json_writer_new();

// Write some data to the writer here

cardano_error_t reset_result = cardano_json_writer_reset(writer);

if (reset_result == CARDANO_SUCCESS)
{
 printf("Writer reset successfully.\n");
}
else
{
 printf("Failed to reset writer. Error code: %d\n", reset_result);
}
// The writer can now be reused for new data without creating a new instance

cardano_json_writer_unref(&writer); // Clean up when done using the writer

Parameters:¶

cardano_json_writer_t *writer¶: [in] The JSON writer instance to reset.

Returns:¶

A cardano_error_t indicating the outcome of the operation. CARDANO_SUCCESS is returned if the writer is successfully reset. If the operation fails, an error code is returned that indicates the specific reason for failure. For detailed information on possible error codes and their meanings, consult the cardano_error_t documentation.

void cardano_json_writer_unref(cardano_json_writer_t **json_writer)¶

Decrements the reference count of a JSON writer object.

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

Usage Example:

cardano_json_writer_t* writer = cardano_json_writer_new();

// Perform operations with the writer...

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

Note

After calling cardano_json_writer_unref, the pointer to the cardano_json_writer_t object will be set to NULL to prevent its reuse.

Parameters:¶

cardano_json_writer_t **json_writer¶: [inout] A pointer to the pointer of the JSON writer 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_json_writer_ref(cardano_json_writer_t *json_writer)¶

Increases the reference count of the cardano_json_writer_t object.

This function is used to manually increment the reference count of a JSON writer 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_json_writer_unref.

Usage Example:

// Assuming writer is a previously created JSON writer object

cardano_json_writer_ref(writer);

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

Note

Always ensure that for every call to cardano_json_writer_ref there is a corresponding call to cardano_json_writer_unref to prevent memory leaks.

Parameters:¶

cardano_json_writer_t *json_writer¶: A pointer to the JSON writer object whose reference count is to be incremented.

size_t cardano_json_writer_refcount(const cardano_json_writer_t *json_writer)¶

Retrieves the current reference count of the cardano_json_writer_t object.

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

Usage Example:

// Assuming writer is a previously created JSON writer object

size_t ref_count = cardano_json_writer_refcount(writer);

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_json_writer_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_json_writer_t *json_writer¶: A pointer to the JSON writer object whose reference count is queried. The object must not be NULL.

Returns:¶

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

void cardano_json_writer_set_last_error(cardano_json_writer_t *writer, const char *message)¶

Sets the last error message for a given JSON writer object.

Records an error message in the JSON writer’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_json_writer_t *writer¶: [in] A pointer to the cardano_json_writer_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 writer’s last_error is set to an empty string, indicating no error.

const char *cardano_json_writer_get_last_error(const cardano_json_writer_t *writer)¶

Retrieves the last error message recorded for a specific writer.

This function returns a pointer to the null-terminated string containing the last error message set by cardano_json_writer_set_last_error for the given writer. 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_json_writer_set_last_error for the same writer, or until the writer is deallocated.

Parameters:¶

const cardano_json_writer_t *writer¶: [in] A pointer to the cardano_json_writer_t instance whose last error message is to be retrieved. If the writer is NULL, the function returns a generic error message indicating the null writer.

Returns:¶

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

JSON Writer¶