This is the base class for all Variant types. More...

#include <glibmm/variant.h>

Inheritance diagram for Glib::VariantBase:

List of all members.

Public Member Functions
	VariantBase ()
	VariantBase (GVariant* castitem, bool make_a_copy=false)
	VariantBase (const VariantBase& src)
VariantBase&	operator= (const VariantBase& src)
	~VariantBase ()
GVariant*	gobj ()
const GVariant*	gobj () const
GVariant*	gobj_copy () const
	Provides access to the underlying C instance. The caller is responsible for freeing it. Use when directly setting fields in structs.
void	init (const GVariant* cobject, bool take_a_reference=false)
	Replace the underlying GVariant.
VariantType	get_type () const
	Determines the type of value.
std::string	get_type_string () const
	Returns the type string of value.
bool	is_floating () const
	Checks whether value has a floating reference count.
bool	is_of_type (const VariantType&type) const
	Checks if a value has a type matching the provided type.
bool	is_container () const
	Checks if value is a container.
GVariantClass	classify () const
	Classifies value according to its top-level type.
gsize	get_size () const
	Determines the number of bytes that would be required to store value with g_variant_store().
gconstpointer	get_data ()
	Returns a pointer to the serialised form of a Variant instance.
void	store (gpointer data) const
	Stores the serialised form of value at data.
Glib::ustring	print (bool type_annotate=false) const
	Pretty-prints value in the format understood by g_variant_parse().
guint	hash () const
	Generates a hash value for a Variant instance.
bool	equal (const VariantBase& other) const
	Checks if one and two have the same type and value.
void	get_normal_form (VariantBase& result) const
	Gets a VariantBase instance that has the same value as this variant and is trusted to be in normal form.
bool	is_normal_form () const
	Checks if value is in normal form.
void	byteswap (VariantBase& result) const
	Performs a byteswapping operation on the contents of this variant.
Static Public Member Functions
template<class V_CastTo >
static V_CastTo	cast_dynamic (const VariantBase& v) throw (std::bad_cast)
	Cast to a specific variant type.
Protected Attributes
GVariant*	gobject_
Related Functions
(Note that these are not member functions.)
Glib::VariantBase	wrap (GVariant* object, bool take_copy=false)
	A Glib::wrap() method for this object.

---

Detailed Description

This is the base class for all Variant types.

If the actual type is known at compile-time then you should use a specific Variant<>, such as Variant<int>. Otherwise, you may use get_type(), is_of_type(), or cast_dynamic().

Since glibmm 2.28:

---

Constructor & Destructor Documentation

Glib::VariantBase::VariantBase

(

)

Glib::VariantBase::VariantBase	(	GVariant *	castitem,
		bool	make_a_copy = false
	)		[explicit]

Glib::VariantBase::VariantBase

(

const VariantBase&

src

)

Glib::VariantBase::~VariantBase

(

)

---

Member Function Documentation

void Glib::VariantBase::byteswap

(

VariantBase&

result

)

const

Performs a byteswapping operation on the contents of this variant.

The result is that all multi-byte numeric data contained in the variant is byteswapped. That includes 16, 32, and 64bit signed and unsigned integers as well as file handles and double precision floating point values.

This function is an identity mapping on any value that does not contain multi-byte numeric data. That include strings, booleans, bytes and containers containing only these things (recursively).

The returned value is always in normal form and is marked as trusted.

Parameters:

result

A location in which to store the byteswapped form of this variant.

Since glibmm 2.24:

VariantContainerBase Glib::VariantBase::cast_dynamic< VariantContainerBase >

(

const VariantBase&

v

)

throw (std::bad_cast) [static]

Cast to a specific variant type.

For instance:

 Variant<std::string> derived = VariantBase::cast_dynamic< Variant<std::string> >(base);

Parameters:

v	The variant to cast to a specific type.

Returns:

The variant as a specific type.

Exceptions:

std::bad_cast

if the Variant was not of the expected type.

GVariantClass Glib::VariantBase::classify

(

)

const

Classifies value according to its top-level type.

Since glibmm 2.24:

Returns:

The VariantClass of value.

bool Glib::VariantBase::equal

(

const VariantBase&

other

)

const

Checks if one and two have the same type and value.

The types of one and two are #gconstpointer only to allow use of this function with HashTable. They must each be a Variant.

Since glibmm 2.24:

Parameters:

one	A Variant instance.
two	A Variant instance.

Returns:

true if one and two are equal.

gconstpointer Glib::VariantBase::get_data

(

)

Returns a pointer to the serialised form of a Variant instance.

The returned data may not be in fully-normalised form if read from an untrusted source. The returned data must not be freed; it remains valid for as long as value exists.

If value is a fixed-sized value that was deserialised from a corrupted serialised container then 0 may be returned. In this case, the proper thing to do is typically to use the appropriate number of nul bytes in place of value. If value is not fixed-sized then 0 is never returned.

In the case that value is already in serialised form, this function is O(1). If the value is not already in serialised form, serialisation occurs implicitly and is approximately O(n) in the size of the result.

Since glibmm 2.24:

Returns:

The serialised form of value, or 0.

void Glib::VariantBase::get_normal_form

(

VariantBase&

result

)

const

Gets a VariantBase instance that has the same value as this variant and is trusted to be in normal form.

If this variant is already trusted to be in normal form then a new reference to the variant is returned.

If this variant is not already trusted, then it is scanned to check if it is in normal form. If it is found to be in normal form then it is marked as trusted and a new reference to it is returned.

If this variant is found not to be in normal form then a new trusted VariantBase is created with the same value as this variant.

It makes sense to call this function if you've received variant data from untrusted sources and you want to ensure your serialised output is definitely in normal form.

Parameters:

result

A location in which to store the trusted VariantBase.

Since glibmm 2.24:

gsize Glib::VariantBase::get_size

(

)

const

Determines the number of bytes that would be required to store value with g_variant_store().

If value has a fixed-sized type then this function always returned that fixed size.

In the case that value is already in serialised form or the size has already been calculated (ie: this function has been called before) then this function is O(1). Otherwise, the size is calculated, an operation which is approximately O(n) in the number of values involved.

Since glibmm 2.24:

Returns:

The serialised size of value.

VariantType Glib::VariantBase::get_type

(

)

const

Determines the type of value.

The return value is valid for the lifetime of value and must not be freed.

Since glibmm 2.24:

Returns:

A VariantType.

std::string Glib::VariantBase::get_type_string

(

)

const

Returns the type string of value.

Unlike the result of calling g_variant_type_peek_string(), this string is nul-terminated. This string belongs to Variant and must not be freed.

Since glibmm 2.24:

Returns:

The type string for the type of value.

const GVariant* Glib::VariantBase::gobj

(

)

const [inline]

GVariant* Glib::VariantBase::gobj

(

)

[inline]

GVariant* Glib::VariantBase::gobj_copy

(

)

const

Provides access to the underlying C instance. The caller is responsible for freeing it. Use when directly setting fields in structs.

guint Glib::VariantBase::hash

(

)

const

Generates a hash value for a Variant instance.

The output of this function is guaranteed to be the same for a given value only per-process. It may change between different processor architectures or even different versions of GLib. Do not use this function as a basis for building protocols or file formats.

The type of value is #gconstpointer only to allow use of this function with HashTable. value must be a Variant.

Since glibmm 2.24:

Parameters:

value

A basic Variant value as a #gconstpointer.

Returns:

A hash value corresponding to value.

void Glib::VariantBase::init	(	const GVariant *	cobject,
		bool	take_a_reference = false
	)

Replace the underlying GVariant.

This is for use by methods that take a VariantBase& as an output parameter.

Parameters:

cobject	The GVariant* obtained from a C function.
take_a_reference	Whether this method should take a reference, for instance if the C function has not given one.

bool Glib::VariantBase::is_container

(

)

const

Checks if value is a container.

Returns:

true if value is a container.

bool Glib::VariantBase::is_floating

(

)

const

Checks whether value has a floating reference count.

This function should only ever be used to assert that a given variant is or is not floating, or for debug purposes. To acquire a reference to a variant that might be floating, always use g_variant_ref_sink().

See g_variant_ref_sink() for more information about floating reference counts.

Since glibmm 2.26:

Returns:

Whether value is floating.

bool Glib::VariantBase::is_normal_form

(

)

const

Checks if value is in normal form.

The main reason to do this is to detect if a given chunk of serialised data is in normal form: load the data into a Variant using g_variant_new_from_data() and then use this function to check.

If value is found to be in normal form then it will be marked as being trusted. If the value was already marked as being trusted then this function will immediately return true.

Since glibmm 2.24:

Returns:

true if value is in normal form.

bool Glib::VariantBase::is_of_type

(

const VariantType&

type

)

const

Checks if a value has a type matching the provided type.

Since glibmm 2.24:

Parameters:

type	A VariantType.

Returns:

true if the type of value matches type.

VariantBase& Glib::VariantBase::operator=

(

const VariantBase&

src

)

Glib::ustring Glib::VariantBase::print

(

bool

type_annotate = false

)

const

Pretty-prints value in the format understood by g_variant_parse().

The format is described here.

If type_annotate is true, then type information is included in the output.

Parameters:

type_annotate

true if type information should be included in the output.

Returns:

A newly-allocated string holding the result.

void Glib::VariantBase::store

(

gpointer

data

)

const

Stores the serialised form of value at data.

data should be large enough. See g_variant_get_size().

The stored data is in machine native byte order but may not be in fully-normalised form if read from an untrusted source. See g_variant_get_normal_form() for a solution.

This function is approximately O(n) in the size of data.

Since glibmm 2.24:

Parameters:

data	The location to store the serialised data at.

---

Friends And Related Function Documentation

Glib::VariantBase wrap	(	GVariant *	object,
		bool	take_copy = false
	)		[related]

A Glib::wrap() method for this object.

Parameters:

object	The C instance.
take_copy	False if the result should take ownership of the C instance. True if it should take a new copy or ref.

Returns:

A C++ instance that wraps this C instance.

---

Member Data Documentation

GVariant* Glib::VariantBase::gobject_ [protected]