docs/sources/mono-api-object.html

   1 <h1>Object API</h1>
   2
   3         <p>The object API deals with all the operations shared by
   4         <a href="#objects">objects</a>, <a href="#valuetypes">value
   5         types</a>, <a href="#arrays">arrays</a>.
   6
   7         <p>The object API has methods for accessing <a
   8         href="#fields">fields</a>, <a
   9         href="#properties">properties</a>, <a href="mono-api-methods.html">methods</a>, <a
  10         href="#events">events</a>, <a href="#delegates">delegates</a>.
  11
  12
  13
  14         <p>There are some advanced uses that are useful to document
  15         here dealing with <a href="#remote">remote fields</a>.
  16
  17 <h2>Synopsis</h2>
  18
  19 <div class="mapi-header">
  20 #include &lt;metadata/object.h&gt;
  21
  22 typedef struct MonoVTable MonoVTable;
  23 typedef struct _MonoThreadsSync MonoThreadsSync;
  24
  25 typedef struct {
  26         MonoVTable *vtable;
  27         MonoThreadsSync *synchronisation;
  28 } MonoObject;
  29
  30 typedef struct {
  31         guint32 length;
  32         guint32 lower_bound;
  33 } MonoArrayBounds;
  34
  35 typedef struct {
  36         MonoObject obj;
  37         /* bounds is NULL for szarrays */
  38         MonoArrayBounds *bounds;
  39         /* total number of elements of the array */
  40         guint32 max_length;
  41         /* we use double to ensure proper alignment on platforms that need it */
  42         double vector [MONO_ZERO_LEN_ARRAY];
  43 } MonoArray;
  44
  45 @API_IDX@
  46 </div>
  47
  48         <p>`MonoObject` is the base definition for all managed objects
  49         in the Mono runtime, it represents the <a
  50         href="http://www.mono-project.com/monodoc/T:System.Object">System.Object</a>
  51         managed type.
  52
  53         <p>All objects that derive from <a
  54         href="http://www.mono-project.com/monodoc/T:System.Object">System.Object</a>
  55         do have this base definition.  Derived objects are declared
  56         following the pattern where the parent class is the first
  57         field of a structure definition, for example:
  58
  59         <div class="mapi-code">
  60 typedef struct {
  61         MonoObject parent;
  62         int my_new_field;
  63 } MyNewObject</div>
  64
  65 <a name="objects"></a>
  66 <h2>Core Object Methods</h2>
  67
  68 <h4><a name="api:mono_object_new">mono_object_new</a></h4>
  69
  70         <p>For example, if you wanted to create an object of type
  71         System.Version, you would use a piece of code like this:
  72
  73 <div class="mapi-code">
  74 MonoClass *version_class;
  75 MonoObject *result;
  76
  77 /* Get the class from mscorlib */
  78 version_class = mono_class_from_name (mono_get_corlib (),
  79         "System", "Version");
  80
  81 /* Create an object of that class */
  82 result = mono_object_new (mono_domain_get (), version_class);
  83 </div>
  84
  85 <h4><a name="api:mono_object_new_alloc_specific">mono_object_new_alloc_specific</a></h4>
  86 <h4><a name="api:mono_object_new_fast">mono_object_new_fast</a></h4>
  87 <h4><a name="api:mono_object_new_from_token">mono_object_new_from_token</a></h4>
  88 <h4><a name="api:mono_object_new_specific">mono_object_new_specific</a></h4>
  89 <h4><a name="api:mono_object_clone">mono_object_clone</a></h4>
  90 <h4><a name="api:mono_object_get_class">mono_object_get_class</a></h4>
  91 <h4><a name="api:mono_object_get_domain">mono_object_get_domain</a></h4>
  92 <h4><a name="api:mono_object_get_virtual_method">mono_object_get_virtual_method</a></h4>
  93 <h4><a name="api:mono_object_isinst_mbyref">mono_object_isinst_mbyref</a></h4>
  94 <h4><a name="api:mono_object_isinst">mono_object_isinst</a></h4>
  95 <h4><a name="api:mono_object_unbox">mono_object_unbox</a></h4>
  96 <h4><a name="api:mono_object_castclass_mbyref">mono_object_castclass_mbyref</a></h4>
  97 <h4><a name="api:mono_object_get_size">mono_object_get_size</a></h4>
  98 <h4><a name="api:mono_object_hash">mono_object_hash</a></h4>
  99 <h4><a name="api:mono_object_to_string">mono_object_to_string</a></h4>
 100
 101 <a name="valuetypes"></a>
 102 <h2>Value Types</h2>
 103
 104 <h4><a name="api:mono_value_box">mono_value_box</a></h4>
 105 <h4><a name="api:mono_value_copy">mono_value_copy</a></h4>
 106 <h4><a name="api:mono_value_copy_array">mono_value_copy_array</a></h4>
 107
 108 <a name="arrays"></a>
 109 <h2>Array Methods</h2>
 110
 111         <p>Use the <tt>mono_array_new_*</tt> methods to create arrays
 112         of a given type.
 113
 114         <p>For example, the following code creates an array with two
 115         elements of type <tt>System.Byte</tt>, and sets the values
 116         0xca and 0xfe on it:
 117
 118         <pre class="mapi-code">
 119 MonoArray *CreateByteArray (MonoDomain *domain)
 120 {
 121     MonoArray *data;
 122
 123     data = mono_array_new (domain, mono_get_byte_class (), 2);
 124     mono_array_set (data, guint8, 0, 0xca);
 125     mono_array_set (data, guint8, 0, 0xfe);
 126
 127     return data;
 128 }
 129         </pre>
 130
 131 <h3>Creating Arrays</h3>
 132
 133 <h4><a name="api:mono_array_new">mono_array_new</a></h4>
 134 <h4><a name="api:mono_array_new_full">mono_array_new_full</a></h4>
 135 <h4><a name="api:mono_array_new_specific">mono_array_new_specific</a></h4>
 136 <h4><a name="api:mono_array_class_get">mono_array_class_get</a></h4>
 137 <h4><a name="api:mono_array_clone">mono_array_clone</a></h4>
 138
 139 <h3>Using Arrays</h3>
 140
 141         <p>Arrays are represented by the `MonoArray` data type and are
 142         instances of `MonoObject`.   While you can use the `bounds`
 143         and `max_length` fields of the type, the actual storage
 144         (represented by `vector`) is not very useful.   Instead you
 145         should use one of the accesor methods described below to
 146         fetch or set the values in the array.
 147
 148         <p>When setting values in an array, you should
 149         use <a href="api:mono_array_set">mono_array_set</a> for
 150         setting elements in an array that contains value types, and
 151         <a
 152         href="api:mono_array_setref">mono_array_setref</a> for arrays
 153         that contain reference types.
 154
 155         <p>The <a href="api:mono_array_get">mono_array_get</a>,
 156         <a href="api:mono_array_set">mono_array_set</a> and <a
 157         href="api:mono_array_setref">mono_array_setref</a> are C
 158         macros that wrap the underlying array access.
 159
 160 <h4><a name="api:mono_array_get">mono_array_get</a></h4>
 161 <h4><a name="api:mono_array_length">mono_array_length</a></h4>
 162 <h4><a name="api:mono_array_set">mono_array_set</a></h4>
 163 <h4><a name="api:mono_array_setref">mono_array_setref</a></h4>
 164 <h4><a name="api:mono_array_addr">mono_array_addr</a></h4>
 165 <h4><a name="api:mono_array_addr_with_size">mono_array_addr_with_size</a></h4>
 166 <h4><a name="api:mono_array_element_size">mono_array_element_size</a></h4>
 167
 168 <a name="fields"></a>
 169 <h2>Fields</h2>
 170
 171 <h4><a name="api:mono_field_from_token">mono_field_from_token</a></h4>
 172 <h4><a name="api:mono_field_get_flags">mono_field_get_flags</a></h4>
 173 <h4><a name="api:mono_field_get_name">mono_field_get_name</a></h4>
 174 <h4><a name="api:mono_field_get_parent">mono_field_get_parent</a></h4>
 175 <h4><a name="api:mono_field_get_type">mono_field_get_type</a></h4>
 176 <h4><a name="api:mono_field_get_value">mono_field_get_value</a></h4>
 177 <h4><a name="api:mono_field_get_value_object">mono_field_get_value_object</a></h4>
 178 <h4><a name="api:mono_field_set_value">mono_field_set_value</a></h4>
 179 <h4><a name="api:mono_field_static_get_value">mono_field_static_get_value</a></h4>
 180 <h4><a name="api:mono_field_static_set_value">mono_field_static_set_value</a></h4>
 181 <h4><a name="api:mono_field_get_object">mono_field_get_object</a></h4>
 182
 183 <a name="properties"></a>
 184 <h2>Properties</h2>
 185
 186 <h4><a name="api:mono_property_get_object">mono_property_get_object</a></h4>
 187 <h4><a name="api:mono_property_get_flags">mono_property_get_flags</a></h4>
 188 <h4><a name="api:mono_property_get_get_method">mono_property_get_get_method</a></h4>
 189 <h4><a name="api:mono_property_get_name">mono_property_get_name</a></h4>
 190 <h4><a name="api:mono_property_get_parent">mono_property_get_parent</a></h4>
 191 <h4><a name="api:mono_property_get_set_method">mono_property_get_set_method</a></h4>
 192 <h4><a name="api:mono_property_get_value">mono_property_get_value</a></h4>
 193 <h4><a name="api:mono_property_set_value">mono_property_set_value</a></h4>
 194
 195 <a name="events"></a>
 196 <h2>Events</h2>
 197
 198 <h4><a name="api:mono_event_get_object">mono_event_get_object</a></h4>
 199 <h4><a name="api:mono_event_get_add_method">mono_event_get_add_method</a></h4>
 200 <h4><a name="api:mono_event_get_flags">mono_event_get_flags</a></h4>
 201 <h4><a name="api:mono_event_get_name">mono_event_get_name</a></h4>
 202 <h4><a name="api:mono_event_get_parent">mono_event_get_parent</a></h4>
 203 <h4><a name="api:mono_event_get_raise_method">mono_event_get_raise_method</a></h4>
 204 <h4><a name="api:mono_event_get_remove_method">mono_event_get_remove_method</a></h4>
 205
 206 <a name="remote"></a>
 207 <h2>Remote Fields</h2>
 208 <h4><a name="api:mono_load_remote_field">mono_load_remote_field</a></h4>
 209 <h4><a name="api:mono_load_remote_field_new">mono_load_remote_field_new</a></h4>
 210 <h4><a name="api:mono_store_remote_field">mono_store_remote_field</a></h4>
 211 <h4><a name="api:mono_store_remote_field_new">mono_store_remote_field_new</a></h4>
 212
 213 <a name="delegates"></a>
 214 <h2>Delegates</h2>
 215 <h4><a name="api:mono_get_delegate_begin_invoke">mono_get_delegate_begin_invoke</a></h4>
 216 <h4><a name="api:mono_get_delegate_end_invoke">mono_get_delegate_end_invoke</a></h4>