mono-api-object.html
   
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
	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 hostedtoken: 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 objectklass: 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 objectklass: a pointer to a class 
Returns
	  obj if obj is derived from klass, throws an exception otherwise
  
 
    mono_object_is_alive
    Prototype: mono_object_is_alive
  
 
    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 *class, gpointer value)
Parameters
class: the class of the valuevalue: 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 createdeclass: element classn: 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 createdarray_class: array classlengths: lengths for each dimension in the arraylower_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 classn: 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 elementsidx: 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 instancefield: MonoClassField describing the field to fetch information fromvalue: 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 fromobj: 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 objectfield: MonoClassField describing the field to setvalue: 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 objectfield: MonoClassField describing the field to fetch information fromvalue: 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 setvalue: 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 fetchobj: instance object on which to actparams: parameters to pass to the properyexc: 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 setobj: instance object on which to actparams: parameters to pass to the properyexc: 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, MonoClass *klass, MonoClassField *field, gpointer *res)
Parameters
this: pointer to an objectklass: klass of the object containing fieldfield: the field to loadres: 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, MonoClass *klass, MonoClassField *field)
Parameters
this: klass: field:
Remarks
	 
	 Missing documentation.
  
 
    mono_store_remote_field
    void
mono_store_remote_field (MonoObject *this, MonoClass *klass, MonoClassField *field, gpointer val)
Parameters
this: pointer to an objectklass: klass of the object containing fieldfield: the field to loadval: the value/object to store
Remarks
	 
	 This method is called by the runtime on attempts to store fields of
	 transparent proxy objects. 
this points to such TP, 
klass is the class of
	 the object containing 
field. 
val is the new value to store in 
field.