JSON Object

JSON Object — a JSON object representation

Synopsis

#include <json-glib/json-glib.h>

                    JsonObject;
JsonObject *        json_object_new                     (void);
JsonObject *        json_object_ref                     (JsonObject *object);
void                json_object_unref                   (JsonObject *object);
void                json_object_seal                    (JsonObject *object);
gboolean            json_object_is_immutable            (JsonObject *object);
guint               json_object_hash                    (gconstpointer key);
gboolean            json_object_equal                   (gconstpointer a,
                                                         gconstpointer b);

void                json_object_add_member              (JsonObject *object,
                                                         const gchar *member_name,
                                                         JsonNode *node);
void                json_object_set_member              (JsonObject *object,
                                                         const gchar *member_name,
                                                         JsonNode *node);
gboolean            json_object_has_member              (JsonObject *object,
                                                         const gchar *member_name);
JsonNode *          json_object_get_member              (JsonObject *object,
                                                         const gchar *member_name);
JsonNode *          json_object_dup_member              (JsonObject *object,
                                                         const gchar *member_name);
GList *             json_object_get_members             (JsonObject *object);
GList *             json_object_get_values              (JsonObject *object);
guint               json_object_get_size                (JsonObject *object);
void                json_object_remove_member           (JsonObject *object,
                                                         const gchar *member_name);
void                (*JsonObjectForeach)                (JsonObject *object,
                                                         const gchar *member_name,
                                                         JsonNode *member_node,
                                                         gpointer user_data);
void                json_object_foreach_member          (JsonObject *object,
                                                         JsonObjectForeach func,
                                                         gpointer data);
                    JsonObjectIter;
void                json_object_iter_init               (JsonObjectIter *iter,
                                                         JsonObject *object);
gboolean            json_object_iter_next               (JsonObjectIter *iter,
                                                         const gchar **member_name,
                                                         JsonNode **member_node);

void                json_object_set_array_member        (JsonObject *object,
                                                         const gchar *member_name,
                                                         JsonArray *value);
JsonArray *         json_object_get_array_member        (JsonObject *object,
                                                         const gchar *member_name);
void                json_object_set_boolean_member      (JsonObject *object,
                                                         const gchar *member_name,
                                                         gboolean value);
gboolean            json_object_get_boolean_member      (JsonObject *object,
                                                         const gchar *member_name);
void                json_object_set_double_member       (JsonObject *object,
                                                         const gchar *member_name,
                                                         gdouble value);
gdouble             json_object_get_double_member       (JsonObject *object,
                                                         const gchar *member_name);
void                json_object_set_int_member          (JsonObject *object,
                                                         const gchar *member_name,
                                                         gint64 value);
gint64              json_object_get_int_member          (JsonObject *object,
                                                         const gchar *member_name);
void                json_object_set_null_member         (JsonObject *object,
                                                         const gchar *member_name);
gboolean            json_object_get_null_member         (JsonObject *object,
                                                         const gchar *member_name);
void                json_object_set_object_member       (JsonObject *object,
                                                         const gchar *member_name,
                                                         JsonObject *value);
JsonObject *        json_object_get_object_member       (JsonObject *object,
                                                         const gchar *member_name);
void                json_object_set_string_member       (JsonObject *object,
                                                         const gchar *member_name,
                                                         const gchar *value);
const gchar *       json_object_get_string_member       (JsonObject *object,
                                                         const gchar *member_name);

Object Hierarchy

  GBoxed
   +----JsonObject

Description

JsonObject is the representation of the object type inside JSON. It contains JsonNodes, which may contain fundamental types, arrays or other objects; each node inside an object, or "member", is accessed using a unique string, or "name".

Since objects can be expensive, they are reference counted. You can control the lifetime of a JsonObject using json_object_ref() and json_object_unref().

To add or overwrite a member with a given name, use json_object_set_member(). To extract a member with a given name, use json_object_get_member(). To retrieve the list of members, use json_object_get_members(). To retrieve the size of the object (that is, the number of members it has), use json_object_get_size().

Details

JsonObject

typedef struct _JsonObject JsonObject;

A JSON object type. The contents of the JsonObject structure are private and should only be accessed by the provided API


json_object_new ()

JsonObject *        json_object_new                     (void);

Creates a new JsonObject, an JSON object type representation.

Returns :

the newly created JsonObject. [transfer full]

json_object_ref ()

JsonObject *        json_object_ref                     (JsonObject *object);

Increase by one the reference count of a JsonObject.

object :

a JsonObject

Returns :

the passed JsonObject, with the reference count increased by one. [transfer none]

json_object_unref ()

void                json_object_unref                   (JsonObject *object);

Decreases by one the reference count of a JsonObject. If the reference count reaches zero, the object is destroyed and all its allocated resources are freed.

object :

a JsonObject

json_object_seal ()

void                json_object_seal                    (JsonObject *object);

Seals the JsonObject, making it immutable to further changes. This will recursively seal all members of the object too.

If the object is already immutable, this is a no-op.

object :

a JsonObject

Since 1.2


json_object_is_immutable ()

gboolean            json_object_is_immutable            (JsonObject *object);

Check whether the given object has been marked as immutable by calling json_object_seal() on it.

object :

a JsonObject

Returns :

TRUE if the object is immutable

Since 1.2


json_object_hash ()

guint               json_object_hash                    (gconstpointer key);

Calculate a hash value for the given key (a JsonObject).

The hash is calculated over the object and all its members, recursively. If the object is immutable, this is a fast operation; otherwise, it scales proportionally with the number of members in the object.

key :

a JSON object to hash. [type JsonObject]

Returns :

hash value for key

Since 1.2


json_object_equal ()

gboolean            json_object_equal                   (gconstpointer a,
                                                         gconstpointer b);

Check whether a and b are equal JsonObjects, meaning they have the same set of members, and the values of corresponding members are equal.

a :

a JSON object. [type JsonObject]

b :

another JSON object. [type JsonObject]

Returns :

TRUE if a and b are equal; FALSE otherwise

Since 1.2


json_object_add_member ()

void                json_object_add_member              (JsonObject *object,
                                                         const gchar *member_name,
                                                         JsonNode *node);

Warning

json_object_add_member has been deprecated since version 0.8 and should not be used in newly-written code. Use json_object_set_member() instead

Adds a member named member_name and containing node into a JsonObject. The object will take ownership of the JsonNode.

This function will return if the object already contains a member member_name.

object :

a JsonObject

member_name :

the name of the member

node :

the value of the member. [transfer full]

json_object_set_member ()

void                json_object_set_member              (JsonObject *object,
                                                         const gchar *member_name,
                                                         JsonNode *node);

Sets node as the value of member_name inside object.

If object already contains a member called member_name then the member's current value is overwritten. Otherwise, a new member is added to object.

object :

a JsonObject

member_name :

the name of the member

node :

the value of the member. [transfer full]

Since 0.8


json_object_has_member ()

gboolean            json_object_has_member              (JsonObject *object,
                                                         const gchar *member_name);

Checks whether object has a member named member_name.

object :

a JsonObject

member_name :

the name of a JSON object member

Returns :

TRUE if the JSON object has the requested member

json_object_get_member ()

JsonNode *          json_object_get_member              (JsonObject *object,
                                                         const gchar *member_name);

Retrieves the JsonNode containing the value of member_name inside a JsonObject.

object :

a JsonObject

member_name :

the name of the JSON object member to access

Returns :

a pointer to the node for the requested object member, or NULL. [transfer none][nullable]

json_object_dup_member ()

JsonNode *          json_object_dup_member              (JsonObject *object,
                                                         const gchar *member_name);

Retrieves a copy of the JsonNode containing the value of member_name inside a JsonObject

object :

a JsonObject

member_name :

the name of the JSON object member to access

Returns :

a copy of the node for the requested object member or NULL. Use json_node_unref() when done. [transfer full][nullable]

Since 0.6


json_object_get_members ()

GList *             json_object_get_members             (JsonObject *object);

Retrieves all the names of the members of a JsonObject. You can obtain the value for each member using json_object_get_member().

object :

a JsonObject

Returns :

a GList of member names, or NULL. The content of the list is owned by the JsonObject and should never be modified or freed. When you have finished using the returned list, use g_list_free() to free the resources it has allocated. [element-type utf8][transfer container][nullable]

json_object_get_values ()

GList *             json_object_get_values              (JsonObject *object);

Retrieves all the values of the members of a JsonObject.

object :

a JsonObject

Returns :

a GList of JsonNodes, or NULL. The content of the list is owned by the JsonObject and should never be modified or freed. When you have finished using the returned list, use g_list_free() to free the resources it has allocated. [element-type JsonNode][transfer container][nullable]

json_object_get_size ()

guint               json_object_get_size                (JsonObject *object);

Retrieves the number of members of a JsonObject.

object :

a JsonObject

Returns :

the number of members

json_object_remove_member ()

void                json_object_remove_member           (JsonObject *object,
                                                         const gchar *member_name);

Removes member_name from object, freeing its allocated resources.

object :

a JsonObject

member_name :

the name of the member to remove

JsonObjectForeach ()

void                (*JsonObjectForeach)                (JsonObject *object,
                                                         const gchar *member_name,
                                                         JsonNode *member_node,
                                                         gpointer user_data);

The function to be passed to json_object_foreach_member(). You should not add or remove members to and from object within this function. It is safe to change the value of member_node.

object :

the iterated JsonObject

member_name :

the name of the member

member_node :

a JsonNode containing the member_name value

user_data :

data passed to the function

Since 0.8


json_object_foreach_member ()

void                json_object_foreach_member          (JsonObject *object,
                                                         JsonObjectForeach func,
                                                         gpointer data);

Iterates over all members of object and calls func on each one of them.

It is safe to change the value of a JsonNode of the object from within the iterator func, but it is not safe to add or remove members from the object.

object :

a JsonObject

func :

the function to be called on each member. [scope call]

data :

data to be passed to the function. [closure]

Since 0.8


JsonObjectIter

typedef struct {
} JsonObjectIter;

An iterator used to iterate over the members of a JsonObject. This must be allocated on the stack and initialised using json_object_iter_init(). The order in which members are returned by the iterator is undefined. The iterator is invalidated if its JsonObject is modified during iteration.

All the fields in the JsonObjectIter structure are private and should never be accessed directly.

Since 1.2


json_object_iter_init ()

void                json_object_iter_init               (JsonObjectIter *iter,
                                                         JsonObject *object);

Initialise the iter and associate it with object.

1
2
3
4
5
6
7
8
9
JsonObjectIter iter;
const gchar *member_name;
JsonNode *member_node;

json_object_iter_init (&iter, some_object);
while (json_object_iter_next (&iter, &member_name, &member_node))
  {
    // Do something with @member_name and @member_node.
  }

iter :

an uninitialised JsonObjectIter

object :

the JsonObject to iterate over

Since 1.2


json_object_iter_next ()

gboolean            json_object_iter_next               (JsonObjectIter *iter,
                                                         const gchar **member_name,
                                                         JsonNode **member_node);

Advance iter and retrieve the next member in the object. If the end of the object is reached, FALSE is returned and member_name and member_node are set to invalid values. After that point, the iter is invalid.

The order in which members are returned by the iterator is undefined. The iterator is invalidated if its JsonObject is modified during iteration.

iter :

a JsonObjectIter

member_name :

return location for the member name, or NULL to ignore. [out callee-allocates][transfer none][optional]

member_node :

return location for the member value, or NULL to ignore. [out callee-allocates][transfer none][optional]

Returns :

TRUE if member_name and member_node are valid; FALSE if the end of the object has been reached

Since 1.2


json_object_set_array_member ()

void                json_object_set_array_member        (JsonObject *object,
                                                         const gchar *member_name,
                                                         JsonArray *value);

Convenience function for setting an array value of member_name inside object.

The object will take ownership of the passed JsonArray

See also: json_object_set_member()

object :

a JsonObject

member_name :

the name of the member

value :

the value of the member. [transfer full]

Since 0.8


json_object_get_array_member ()

JsonArray *         json_object_get_array_member        (JsonObject *object,
                                                         const gchar *member_name);

Convenience function that retrieves the array stored in member_name of object

See also: json_object_get_member()

object :

a JsonObject

member_name :

the name of the member

Returns :

the array inside the object's member. [transfer none]

Since 0.8


json_object_set_boolean_member ()

void                json_object_set_boolean_member      (JsonObject *object,
                                                         const gchar *member_name,
                                                         gboolean value);

Convenience function for setting a boolean value of member_name inside object.

See also: json_object_set_member()

object :

a JsonObject

member_name :

the name of the member

value :

the value of the member

Since 0.8


json_object_get_boolean_member ()

gboolean            json_object_get_boolean_member      (JsonObject *object,
                                                         const gchar *member_name);

Convenience function that retrieves the boolean value stored in member_name of object

See also: json_object_get_member()

object :

a JsonObject

member_name :

the name of the member

Returns :

the boolean value of the object's member

Since 0.8


json_object_set_double_member ()

void                json_object_set_double_member       (JsonObject *object,
                                                         const gchar *member_name,
                                                         gdouble value);

Convenience function for setting a floating point value of member_name inside object.

See also: json_object_set_member()

object :

a JsonObject

member_name :

the name of the member

value :

the value of the member

Since 0.8


json_object_get_double_member ()

gdouble             json_object_get_double_member       (JsonObject *object,
                                                         const gchar *member_name);

Convenience function that retrieves the floating point value stored in member_name of object

See also: json_object_get_member()

object :

a JsonObject

member_name :

the name of the member

Returns :

the floating point value of the object's member

Since 0.8


json_object_set_int_member ()

void                json_object_set_int_member          (JsonObject *object,
                                                         const gchar *member_name,
                                                         gint64 value);

Convenience function for setting an integer value of member_name inside object.

See also: json_object_set_member()

object :

a JsonObject

member_name :

the name of the member

value :

the value of the member

Since 0.8


json_object_get_int_member ()

gint64              json_object_get_int_member          (JsonObject *object,
                                                         const gchar *member_name);

Convenience function that retrieves the integer value stored in member_name of object

See also: json_object_get_member()

object :

a JsonObject

member_name :

the name of the member

Returns :

the integer value of the object's member

Since 0.8


json_object_set_null_member ()

void                json_object_set_null_member         (JsonObject *object,
                                                         const gchar *member_name);

Convenience function for setting a null value of member_name inside object.

See also: json_object_set_member()

object :

a JsonObject

member_name :

the name of the member

Since 0.8


json_object_get_null_member ()

gboolean            json_object_get_null_member         (JsonObject *object,
                                                         const gchar *member_name);

Convenience function that checks whether the value stored in member_name of object is null

See also: json_object_get_member()

object :

a JsonObject

member_name :

the name of the member

Returns :

TRUE if the value is null

Since 0.8


json_object_set_object_member ()

void                json_object_set_object_member       (JsonObject *object,
                                                         const gchar *member_name,
                                                         JsonObject *value);

Convenience function for setting an object value of member_name inside object.

The object will take ownership of the passed JsonObject

See also: json_object_set_member()

object :

a JsonObject

member_name :

the name of the member

value :

the value of the member. [transfer full]

Since 0.8


json_object_get_object_member ()

JsonObject *        json_object_get_object_member       (JsonObject *object,
                                                         const gchar *member_name);

Convenience function that retrieves the object stored in member_name of object. It is an error to specify a member_name which does not exist.

See also: json_object_get_member()

object :

a JsonObject

member_name :

the name of the member

Returns :

the object inside the object’s member, or NULL if the value for the member is `null`. [transfer none][nullable]

Since 0.8


json_object_set_string_member ()

void                json_object_set_string_member       (JsonObject *object,
                                                         const gchar *member_name,
                                                         const gchar *value);

Convenience function for setting a string value of member_name inside object.

See also: json_object_set_member()

object :

a JsonObject

member_name :

the name of the member

value :

the value of the member

Since 0.8


json_object_get_string_member ()

const gchar *       json_object_get_string_member       (JsonObject *object,
                                                         const gchar *member_name);

Convenience function that retrieves the string value stored in member_name of object

See also: json_object_get_member()

object :

a JsonObject

member_name :

the name of the member

Returns :

the string value of the object's member

Since 0.8