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
`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.
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
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
mono_object_clone
Syntax
MonoObject*
mono_object_clone (MonoObject *obj)
Parameters
Return value
A newly created object who is a shallow copy of obj
mono_object_get_class
Syntax
MonoClass*
mono_object_get_class (MonoObject *obj)
Parameters
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
Return value
the MonoDomain where the object is hosted
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
MonoObject*
mono_object_isinst_mbyref (MonoObject *obj_raw, MonoClass *klass)
mono_object_isinst
Syntax
MonoObject*
mono_object_isinst (MonoObject *obj_raw, MonoClass *klass)
Parameters
| obj | an object |
| klass | a pointer to a class |
Return value
obj if obj is derived from klass or NULL otherwise.
mono_object_unbox
Syntax
void*
mono_object_unbox (MonoObject *obj)
Parameters
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.
mono_object_castclass_mbyref
Syntax
MonoObject*
mono_object_castclass_mbyref (MonoObject *obj_raw, MonoClass *klass)
Parameters
| obj | an object |
| klass | a pointer to a class |
Return value
obj if obj is derived from klass, returns NULL otherwise.
mono_object_get_size
Syntax
unsigned
mono_object_get_size (MonoObject *o)
Parameters
Return value
the size, in bytes, of o
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.
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.
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 reference fields.
mono_value_copy_array
Syntax
void
mono_value_copy_array (MonoArray *dest, int dest_idx, void* 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 object 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.
mono_array_clone
Syntax
MonoArray*
mono_array_clone (MonoArray *array)
Parameters
Return value
A newly created array who is a shallow copy of array
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_internal (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
Return value
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 |
| version | This sets the index's element of the array |
Description
with elements of size sizeof(type) to the provided
value.
This macro does not attempt to perform type checking or bounds checking
and it doesn't execute any write barriers.
Use this to set value types in a
MonoArray. This shouldn't be used if
the copied value types contain references. Use
mono_gc_wbarrier_value_copy
instead when also copying references.
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_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 |
Return value
the address of the idx element in 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.
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.
LOCKING: Acquires the loader lock.
Description
Fields
mono_field_from_token
Deprecated: use the _checked variant
Syntax
MonoClassField*
mono_field_from_token (MonoImage *image, guint32 token, MonoClass **retklass, MonoGenericContext *context)
Parameters
| Notes | runtime code MUST not use this function |
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.
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.
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 in 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 in the native format of the field type.
mono_field_get_object
Syntax
MonoReflectionField*
mono_field_get_object (MonoDomain *domain, MonoClass *klass, MonoClassField *field)
Parameters
| domain | an app domain |
| klass | a type |
| field | a field |
Return value
A System.Reflection.MonoField object representing the field field
in class klass.
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 |
Return value
a 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 getter method of the property (A MonoMethod)
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.
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.
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
MonoReflectionEvent*
mono_event_get_object (MonoDomain *domain, MonoClass *klass, MonoEvent *event)
Parameters
| domain | an app domain |
| klass | a type |
| event | a event |
Return value
A System.Reflection.MonoEvent object representing the event event
in class klass.
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.
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.
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.
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.
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.
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
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
Description
Missing documentation
Delegates
mono_get_delegate_begin_invoke
Syntax
MonoMethod*
mono_get_delegate_begin_invoke (MonoClass *klass)
Parameters
Return value
the MonoMethod for the BeginInvoke method in the delegate class or NULL if klass is a broken delegate type