JsonBuilder: JSON-GLib Reference Manual

## JsonBuilder JsonBuilder — Generates JSON trees |

## Functions

JsonBuilder * | json_builder_new ()
JsonNode * | json_builder_get_root ()
void | json_builder_reset ()
JsonBuilder * | json_builder_begin_array ()
JsonBuilder * | json_builder_end_array ()
JsonBuilder * | json_builder_begin_object ()
JsonBuilder * | json_builder_set_member_name ()
JsonBuilder * | json_builder_end_object ()
JsonBuilder * | json_builder_add_value ()
JsonBuilder * | json_builder_add_int_value ()
JsonBuilder * | json_builder_add_double_value ()
JsonBuilder * | json_builder_add_boolean_value ()
JsonBuilder * | json_builder_add_string_value ()
JsonBuilder * | json_builder_add_null_value ()

## Types and Values

struct | JsonBuilder
struct | JsonBuilderClass

## Object Hierarchy

        GObject
        ╰── JsonBuilder

## Description

JsonBuilder provides an object for generating a JSON tree. You can generate only one tree with one JsonBuilder instance.

The root of the JSON tree can be either a JsonObject or a JsonArray. Thus the first call must necessarily be either `json_builder_begin_object()` or `json_builder_begin_array()`.

For convenience to language bindings, JsonBuilder returns itself from most of functions, making it easy to chain function calls.

## Functions

### json_builder_new ()

    JsonBuilder *
    json_builder_new (void);

Creates a new JsonBuilder. You can use this object to generate a JSON tree and obtain the root JsonNode.

#### Returns

the newly created JsonBuilder instance

### json_builder_get_root ()

    JsonNode *
    json_builder_get_root (JsonBuilder *builder);

Returns the root of the current constructed tree, if the build is complete (ie: all opened objects, object members and arrays are being closed).

#### Parameters

builder | a JsonBuilder |

#### Returns

the JsonNode, or `NULL` if the build is not complete. Free the returned value with `json_node_free()`.

[transfer full]

### json_builder_reset ()

    void
    json_builder_reset (JsonBuilder *builder);

Resets the state of the `builder` back to its initial state.

#### Parameters

builder | a JsonBuilder |

### json_builder_begin_array ()

    JsonBuilder *
    json_builder_begin_array (JsonBuilder *builder);

Opens a subarray inside the given `builder` . When done adding members to the subarray, `json_builder_end_array()` must be called.

Can be called for first or only if the call is associated to an object member or an array element.

#### Parameters

builder | a JsonBuilder |

#### Returns

the JsonBuilder, or `NULL` if the call was inconsistent.

[transfer none]

### json_builder_end_array ()

    JsonBuilder *
    json_builder_end_array (JsonBuilder *builder);

Closes the subarray inside the given `builder` that was opened by the most recent call to `json_builder_begin_array()`.

Cannot be called after `json_builder_set_member_name()`.

#### Parameters

builder | a JsonBuilder |

#### Returns

the JsonBuilder, or `NULL` if the call was inconsistent.

[transfer none]

### json_builder_begin_object ()

    JsonBuilder *
    json_builder_begin_object (JsonBuilder *builder);

Opens a subobject inside the given `builder` . When done adding members to the subobject, `json_builder_end_object()` must be called.

Can be called for first or only if the call is associated to an object member or an array element.

#### Parameters

builder | a JsonBuilder |

#### Returns

the JsonBuilder, or `NULL` if the call was inconsistent.

[transfer none]

### json_builder_set_member_name ()

    JsonBuilder *
    json_builder_set_member_name (JsonBuilder *builder,
                                  const gchar *member_name);

Set the name of the next member in an object. The next call must add a value, open an object or an array.

Can be called only if the call is associated to an object.

#### Parameters

builder | a JsonBuilder |
member_name | the name of the member |

#### Returns

the JsonBuilder, or `NULL` if the call was inconsistent.

[transfer none]

### json_builder_end_object ()

    JsonBuilder *
    json_builder_end_object (JsonBuilder *builder);

Closes the subobject inside the given `builder` that was opened by the most recent call to `json_builder_begin_object()`.

Cannot be called after `json_builder_set_member_name()`.

#### Parameters

builder | a JsonBuilder |

#### Returns

the JsonBuilder, or `NULL` if the call was inconsistent.

[transfer none]

### json_builder_add_value ()

    JsonBuilder *
    json_builder_add_value (JsonBuilder *builder,
                            JsonNode *node);

If called after `json_builder_set_member_name()`, sets `node` as member of the most recent opened object, otherwise `node` is added as element of the most recent opened array.

The builder will take ownership of the JsonNode.

#### Parameters

builder | a JsonBuilder |
node | the value of the member or element. | [transfer full]

#### Returns

the JsonBuilder, or `NULL` if the call was inconsistent.

[transfer none]

### json_builder_add_int_value ()

    JsonBuilder *
    json_builder_add_int_value (JsonBuilder *builder,
                                gint64 value);

If called after `json_builder_set_member_name()`, sets `value` as member of the most recent opened object, otherwise `value` is added as element of the most recent opened array.

See also: `json_builder_add_value()`

#### Parameters

builder | a JsonBuilder |
value | the value of the member or element |

#### Returns

the JsonBuilder, or `NULL` if the call was inconsistent.

[transfer none]

### json_builder_add_double_value ()

    JsonBuilder *
    json_builder_add_double_value (JsonBuilder *builder,
                                   gdouble value);

If called after `json_builder_set_member_name()`, sets `value` as member of the most recent opened object, otherwise `value` is added as element of the most recent opened array.

See also: `json_builder_add_value()`

#### Parameters

builder | a JsonBuilder |
value | the value of the member or element |

#### Returns

the JsonBuilder, or `NULL` if the call was inconsistent.

[transfer none]

### json_builder_add_boolean_value ()

    JsonBuilder *
    json_builder_add_boolean_value (JsonBuilder *builder,
                                    gboolean value);

If called after `json_builder_set_member_name()`, sets `value` as member of the most recent opened object, otherwise `value` is added as element of the most recent opened array.

See also: `json_builder_add_value()`

#### Parameters

builder | a JsonBuilder |
value | the value of the member or element |

#### Returns

the JsonBuilder, or `NULL` if the call was inconsistent.

[transfer none]

### json_builder_add_string_value ()

    JsonBuilder *
    json_builder_add_string_value (JsonBuilder *builder,
                                   const gchar *value);

If called after `json_builder_set_member_name()`, sets `value` as member of the most recent opened object, otherwise `value` is added as element of the most recent opened array.

See also: `json_builder_add_value()`

#### Parameters

builder | a JsonBuilder |
value | the value of the member or element |

#### Returns

the JsonBuilder, or `NULL` if the call was inconsistent.

[transfer none]

### json_builder_add_null_value ()

    JsonBuilder *
    json_builder_add_null_value (JsonBuilder *builder);

If called after `json_builder_set_member_name()`, sets null as member of the most recent opened object, otherwise null is added as element of the most recent opened array.

See also: `json_builder_add_value()`

#### Parameters

builder | a JsonBuilder |

#### Returns

the JsonBuilder, or `NULL` if the call was inconsistent.

[transfer none]

## Types and Values

### struct JsonBuilder

    struct JsonBuilder;

The `JsonBuilder` structure contains only private data and should be accessed using the provided API

Since 0.12

### struct JsonBuilderClass

    struct JsonBuilderClass {
    };

The `JsonBuilderClass` structure contains only private data

Since 0.12

## See Also

JsonGenerator