# Object API

The object API deals with all the operations shared by objects, value types, arrays.

The object API has methods for accessing fields, properties, events, delegates.

There are some advanced uses that are useful to document here dealing with remote fields.

## Synopsis

#include <metadata/object.h> typedef struct MonoVTable MonoVTable; typedef struct _MonoThreadsSync MonoThreadsSync; typedef struct { MonoVTable *vtable; MonoThreadsSync *synchronisation; } MonoObject; typedef struct { guint32 length; guint32 lower_bound; } MonoArrayBounds; typedef struct { MonoObject obj; /* bounds is NULL for szarrays */ MonoArrayBounds *bounds; /* total number of elements of the array */ guint32 max_length; /* we use double to ensure proper alignment on platforms that need it */ double vector [MONO_ZERO_LEN_ARRAY]; } MonoArray; MonoObject* mono_object_new (MonoDomain *domain, MonoClass *klass); MonoObject* mono_object_new_from_token (MonoDomain *domain, MonoImage *image, guint32 token); MonoObject* mono_object_new_specific (MonoVTable *vtable); MonoObject* mono_object_clone (MonoObject *obj); MonoClass* mono_object_get_class (MonoObject *obj); MonoDomain* mono_object_get_domain (MonoObject *obj); MonoMethod* mono_object_get_virtual_method (MonoObject *obj, MonoMethod *method); MonoObject* mono_object_isinst (MonoObject *obj, MonoClass *klass); gpointer mono_object_unbox (MonoObject *obj); MonoObject* mono_object_castclass_mbyref (MonoObject *obj, MonoClass *klass); guint mono_object_get_size (MonoObject* o); MonoObject* mono_value_box (MonoDomain *domain, MonoClass *klass, gpointer value); MonoArray* mono_array_new (MonoDomain *domain, MonoClass *eclass, uintptr_t n); MonoArray* mono_array_new_full (MonoDomain *domain, MonoClass *array_class, uintptr_t *lengths, intptr_t *lower_bounds); MonoArray* mono_array_new_specific (MonoVTable *vtable, uintptr_t n); MonoClass* mono_array_class_get (MonoClass *eclass, guint32 rank); MonoArray* mono_array_clone (MonoArray *array); uintptr_t mono_array_length (MonoArray *array); char* mono_array_addr_with_size (MonoArray *array, int size, uintptr_t idx); gint32 mono_array_element_size (MonoClass *ac); const char* mono_field_get_name (MonoClassField *field); MonoClass* mono_field_get_parent (MonoClassField *field); MonoType* mono_field_get_type (MonoClassField *field); void mono_field_get_value (MonoObject *obj, MonoClassField *field, void *value); MonoObject* mono_field_get_value_object (MonoDomain *domain, MonoClassField *field, MonoObject *obj); void mono_field_set_value (MonoObject *obj, MonoClassField *field, void *value); void mono_field_static_get_value (MonoVTable *vt, MonoClassField *field, void *value); void mono_field_static_set_value (MonoVTable *vt, MonoClassField *field, void *value); guint32 mono_property_get_flags (MonoProperty *prop); MonoMethod* mono_property_get_get_method (MonoProperty *prop); MonoClass* mono_property_get_parent (MonoProperty *prop); MonoMethod* mono_property_get_set_method (MonoProperty *prop); MonoObject* mono_property_get_value (MonoProperty *prop, void *obj, void **params, MonoObject **exc); void mono_property_set_value (MonoProperty *prop, void *obj, void **params, MonoObject **exc); MonoMethod* mono_event_get_add_method (MonoEvent *event); guint32 mono_event_get_flags (MonoEvent *event); const char* mono_event_get_name (MonoEvent *event); MonoClass* mono_event_get_parent (MonoEvent *event); MonoMethod* mono_event_get_raise_method (MonoEvent *event); MonoMethod* mono_event_get_remove_method (MonoEvent *event); gpointer mono_load_remote_field (MonoObject *this_obj, MonoClass *klass, MonoClassField *field, gpointer *res); MonoObject* mono_load_remote_field_new (MonoObject *this_obj, MonoClass *klass, MonoClassField *field); void mono_store_remote_field (MonoObject *this_obj, MonoClass *klass, MonoClassField *field, gpointer val); void mono_store_remote_field_new (MonoObject *this_obj, MonoClass *klass, MonoClassField *field, MonoObject *arg);

MonoObject is the base definition for all managed objects in the Mono runtime, it represents the System.Object managed type.

All objects that derive from System.Object do have this base definition. Derived objects are declared following the pattern where the parent class is the first field of a structure definition, for example:
typedef struct { MonoObject parent; int my_new_field; } MyNewObject

## Core Object Methods

mono_object_new
MonoObject* mono_object_new (MonoDomain *domain, MonoClass *klass)

Parameters

> klass:
>   the class of the object that we want to create

Returns

> a newly created object whose definition is looked up using klass. This will not invoke any constructors, so the consumer of this routine has to invoke any constructors on its own to initialize the object.

> It returns NULL on failure.

For example, if you wanted to create an object of type System.Version, you would use a piece of code like this:
MonoClass *version_class; MonoObject *result; /* Get the class from mscorlib */ version_class = mono_class_from_name (mono_get_corlib (), "System", "Version"); /* Create an object of that class */ result = mono_object_new (mono_domain_get (), version_class);
mono_object_new_alloc_specific
Prototype: mono_object_new_alloc_specific

mono_object_new_fast
Prototype: mono_object_new_fast

mono_object_new_from_token
MonoObject* mono_object_new_from_token (MonoDomain *domain, MonoImage *image, guint32 token)

Parameters

> image:
>   Context where the type_token is hosted
> token:
>   a token of the type that we want to create

Returns

> A newly created object whose definition is looked up using token in the image image

mono_object_new_specific
MonoObject* mono_object_new_specific (MonoVTable *vtable)

Parameters

> vtable:
>   the vtable of the object that we want to create

Returns

> A newly created object with class and domain specified by vtable

mono_object_clone
MonoObject* mono_object_clone (MonoObject *obj)

Parameters

> obj:
>   the object to clone

Returns

> A newly created object who is a shallow copy of obj

mono_object_get_class
MonoClass* mono_object_get_class (MonoObject *obj)

Parameters

> obj:
>   object to query

Returns

> the MonOClass of the object.

Remarks

mono_object_get_domain
MonoDomain* mono_object_get_domain (MonoObject *obj)

Parameters

> obj:
>   object to query

Returns

> the MonoDomain where the object is hosted

Remarks

mono_object_get_virtual_method
MonoMethod* mono_object_get_virtual_method (MonoObject *obj, MonoMethod *method)

Parameters

> obj:
>   object to operate on.
> method:
>   method

Remarks

Retrieves the MonoMethod that would be called on obj if obj is passed as the instance of a callvirt of method.
mono_object_isinst_mbyref
Prototype: mono_object_isinst_mbyref

mono_object_isinst
MonoObject* mono_object_isinst (MonoObject *obj, MonoClass *klass)

Parameters

> obj:
>   an object
> klass:
>   a pointer to a class

Returns

> obj if obj is derived from klass

mono_object_unbox
gpointer mono_object_unbox (MonoObject *obj)

Parameters

> obj:
>   object to unbox

Returns

> a pointer to the start of the valuetype boxed in this object. This method will assert if the object passed is not a valuetype.

Remarks

mono_object_castclass_mbyref
MonoObject* mono_object_castclass_mbyref (MonoObject *obj, MonoClass *klass)

Parameters

> obj:
>   an object
> klass:
>   a pointer to a class

Returns

> obj if obj is derived from klass, throws an exception otherwise

mono_object_get_size
guint mono_object_get_size (MonoObject* o)

Parameters

> o:
>   object to query

Returns

> the size, in bytes, of o

Remarks

## Value Types

mono_value_box
MonoObject* mono_value_box (MonoDomain *domain, MonoClass *klass, gpointer value)

Parameters

> class:
>   the class of the value
> value:
>   a pointer to the unboxed data

Returns

> A newly created object which contains value.

mono_value_copy
Prototype: mono_value_copy

mono_value_copy_array
Prototype: mono_value_copy_array

## Array Methods

Use the `mono_array_new_*` methods to create arrays of a given type.

For example, the following code creates an array with two elements of type `System.Byte`, and sets the values 0xca and 0xfe on it:

    	MonoArray *CreateByteArray (MonoDomain *domain)
    	{
    	    MonoArray *data;

    	    data = mono_array_new (domain, mono_get_byte_class (), 2);
    	    mono_array_set (data, guint8, 0, 0xca);
    	    mono_array_set (data, guint8, 0, 0xfe);

    	    return data;
    	}

### Creating Arrays

mono_array_new
MonoArray* mono_array_new (MonoDomain *domain, MonoClass *eclass, uintptr_t n)

Parameters

> domain:
>   domain where the object is created
> eclass:
>   element class
> n:
>   number of array elements

Remarks

This routine creates a new szarray with n elements of type eclass.
mono_array_new_full
MonoArray* mono_array_new_full (MonoDomain *domain, MonoClass *array_class, uintptr_t *lengths, intptr_t *lower_bounds)

Parameters

> domain:
>   domain where the object is created
> array_class:
>   array class
> lengths:
>   lengths for each dimension in the array
> lower_bounds:
>   lower bounds for each dimension in the array (may be NULL)

Remarks

This routine creates a new array objects with the given dimensions, lower bounds and type.
mono_array_new_specific
MonoArray* mono_array_new_specific (MonoVTable *vtable, uintptr_t n)

Parameters

> vtable:
>   a vtable in the appropriate domain for an initialized class
> n:
>   number of array elements

Remarks

This routine is a fast alternative to mono_array_new() for code which can be sure about the domain it operates in.
mono_array_class_get
MonoClass* mono_array_class_get (MonoClass *eclass, guint32 rank)

Parameters

> element_class:
>   element class
> rank:
>   the dimension of the array class

Returns

> a class object describing the array with element type element_type and dimension rank.

mono_array_clone
MonoArray* mono_array_clone (MonoArray *array)

Parameters

> array:
>   the array to clone

Returns

> A newly created array who is a shallow copy of array

### Using Arrays

mono_array_set
Prototype: mono_array_set

mono_array_setref
Prototype: mono_array_setref

mono_array_length
uintptr_t mono_array_length (MonoArray *array)

Parameters

> array:
>   a MonoArray*

Remarks

Returns the total number of elements in the array. This works for both vectors and multidimensional arrays.
mono_array_addr
Prototype: mono_array_addr

mono_array_addr_with_size
char* mono_array_addr_with_size (MonoArray *array, int size, uintptr_t idx)

Parameters

> array:
>   a MonoArray*
> size:
>   size of the array elements
> idx:
>   index into the array

Remarks

Returns the address of the idx element in the array.
mono_array_get
Prototype: mono_array_get

mono_array_element_size
gint32 mono_array_element_size (MonoClass *ac)

Parameters

> ac:
>   pointer to a #MonoArrayClass

Returns

> the size of single array element.

## Fields

mono_field_from_token
Prototype: mono_field_from_token

mono_field_get_flags
Prototype: mono_field_get_flags

mono_field_get_name
const char* mono_field_get_name (MonoClassField *field)

Parameters

> field:
>   the MonoClassField to act on

Returns

> the name of the field.

mono_field_get_parent
MonoClass* mono_field_get_parent (MonoClassField *field)

Parameters

> field:
>   the MonoClassField to act on

Returns

> MonoClass where the field was defined.

mono_field_get_type
MonoType* mono_field_get_type (MonoClassField *field)

Parameters

> field:
>   the MonoClassField to act on

Returns

> MonoType of the field.

mono_field_get_value
void mono_field_get_value (MonoObject *obj, MonoClassField *field, void *value)

Parameters

> obj:
>   Object instance
> field:
>   MonoClassField describing the field to fetch information from
> value:
>   pointer to the location where the value will be stored

Remarks

Use this routine to get the value of the field field in the object passed. The pointer provided by value must be of the field type, for reference types this is a MonoObject*, for value types its the actual pointer to the value type. For example: int i; mono_field_get_value (obj, int_field, &i);
mono_field_get_value_object
MonoObject* mono_field_get_value_object (MonoDomain *domain, MonoClassField *field, MonoObject *obj)

Parameters

> domain:
>   domain where the object will be created (if boxing)
> field:
>   MonoClassField describing the field to fetch information from
> obj:
>   The object instance for the field.

Returns

> a new MonoObject with the value from the given field. If the field represents a value type, the value is boxed.

mono_field_set_value
void mono_field_set_value (MonoObject *obj, MonoClassField *field, void *value)

Parameters

> obj:
>   Instance object
> field:
>   MonoClassField describing the field to set
> value:
>   The value to be set

Remarks

Sets the value of the field described by field in the object instance obj to the value passed in value. This method should only be used for instance fields. For static fields, use mono_field_static_set_value. The value must be on the native format of the field type.
mono_field_static_get_value
void mono_field_static_get_value (MonoVTable *vt, MonoClassField *field, void *value)

Parameters

> vt:
>   vtable to the object
> field:
>   MonoClassField describing the field to fetch information from
> value:
>   where the value is returned

Remarks

Use this routine to get the value of the static field field value. The pointer provided by value must be of the field type, for reference types this is a MonoObject*, for value types its the actual pointer to the value type. For example: int i; mono_field_static_get_value (vt, int_field, &i);
mono_field_static_set_value
void mono_field_static_set_value (MonoVTable *vt, MonoClassField *field, void *value)

Parameters

> field:
>   MonoClassField describing the field to set
> value:
>   The value to be set

Remarks

Sets the value of the static field described by field to the value passed in value. The value must be on the native format of the field type.
mono_field_get_object
Prototype: mono_field_get_object

## Properties

mono_property_get_object
Prototype: mono_property_get_object

mono_property_get_flags
guint32 mono_property_get_flags (MonoProperty *prop)

Parameters

> prop:
>   the MonoProperty to act on.

Returns

> the flags for the property.

Remarks

The metadata flags for a property are encoded using the PROPERTY_ATTRIBUTE_* constants. See the tabledefs.h file for details.
mono_property_get_get_method
MonoMethod* mono_property_get_get_method (MonoProperty *prop)

Parameters

> prop:
>   the MonoProperty to act on.

Returns

> the setter method of the property (A MonoMethod)

mono_property_get_name
Prototype: mono_property_get_name

mono_property_get_parent
MonoClass* mono_property_get_parent (MonoProperty *prop)

Parameters

> prop:
>   the MonoProperty to act on.

Returns

> the MonoClass where the property was defined.

mono_property_get_set_method
MonoMethod* mono_property_get_set_method (MonoProperty *prop)

Parameters

> prop:
>   the MonoProperty to act on.

Returns

> the setter method of the property (A MonoMethod)

mono_property_get_value
MonoObject* mono_property_get_value (MonoProperty *prop, void *obj, void **params, MonoObject **exc)

Parameters

> prop:
>   MonoProperty to fetch
> obj:
>   instance object on which to act
> params:
>   parameters to pass to the propery
> exc:
>   optional exception

Returns

> the value from invoking the get method on the property.

Remarks

Invokes the property's get method with the given arguments on the object instance obj (or NULL for static properties).

You can pass NULL as the exc argument if you don't want to catch exceptions, otherwise, *exc will be set to the exception thrown, if any. if an exception is thrown, you can't use the MonoObject* result from the function.
mono_property_set_value
void mono_property_set_value (MonoProperty *prop, void *obj, void **params, MonoObject **exc)

Parameters

> prop:
>   MonoProperty to set
> obj:
>   instance object on which to act
> params:
>   parameters to pass to the propery
> exc:
>   optional exception

Remarks

Invokes the property's set method with the given arguments on the object instance obj (or NULL for static properties).

You can pass NULL as the exc argument if you don't want to catch exceptions, otherwise, *exc will be set to the exception thrown, if any. if an exception is thrown, you can't use the MonoObject* result from the function.

## Events

mono_event_get_object
Prototype: mono_event_get_object

mono_event_get_add_method
MonoMethod* mono_event_get_add_method (MonoEvent *event)

Parameters

> event:
>   The MonoEvent to act on.

Returns

> the add' method for the event (a MonoMethod).

mono_event_get_flags
guint32 mono_event_get_flags (MonoEvent *event)

Parameters

> event:
>   the MonoEvent to act on.

Returns

> the flags for the event.

Remarks

The metadata flags for an event are encoded using the EVENT_* constants. See the tabledefs.h file for details.
mono_event_get_name
const char* mono_event_get_name (MonoEvent *event)

Parameters

> event:
>   the MonoEvent to act on

Returns

> the name of the event.

mono_event_get_parent
MonoClass* mono_event_get_parent (MonoEvent *event)

Parameters

> event:
>   the MonoEvent to act on.

Returns

> the MonoClass where the event is defined.

mono_event_get_raise_method
MonoMethod* mono_event_get_raise_method (MonoEvent *event)

Parameters

> event:
>   The MonoEvent to act on.

Returns

> the raise method for the event (a MonoMethod).

mono_event_get_remove_method
MonoMethod* mono_event_get_remove_method (MonoEvent *event)

Parameters

> event:
>   The MonoEvent to act on.

Returns

> the remove method for the event (a MonoMethod).

## Remote Fields

mono_load_remote_field
gpointer mono_load_remote_field (MonoObject *this_obj, MonoClass *klass, MonoClassField *field, gpointer *res)

Parameters

> this:
>   pointer to an object
> klass:
>   klass of the object containing field
> field:
>   the field to load
> res:
>   a storage to store the result

Returns

> an address pointing to the value of field.

Remarks

This method is called by the runtime on attempts to load fields of transparent proxy objects. this points to such TP, klass is the class of the object containing field. res is a storage location which can be used to store the result.
mono_load_remote_field_new
MonoObject* mono_load_remote_field_new (MonoObject *this_obj, MonoClass *klass, MonoClassField *field)

Parameters

> this:
> klass:
> field:

Remarks

Missing documentation.
mono_store_remote_field
void mono_store_remote_field (MonoObject *this_obj, MonoClass *klass, MonoClassField *field, gpointer val)

Parameters

> this_obj:
>   pointer to an object
> klass:
>   klass of the object containing field
> field:
>   the field to load
> val:
>   the value/object to store

Remarks

This method is called by the runtime on attempts to store fields of transparent proxy objects. this_obj points to such TP, klass is the class of the object containing field. val is the new value to store in field.