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.
`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:
mono_object_new
| klass | the class of the object that we want to create |
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:
mono_object_new_alloc_specific
| vtable | virtual table for the object. |
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
| vtable | virtual table for the object. |
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
| image | Context where the type_token is hosted |
| token | a token of the type that we want to create |
mono_object_new_specific
| vtable | the vtable of the object that we want to create |
mono_object_clone
| obj | the object to clone |
mono_object_get_class
| obj | object to query |
Use this function to obtain the MonoClass* for a given MonoObject.
mono_object_get_domain
| obj | object to query |
mono_object_get_virtual_method
| obj | object to operate on. |
| method | method |
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
mono_object_isinst
| obj | an object |
| klass | a pointer to a class |
NULL otherwise.
mono_object_unbox
| obj | object to unbox |
This method will assert if the object passed is not a valuetype.
mono_object_castclass_mbyref
| obj | an object |
| klass | a pointer to a class |
NULL otherwise.
mono_object_get_size
| o | object to query |
mono_object_hash
mono_object_to_string
| obj | The object |
| exc | Any exception thrown by ToString (). May be NULL. |
mono_value_box
| class | the class of the value |
| value | a pointer to the unboxed data |
mono_value_copy
| dest | destination pointer |
| src | source pointer |
| klass | a valuetype class |
Copy a valuetype from src to dest. This function must be used when klass contains references fields.
mono_value_copy_array
| dest | destination array |
| dest_idx | index in the dest array |
| src | source pointer |
| count | number of items |
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.
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;
}
mono_array_new
| domain | domain where the object is created |
| eclass | element class |
| n | number of array elements |
This routine creates a new szarray with n elements of type eclass.
mono_array_new_full
| 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) |
This routine creates a new array objects with the given dimensions, lower bounds and type.
mono_array_new_specific
| vtable | a vtable in the appropriate domain for an initialized class |
| n | number of array elements |
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
| element_class | element class |
| rank | the dimension of the array class |
mono_array_clone
| array | the array to clone |
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
| array | array on which to operate on |
| element_type | C element type (example: MonoString *, int, MonoObject *) |
| index | index into the array |
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
| array | a MonoArray* |
Returns the total number of elements in the array. This works for both vectors and multidimensional arrays.
mono_array_set
| 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 |
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
| array | array to alter |
| index | index into the array |
| value | value to set |
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
mono_array_addr_with_size
| array | a MonoArray* |
| size | size of the array elements |
| idx | index into the array |
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
| ac | pointer to a MonoArrayClass |
mono_field_from_token
mono_field_get_flags
mono_field_get_name
| field | the MonoClassField to act on |
mono_field_get_parent
| field | the MonoClassField to act on |
mono_field_get_type
| field | the MonoClassField to act on |
mono_field_get_value
| obj | Object instance |
| field | MonoClassField describing the field to fetch information from |
| value | pointer to the location where the value will be stored |
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
| 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. |
mono_field_set_value
| obj | Instance object |
| field | MonoClassField describing the field to set |
| value | The value to be set |
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
| vt | vtable to the object |
| field | MonoClassField describing the field to fetch information from |
| value | where the value is returned |
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
| field | MonoClassField describing the field to set |
| value | The value to be set |
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_property_get_object
| domain | an app domain |
| klass | a type |
| property | a property |
| error | set on error |
Return an System.Reflection.MonoProperty object representing the property property
in class klass. On error returns NULL and sets error.
mono_property_get_flags
| prop | the MonoProperty to act on. |
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
| prop | the MonoProperty to act on. |
mono_property_get_name
mono_property_get_parent
| prop | the MonoProperty to act on. |
mono_property_get_set_method
| prop | the MonoProperty to act on. |
mono_property_get_value
| prop | MonoProperty to fetch |
| obj | instance object on which to act |
| params | parameters to pass to the propery |
| exc | optional exception |
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
| prop | MonoProperty to set |
| obj | instance object on which to act |
| params | parameters to pass to the propery |
| exc | optional exception |
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.
mono_event_get_object
mono_event_get_add_method
| event | The MonoEvent to act on. |
mono_event_get_flags
| event | the MonoEvent to act on. |
The metadata flags for an event are encoded using the EVENT_* constants. See the tabledefs.h file for details.
mono_event_get_name
| event | the MonoEvent to act on |
mono_event_get_parent
| event | the MonoEvent to act on. |
mono_event_get_raise_method
| event | The MonoEvent to act on. |
mono_event_get_remove_method
| event | The MonoEvent to act on. |
mono_load_remote_field
| this | pointer to an object |
| klass | klass of the object containing field |
| field | the field to load |
| res | a storage to store the result |
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
| this | |
| klass | |
| field |
Missing documentation.
mono_store_remote_field
| this_obj | pointer to an object |
| klass | klass of the object containing field |
| field | the field to load |
| val | the value/object to store |
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
| this_obj | |
| klass | |
| field | |
| arg |
Missing documentation
mono_get_delegate_begin_invoke
| klass | The delegate class |
NULL if klass is a broken delegate type