docs/sources/mono-api-methods.html

   1 <h2>Methods</h2>
   2
   3         <p>Methods are represented by the <code>MonoMethod*</code>
   4         instances.  Various APIs surface these instances, but usually
   5         you will use the <a href="#method-desc">method description</a>
   6         API to get a handle to a Mono Method.   You can <a href="method-invoking">invoke</a> those methods from C,
   7         or you can probe <a href="method-working">probe various properties</a> of a method, and in particular
   8         its <a href="method-signature">method signature</a> or get
   9         some <a href="method-header">low-level information</a> about them.
  10
  11         <p>The following code snippet from the Mono runtime shows you
  12         how to create a managed <code>System.Version</code> instance
  13         with four integers by looking up the constructor in the
  14         managed implementation of System.Version, creating an instance
  15         of the object, and then invoking the constructor on it.
  16
  17         <div class="mapi-header">
  18 MonoObject*
  19 create_version (MonoDomain *domain, guint32 major, guint32 minor, guint32 build, guint32 revision)
  20 {
  21     MonoClass *System_Version;
  22     MonoMethod *create_version;
  23     MonoError error;
  24     MonoObject *result;
  25     gpointer args [4];
  26
  27     System_Version = mono_class_from_name (mono_defaults.corlib, "System", "Version");
  28
  29     // Create a method description that we use to search for the
  30     // constructor method
  31     MonoMethodDesc *desc = mono_method_desc_new (":.ctor(int,int,int,int)", FALSE);
  32     create_version = mono_method_desc_search_in_class (desc, System_Version);
  33     mono_method_desc_free (desc);
  34
  35     // Setup the parameters to pass.
  36     args [0] = &major;
  37     args [1] = &minor;
  38     args [2] = &build;
  39     args [3] = &revision;
  40
  41     // Create the object instance
  42     result = mono_object_new_checked (domain, System_Version, &error);
  43
  44     // Raise an exception in case of an error
  45     mono_error_raise_exception (&error);
  46
  47     // Otherwise, invoke the constructor
  48     mono_runtime_invoke (create_version, result, args, NULL);
  49
  50     // Return ther esult
  51     return result;
  52 }
  53
  54         </div>
  55
  56 <a name="method-desc"></a>
  57 <h3>Method Descriptions</h3>
  58
  59         <p>Methods are represented by the <code>MonoMethod*</code>
  60         instances.  To simplify the process of getting
  61         a <code>MonoMethod*</code>, you use Method Descriptors, which
  62         are C-strings that describe the method that you are looking
  63         for, and then you perform a search in either
  64         a <a href="mono-api-type.html">type</a>, or a
  65         loaded <a href="mono-api-image.html">image</a>.
  66
  67
  68         <p>To describe a method, you use the Method Description API.
  69         Method descriptions are used to locate a method in the
  70         executing program.   They can either be fully specified, that
  71         is, they would include the namespace, class, method name and
  72         all of its arguments or they omit the namespace and arguments
  73         and even use wildcard matches for the class name and method names.
  74
  75         <p>You use the fully specified version to identify a
  76         particular method, or you can use the partial version to find
  77         a method or a family of methods in the code.
  78
  79         <p>Method descriptions are typically created from a C string
  80         representation, and take the following form:
  81
  82         <p><code>[namespace.]classname:methodname[(args...)]</code>
  83
  84         <p>Both classname and methodname can contain the '*' character
  85         which can be used to match anything.  Arguments are separated
  86         by commas.
  87
  88         <p>You can use the type shortcuts to match the fully qualified
  89         parameter types.  The supported type shortcuts are:
  90         <code>char</code>,
  91         <code>bool</code>,
  92         <code>byte</code>,
  93         <code>sbyte</code>,
  94         <code>uint16</code>,
  95         <code>int16</code>,
  96         <code>uint</code>,
  97         <code>int</code>,
  98         <code>ulong</code>,
  99         <code>long</code>,
 100         <code>uintptr</code>,
 101         <code>intptr</code>,
 102         <code>single</code>,
 103         <code>double</code>,
 104         <code>string</code> and
 105         <code>object</code>.
 106
 107         <p>The type parameters can use the "&" and "*" type modifiers.
 108
 109         <p>Examples of method descriptions:
 110         <ul>
 111                 <li>"Monitor:Exit": matches classes and methods called "Monitor.Exit"
 112                 <li>"Monitor:enter_with_atomic_var(object,bool&)":
 113                 matches a method in the class Monitor with two
 114                 specific type parameters.
 115                 <li>":.ctor(int,int,int,int)": matches constructors
 116                 that take four integers.
 117                 <li>"System.Globalization.CultureInfo:CreateCulture(string,bool)":
 118                 matches the CreateCultureMethod that takes a string
 119                 and a boolean on the System.Globalization.CultureInfo class.
 120         </ul>
 121
 122         <p>You can
 123         then <a href="api:mono_method_desc_search_in_image">search for
 124         methods in MonoImages</a>
 125         or <a href="api:mono_method_desc_search_in_class">search for
 126         methods in classes</a>.
 127
 128 <h4><a name="api:mono_method_desc_new">mono_method_desc_new</a></h4>
 129 <h4><a name="api:mono_method_desc_free">mono_method_desc_free</a></h4>
 130 <h4><a name="api:mono_method_desc_from_method">mono_method_desc_from_method</a></h4>
 131 <h4><a name="api:mono_method_desc_full_match">mono_method_desc_full_match</a></h4>
 132 <h4><a name="api:mono_method_desc_match">mono_method_desc_match</a></h4>
 133 <h4><a name="api:mono_method_desc_search_in_class">mono_method_desc_search_in_class</a></h4>
 134 <h4><a name="api:mono_method_desc_search_in_image">mono_method_desc_search_in_image</a></h4>
 135
 136 <a name="method-working"></a>
 137 <h3>Working with Methods</h3>
 138
 139 <h4><a name="api:mono_method_full_name">mono_method_full_name</a></h4>
 140 <h4><a name="api:mono_method_get_class">mono_method_get_class</a></h4>
 141 <h4><a name="api:mono_method_get_flags">mono_method_get_flags</a></h4>
 142 <h4><a name="api:mono_method_get_last_managed">mono_method_get_last_managed</a></h4>
 143 <h4><a name="api:mono_method_get_marshal_info">mono_method_get_marshal_info</a></h4>
 144 <h4><a name="api:mono_method_get_name">mono_method_get_name</a></h4>
 145 <h4><a name="api:mono_method_get_object">mono_method_get_object</a></h4>
 146 <h4><a name="api:mono_method_get_param_names">mono_method_get_param_names</a></h4>
 147 <h4><a name="api:mono_method_get_param_token">mono_method_get_param_token</a></h4>
 148 <h4><a name="api:mono_method_get_signature">mono_method_get_signature</a></h4>
 149 <h4><a name="api:mono_method_get_index">mono_method_get_index</a></h4>
 150 <h4><a name="api:mono_method_get_signature_full">mono_method_get_signature_full</a></h4>
 151 <h4><a name="api:mono_method_get_token">mono_method_get_token</a></h4>
 152 <h4><a name="api:mono_method_get_unmanaged_thunk">mono_method_get_unmanaged_thunk</a></h4>
 153 <h4><a name="api:mono_method_has_marshal_info">mono_method_has_marshal_info</a></h4>
 154 <h4><a name="api:mono_method_verify">mono_method_verify</a></h4>
 155
 156 <a name="method-invoking"></a>
 157 <h3>Invoking Methods</h3>
 158
 159 <h4><a name="api:mono_runtime_invoke">mono_runtime_invoke</a></h4>
 160
 161 If you want to invoke generic methods, you must call the method on the
 162 "inflated" class, which you can obtain from the
 163 <tt>mono_object_get_class()</tt>
 164
 165 <div class="mapi-code">
 166 MonoClass *clazz;
 167 MonoMethod *method;
 168
 169 clazz = mono_object_get_class (obj);
 170
 171 /*
 172  * If there are more Add methods declared, you
 173  * may use mono_method_desc_search_in_class (clazz, ":Add(T)"),
 174  * you must substitute ":Add(T)" with the correct type, for example
 175  * for List&lt;int&gt;, you would use ":Add(int)".
 176  */
 177 method = mono_class_get_method_from_name (clazz, "Add", 1);
 178 mono_runtime_invoke (method, obj, args, &amp;exception);
 179 </div>
 180
 181
 182 <h4><a name="api:mono_runtime_invoke_array">mono_runtime_invoke_array</a></h4>
 183 <h4><a name="api:mono_runtime_delegate_invoke">mono_runtime_delegate_invoke</a></h4>
 184
 185 <h4><a name="api:mono_method_body_get_object">mono_method_body_get_object</a></h4>
 186
 187 <a name="method-signature"></a>
 188 <h3>Method Signatures</h3>
 189
 190 <h4><a name="api:mono_method_signature">mono_method_signature</a></h4>
 191 <h4><a name="api:mono_signature_explicit_this">mono_signature_explicit_this</a></h4>
 192 <h4><a name="api:mono_signature_get_call_conv">mono_signature_get_call_conv</a></h4>
 193 <h4><a name="api:mono_signature_get_desc">mono_signature_get_desc</a></h4>
 194 <h4><a name="api:mono_signature_get_param_count">mono_signature_get_param_count</a></h4>
 195 <h4><a name="api:mono_signature_get_params">mono_signature_get_params</a></h4>
 196 <h4><a name="api:mono_signature_get_return_type">mono_signature_get_return_type</a></h4>
 197 <h4><a name="api:mono_signature_hash">mono_signature_hash</a></h4>
 198 <h4><a name="api:mono_signature_is_instance">mono_signature_is_instance</a></h4>
 199 <h4><a name="api:mono_signature_param_is_out">mono_signature_param_is_out</a></h4>
 200 <h4><a name="api:mono_signature_vararg_start">mono_signature_vararg_start</a></h4>
 201 <h4><a name="api:mono_param_get_objects">mono_param_get_objects</a></h4>
 202 <h4><a name="api:mono_get_method_full">mono_get_method_full</a></h4>
 203 <h4><a name="api:mono_get_method">mono_get_method</a></h4>
 204
 205 <a name="method-header"></a>
 206 <h3>Methods Header Operations</h3>
 207
 208 <h4><a name="api:mono_method_get_header">mono_method_get_header</a></h4>
 209 <h4><a name="api:mono_method_header_get_clauses">mono_method_header_get_clauses</a></h4>
 210 <h4><a name="api:mono_method_header_get_code">mono_method_header_get_code</a></h4>
 211 <h4><a name="api:mono_method_header_get_locals">mono_method_header_get_locals</a></h4>
 212 <h4><a name="api:mono_method_header_get_num_clauses">mono_method_header_get_num_clauses</a></h4>