# 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, methods, 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_alloc_specific (MonoVTable *vtable); MonoObject* mono_object_new_fast (MonoVTable *vtable); 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); mono_object_isinst_mbyref 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); mono_object_hash MonoString* mono_object_to_string (MonoObject *obj, MonoObject **exc); MonoObject* mono_value_box (MonoDomain *domain, MonoClass *klass, gpointer value); void mono_value_copy (gpointer dest, gpointer src, MonoClass *klass); void mono_value_copy_array (MonoArray *dest, int dest_idx, gpointer src, int count); 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); mono_array_get uintptr_t mono_array_length (MonoArray *array); mono_array_set mono_array_setref mono_array_addr char* mono_array_addr_with_size (MonoArray *array, int size, uintptr_t idx); gint32 mono_array_element_size (MonoClass *ac); mono_field_from_token mono_field_get_flags 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); mono_field_get_object MonoReflectionProperty* mono_property_get_object_checked (MonoDomain *domain, MonoClass *klass, MonoProperty *property, MonoError *error); guint32 mono_property_get_flags (MonoProperty *prop); MonoMethod* mono_property_get_get_method (MonoProperty *prop); mono_property_get_name 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); mono_event_get_object 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); MonoMethod* mono_get_delegate_begin_invoke (MonoClass *klass); MonoMethod* mono_get_delegate_end_invoke (MonoClass *klass);

`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`
Syntax
MonoObject* mono_object_new (MonoDomain *domain, MonoClass *klass)

Parameters

klass | the class of the object that we want to create

Return value
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.
Description

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`
Syntax
MonoObject* mono_object_new_alloc_specific (MonoVTable *vtable)

Parameters

vtable | virtual table for the object.

Return value
the allocated object.
Description

This function allocates a new `MonoObject` with the type derived from the vtable information. If the class of this object has a finalizer, then the object will be tracked for finalization.

This method might raise an exception on errors. Use the `mono_object_new_fast_checked` method if you want to manually raise the exception.

`mono_object_new_fast`
Syntax
MonoObject* mono_object_new_fast (MonoVTable *vtable)

Parameters

vtable | virtual table for the object.

Return value
the allocated object.
Description

This function allocates a new `MonoObject` with the type derived from the vtable information. The returned object is not tracked for finalization. If your object implements a finalizer, you should use `mono_object_new_alloc_specific` instead.

This method might raise an exception on errors. Use the `mono_object_new_fast_checked` method if you want to manually raise the exception.

`mono_object_new_from_token`
Syntax
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

Return value
A newly created object whose definition is looked up using token in the image image
Description

`mono_object_new_specific`
Syntax
MonoObject* mono_object_new_specific (MonoVTable *vtable)

Parameters

vtable | the vtable of the object that we want to create

Return value
A newly created object with class and domain specified by vtable
Description

`mono_object_clone`
Syntax
MonoObject* mono_object_clone (MonoObject *obj)

Parameters

obj | the object to clone

Return value
A newly created object who is a shallow copy of obj
Description

`mono_object_get_class`
Syntax
MonoClass* mono_object_get_class (MonoObject *obj)

Parameters

obj | object to query

Return value
the MonoClass of the object.
Description

Use this function to obtain the `MonoClass*` for a given `MonoObject`.

`mono_object_get_domain`
Syntax
MonoDomain* mono_object_get_domain (MonoObject *obj)

Parameters

obj | object to query

Return value
the MonoDomain where the object is hosted
Description

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

Parameters

obj | object to operate on.
method | method

Description

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`
Syntax
mono_object_isinst_mbyref

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

Parameters

obj | an object
klass | a pointer to a class

Return value
obj if obj is derived from klass or `NULL` otherwise.
Description

`mono_object_unbox`
Syntax
gpointer mono_object_unbox (MonoObject *obj)

Parameters

obj | object to unbox

Return value
a pointer to the start of the valuetype boxed in this object.

This method will assert if the object passed is not a valuetype.
Description

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

Parameters

obj | an object
klass | a pointer to a class

Return value
obj if obj is derived from klass, returns `NULL` otherwise.
Description

`mono_object_get_size`
Syntax
guint mono_object_get_size (MonoObject* o)

Parameters

o | object to query

Return value
the size, in bytes, of o
Description

`mono_object_hash`
Syntax
mono_object_hash

`mono_object_to_string`
Syntax
MonoString* mono_object_to_string (MonoObject *obj, MonoObject **exc)

Parameters

obj | The object
exc | Any exception thrown by ToString (). May be `NULL`.

Return value
the result of calling ToString () on an object.
Description

## Value Types

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

Parameters

class | the class of the value
value | a pointer to the unboxed data

Return value
A newly created object which contains value.
Description

`mono_value_copy`
Syntax
void mono_value_copy (gpointer dest, gpointer src, MonoClass *klass)

Parameters

dest | destination pointer
src | source pointer
klass | a valuetype class

Description

Copy a valuetype from src to dest. This function must be used when klass contains references fields.
`mono_value_copy_array`
Syntax
void mono_value_copy_array (MonoArray *dest, int dest_idx, gpointer src, int count)

Parameters

dest | destination array
dest_idx | index in the dest array
src | source pointer
count | number of items

Description

Copy count valuetype items from src to the array dest at index dest_idx. This function must be used when klass contains references fields. Overlap is handled.

## 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`
Syntax
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

Description

This routine creates a new szarray with n elements of type eclass.
`mono_array_new_full`
Syntax
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`)

Description

This routine creates a new array objects with the given dimensions, lower bounds and type.
`mono_array_new_specific`
Syntax
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

Description

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`
Syntax
MonoClass* mono_array_class_get (MonoClass *eclass, guint32 rank)

Parameters

element_class | element class
rank | the dimension of the array class

Return value
A class object describing the array with element type element_type and dimension rank.
Description

`mono_array_clone`
Syntax
MonoArray* mono_array_clone (MonoArray *array)

Parameters

array | the array to clone

Return value
A newly created array who is a shallow copy of array
Description

### Using Arrays

Arrays are represented by the `MonoArray` data type and are instances of `MonoObject`. While you can use the `bounds` and `max_length` fields of the type, the actual storage (represented by `vector`) is not very useful. Instead you should use one of the accesor methods described below to fetch or set the values in the array.

When setting values in an array, you should use mono_array_set for setting elements in an array that contains value types, and mono_array_setref for arrays that contain reference types.

The mono_array_get, mono_array_set and mono_array_setref are C macros that wrap the underlying array access.
`mono_array_get`
Syntax
Type mono_array_get (MonoArray *array, Type element_type, uintptr_t index)

Parameters

array | array on which to operate on
element_type | C element type (example: MonoString *, int, MonoObject *)
index | index into the array

Return value
The element at the index position in the array.
Description

Use this macro to retrieve the index element of an array and extract the value assuming that the elements of the array match the provided type value.

This method can be used with both arrays holding value types and reference types. For reference types, the type parameter should be a `MonoObject*` or any subclass of it, like `MonoString*`.

This macro does not attempt to perform type checking or bounds checking.

`mono_array_length`
Syntax
uintptr_t mono_array_length (MonoArray *array)

Parameters

array | a MonoArray*

Description

Returns the total number of elements in the array. This works for both vectors and multidimensional arrays.
`mono_array_set`
Syntax
void mono_array_set(MonoArray *array, Type element_type, uintptr_t index, Value value)

Parameters

array | array to alter
element_type | A C type name, this macro will use the sizeof(type) to determine the element size
index | index into the array
value | value to set

Description

Value Type version: This sets the index's element of the array with elements of size sizeof(type) to the provided value.

This macro does not attempt to perform type checking or bounds checking.

Use this to set value types in a `MonoArray`.
`mono_array_setref`
Syntax
void mono_array_setref(MonoArray *array, uintptr_t index, MonoObject *object)

Parameters

array | array to alter
index | index into the array
value | value to set

Description

Reference Type version: This sets the index's element of the array with elements of size sizeof(type) to the provided value.

This macro does not attempt to perform type checking or bounds checking.

Use this to reference types in a `MonoArray`.
`mono_array_addr`
Syntax
mono_array_addr

`mono_array_addr_with_size`
Syntax
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

Description

Use this function to obtain the address for the idx item on the array containing elements of size size.

This method performs no bounds checking or type checking.

Returns the address of the idx element in the array.
`mono_array_element_size`
Syntax
gint32 mono_array_element_size (MonoClass *ac)

Parameters

ac | pointer to a `MonoArrayClass`

Return value
The size of single array element.
Description

## Fields

`mono_field_from_token`
Syntax
mono_field_from_token

`mono_field_get_flags`
Syntax
mono_field_get_flags

`mono_field_get_name`
Syntax
const char* mono_field_get_name (MonoClassField *field)

Parameters

field | the MonoClassField to act on

Return value
The name of the field.
Description

`mono_field_get_parent`
Syntax
MonoClass* mono_field_get_parent (MonoClassField *field)

Parameters

field | the MonoClassField to act on

Return value
MonoClass where the field was defined.
Description

`mono_field_get_type`
Syntax
MonoType* mono_field_get_type (MonoClassField *field)

Parameters

field | the MonoClassField to act on

Return value
MonoType of the field.
Description

`mono_field_get_value`
Syntax
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

Description

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`
Syntax
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.

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

Description

`mono_field_set_value`
Syntax
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

Description

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`
Syntax
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

Description

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`
Syntax
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

Description

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`
Syntax
mono_field_get_object

## Properties

`mono_property_get_object`
Syntax
MonoReflectionProperty* mono_property_get_object_checked (MonoDomain *domain, MonoClass *klass, MonoProperty *property, MonoError *error)

Parameters

domain | an app domain
klass | a type
property | a property
error | set on error

Description

Return an System.Reflection.MonoProperty object representing the property property in class klass. On error returns `NULL` and sets error.
`mono_property_get_flags`
Syntax
guint32 mono_property_get_flags (MonoProperty *prop)

Parameters

prop | the MonoProperty to act on.

Return value
The flags for the property.
Description

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`
Syntax
MonoMethod* mono_property_get_get_method (MonoProperty *prop)

Parameters

prop | the MonoProperty to act on.

Return value
The setter method of the property (A MonoMethod)
Description

`mono_property_get_name`
Syntax
mono_property_get_name

`mono_property_get_parent`
Syntax
MonoClass* mono_property_get_parent (MonoProperty *prop)

Parameters

prop | the MonoProperty to act on.

Return value
The MonoClass where the property was defined.
Description

`mono_property_get_set_method`
Syntax
MonoMethod* mono_property_get_set_method (MonoProperty *prop)

Parameters

prop | the MonoProperty to act on.

Return value
The setter method of the property (A MonoMethod)
Description

`mono_property_get_value`
Syntax
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

Return value
the value from invoking the get method on the property.
Description

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`
Syntax
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

Description

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`
Syntax
mono_event_get_object

`mono_event_get_add_method`
Syntax
MonoMethod* mono_event_get_add_method (MonoEvent *event)

Parameters

event | The MonoEvent to act on.

Return value
The add' method for the event (a MonoMethod).
Description

`mono_event_get_flags`
Syntax
guint32 mono_event_get_flags (MonoEvent *event)

Parameters

event | the MonoEvent to act on.

Return value
The flags for the event.
Description

The metadata flags for an event are encoded using the EVENT_* constants. See the tabledefs.h file for details.

`mono_event_get_name`
Syntax
const char* mono_event_get_name (MonoEvent *event)

Parameters

event | the MonoEvent to act on

Return value
The name of the event.
Description

`mono_event_get_parent`
Syntax
MonoClass* mono_event_get_parent (MonoEvent *event)

Parameters

event | the MonoEvent to act on.

Return value
The MonoClass where the event is defined.
Description

`mono_event_get_raise_method`
Syntax
MonoMethod* mono_event_get_raise_method (MonoEvent *event)

Parameters

event | The MonoEvent to act on.

Return value
The raise method for the event (a MonoMethod).
Description

`mono_event_get_remove_method`
Syntax
MonoMethod* mono_event_get_remove_method (MonoEvent *event)

Parameters

event | The MonoEvent to act on.

Return value
The remove method for the event (a MonoMethod).
Description

## Remote Fields

`mono_load_remote_field`
Syntax
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

Return value
an address pointing to the value of field.
Description

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`
Syntax
MonoObject* mono_load_remote_field_new (MonoObject *this_obj, MonoClass *klass, MonoClassField *field)

Parameters

this |
klass |
field |

Description

Missing documentation.
`mono_store_remote_field`
Syntax
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

Description

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.
`mono_store_remote_field_new`
Syntax
void mono_store_remote_field_new (MonoObject *this_obj, MonoClass *klass, MonoClassField *field, MonoObject *arg)

Parameters

this_obj |
klass |
field |
arg |

Description

Missing documentation

## Delegates

`mono_get_delegate_begin_invoke`
Syntax
MonoMethod* mono_get_delegate_begin_invoke (MonoClass *klass)

Parameters

klass | The delegate class

Return value
the MonoMethod for the "BeginInvoke" method in the delegate klass or `NULL` if klass is a broken delegate type
Description