JSON Object

JSON Object — a JSON object representation

Functions

Types and Values

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().

Functions

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.

Parameters

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.

Parameters

object

a JsonObject

 

json_object_add_member ()

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

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 .

Parameters

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 .

Parameters

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 .

Parameters

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.

Parameters

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]


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

Parameters

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_free() when done.

[transfer full]

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().

Parameters

object

a JsonObject

 

Returns

a GList of member names. 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]


json_object_get_values ()

GList *
json_object_get_values (JsonObject *object);

Retrieves all the values of the members of a JsonObject.

Parameters

object

a JsonObject

 

Returns

a GList of JsonNodes. 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]


json_object_get_size ()

guint
json_object_get_size (JsonObject *object);

Retrieves the number of members of a JsonObject.

Parameters

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.

Parameters

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 .

Parameters

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 .

Parameters

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


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()

Parameters

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()

Parameters

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()

Parameters

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()

Parameters

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()

Parameters

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()

Parameters

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()

Parameters

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()

Parameters

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()

Parameters

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()

Parameters

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()

Parameters

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

See also: json_object_get_member()

Parameters

object

a JsonObject

 

member_name

the name of the member

 

Returns

the object inside the object's member.

[transfer none]

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()

Parameters

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()

Parameters

object

a JsonObject

 

member_name

the name of the member

 

Returns

the string value of the object's member

Since 0.8

Types and Values

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