mono-api-methods.html

## Methods

Methods are represented by the `MonoMethod*` instances. Various APIs surface these instances, but usually you will use the method description API to get a handle to a Mono Method. You can invoke those methods from C, or you can probe probe various properties of a method, and in particular its method signature or get some low-level information about them.

The following code snippet from the Mono runtime shows you how to create a managed `System.Version` instance with four integers by looking up the constructor in the managed implementation of System.Version, creating an instance of the object, and then invoking the constructor on it.
MonoObject* create_version (MonoDomain *domain, guint32 major, guint32 minor, guint32 build, guint32 revision) { MonoClass *System_Version; MonoMethod *create_version; MonoError error; MonoObject *result; gpointer args [4]; System_Version = mono_class_from_name (mono_defaults.corlib, "System", "Version"); // Create a method description that we use to search for the // constructor method MonoMethodDesc *desc = mono_method_desc_new (":.ctor(int,int,int,int)", FALSE); create_version = mono_method_desc_search_in_class (desc, System_Version); mono_method_desc_free (desc); // Setup the parameters to pass. args [0] = &major; args [1] = &minor; args [2] = &build; args [3] = &revision; // Create the object instance result = mono_object_new_checked (domain, System_Version, &error); // Raise an exception in case of an error mono_error_raise_exception (&error); // Otherwise, invoke the constructor mono_runtime_invoke (create_version, result, args, NULL); // Return ther esult return result; }

### Method Descriptions

Methods are represented by the `MonoMethod*` instances. To simplify the process of getting a `MonoMethod*`, you use Method Descriptors, which are C-strings that describe the method that you are looking for, and then you perform a search in either a type, or a loaded image.

To describe a method, you use the Method Description API. Method descriptions are used to locate a method in the executing program. They can either be fully specified, that is, they would include the namespace, class, method name and all of its arguments or they omit the namespace and arguments and even use wildcard matches for the class name and method names.

You use the fully specified version to identify a particular method, or you can use the partial version to find a method or a family of methods in the code.

Method descriptions are typically created from a C string representation, and take the following form:

`[namespace.]classname:methodname[(args...)]`

Both classname and methodname can contain the '*' character which can be used to match anything. Arguments are separated by commas.

You can use the type shortcuts to match the fully qualified parameter types. The supported type shortcuts are: `char`, `bool`, `byte`, `sbyte`, `uint16`, `int16`, `uint`, `int`, `ulong`, `long`, `uintptr`, `intptr`, `single`, `double`, `string` and `object`.

The type parameters can use the "&" and "*" type modifiers.

Examples of method descriptions:

- "Monitor:Exit": matches classes and methods called "Monitor.Exit"
- "Monitor:enter_with_atomic_var(object,bool&)": matches a method in the class Monitor with two specific type parameters.
- ":.ctor(int,int,int,int)": matches constructors that take four integers.
- "System.Globalization.CultureInfo:CreateCulture(string,bool)": matches the CreateCultureMethod that takes a string and a boolean on the System.Globalization.CultureInfo class.

You can then search for methods in MonoImages or search for methods in classes.
`mono_method_desc_new`
Syntax
MonoMethodDesc* mono_method_desc_new (const char *name, gboolean include_namespace)

Parameters

name | the method name.
include_namespace | whether the name includes a namespace or not.

Return value
a parsed representation of the method description.
Description

Creates a method description for name, which conforms to the following specification:

`[namespace.]classname:methodname[(args...)]`

in all the loaded assemblies.

Both classname and methodname can contain `*` which matches anything.

`mono_method_desc_free`
Syntax
void mono_method_desc_free (MonoMethodDesc *desc)

Parameters

desc | method description to be released

Description
Releases the `MonoMethodDesc` object desc.
`mono_method_desc_from_method`
Syntax
MonoMethodDesc* mono_method_desc_from_method (MonoMethod *method)

`mono_method_desc_full_match`
Syntax
gboolean mono_method_desc_full_match (MonoMethodDesc *desc, MonoMethod *method)

Parameters

desc | A method description that you created with mono_method_desc_new
method | a MonoMethod instance that you want to match against

Return value
`TRUE` if the specified method matches the specified description, `FALSE` otherwise.
Description

This method is used to check whether the method matches the provided description, by making sure that the method matches both the class and the method parameters.

`mono_method_desc_match`
Syntax
gboolean mono_method_desc_match (MonoMethodDesc *desc, MonoMethod *method)

Parameters

desc | `MonoMethoDescription`
method | `MonoMethod` to test

Return value
`TRUE` if the method matches the description, `FALSE` otherwise.
Description

Determines whether the specified method matches the provided desc description.

namespace and class are supposed to match already if this function is used.
`mono_method_desc_search_in_class`
Syntax
MonoMethod* mono_method_desc_search_in_class (MonoMethodDesc *desc, MonoClass *klass)

`mono_method_desc_search_in_image`
Syntax
MonoMethod* mono_method_desc_search_in_image (MonoMethodDesc *desc, MonoImage *image)

### Working with Methods

`mono_method_full_name`
Syntax
char* mono_method_full_name (MonoMethod *method, gboolean signature)

`mono_method_get_class`
Syntax
MonoClass* mono_method_get_class (MonoMethod *method)

`mono_method_get_flags`
Syntax
guint32 mono_method_get_flags (MonoMethod *method, guint32 *iflags)

`mono_method_get_last_managed`
Syntax
MonoMethod* mono_method_get_last_managed (void)

`mono_method_get_marshal_info`
Syntax
void mono_method_get_marshal_info (MonoMethod *method, MonoMarshalSpec **mspecs)

`mono_method_get_name`
Syntax
const char* mono_method_get_name (MonoMethod *method)

`mono_method_get_object`
Syntax
MonoReflectionMethod* mono_method_get_object (MonoDomain *domain, MonoMethod *method, MonoClass *refclass)

Parameters

domain | an app domain
method | a method
refclass | the reflected type (can be `NULL`)

Return value
A `System.Reflection.MonoMethod` object representing the method method.
`mono_method_get_param_names`
Syntax
void mono_method_get_param_names (MonoMethod *method, const char **names)

`mono_method_get_param_token`
Syntax
guint32 mono_method_get_param_token (MonoMethod *method, int index)

`mono_method_get_signature`
Syntax
MonoMethodSignature* mono_method_get_signature (MonoMethod *method, MonoImage *image, guint32 token)

Description
token is the method_ref/def/spec token used in a call IL instruction. \deprecated use the `_checked` variant Notes: runtime code MUST not use this function
`mono_method_get_index`
Syntax
guint32 mono_method_get_index (MonoMethod *method)

Description
Find the method index in the metadata `MethodDef` table.
`mono_method_get_signature_full`
Syntax
MonoMethodSignature* mono_method_get_signature_full (MonoMethod *method, MonoImage *image, guint32 token, MonoGenericContext *context)

Description
token is the method ref/def/spec token used in a `call` IL instruction. \deprecated use the `_checked` variant Notes: runtime code MUST not use this function
`mono_method_get_token`
Syntax
guint32 mono_method_get_token (MonoMethod *method)

`mono_method_get_unmanaged_thunk`
Syntax
gpointer mono_method_get_unmanaged_thunk (MonoMethod *method)

Parameters

method | method to generate a thunk for.

Description

Returns an `unmanaged->managed` thunk that can be used to call a managed method directly from C.

The thunk's C signature closely matches the managed signature:

C#: `public bool Equals (object obj);`

C: `typedef MonoBoolean (*Equals)(MonoObject*, MonoObject*, MonoException**);`

The 1st (`this`) parameter must not be used with static methods:

C#: `public static bool ReferenceEquals (object a, object b);`

C: `typedef MonoBoolean (*ReferenceEquals)(MonoObject*, MonoObject*, MonoException**);`

The last argument must be a non-null `MonoException*` pointer. It has "out" semantics. After invoking the thunk, `*ex` will be `NULL` if no exception has been thrown in managed code. Otherwise it will point to the `MonoException*` caught by the thunk. In this case, the result of the thunk is undefined:

     MonoMethod *method = ... // MonoMethod* of System.Object.Equals

     MonoException *ex = NULL;

     Equals func = mono_method_get_unmanaged_thunk (method);

     MonoBoolean res = func (thisObj, objToCompare, &ex);

     if (ex) {

        // handle exception

     }

The calling convention of the thunk matches the platform's default convention. This means that under Windows, C declarations must contain the `__stdcall` attribute:

C: `typedef MonoBoolean (__stdcall *Equals)(MonoObject*, MonoObject*, MonoException**);`

LIMITATIONS

Value type arguments and return values are treated as they were objects:

C#: `public static Rectangle Intersect (Rectangle a, Rectangle b);` C: `typedef MonoObject* (*Intersect)(MonoObject*, MonoObject*, MonoException**);`

Arguments must be properly boxed upon trunk's invocation, while return values must be unboxed.
`mono_method_has_marshal_info`
Syntax
gboolean mono_method_has_marshal_info (MonoMethod *method)

`mono_method_verify`
Syntax
GSList* mono_method_verify (MonoMethod *method, int level)

Description
Verify types for opcodes.

### Invoking Methods

`mono_runtime_invoke`
Syntax
MonoObject* mono_runtime_invoke (MonoMethod *method, void *obj, void **params, MonoObject **exc)

Parameters

method | method to invoke
obj | object instance
params | arguments to the method
exc | exception information.

Description
Invokes the method represented by method on the object obj. obj is the `this` pointer, it should be `NULL` for static methods, a `MonoObject*` for object instances and a pointer to the value type for value types.

The params array contains the arguments to the method with the same convention: `MonoObject*` pointers for object instances and pointers to the value type otherwise.

From unmanaged code you'll usually use the `mono_runtime_invoke` variant.

Note that this function doesn't handle virtual methods for you, it will exec the exact method you pass: we still need to expose a function to lookup the derived class implementation of a virtual method (there are examples of this in the code, though).

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.

If the method returns a value type, it is boxed in an object reference.
If you want to invoke generic methods, you must call the method on the "inflated" class, which you can obtain from the `mono_object_get_class()`
MonoClass *clazz; MonoMethod *method; clazz = mono_object_get_class (obj); /* * If there are more Add methods declared, you * may use mono_method_desc_search_in_class (clazz, ":Add(T)"), * you must substitute ":Add(T)" with the correct type, for example * for List<int>, you would use ":Add(int)". */ method = mono_class_get_method_from_name (clazz, "Add", 1); mono_runtime_invoke (method, obj, args, &exception);
`mono_runtime_invoke_array`
Syntax
MonoObject* mono_runtime_invoke_array (MonoMethod *method, void *obj, MonoArray *params, MonoObject **exc)

Parameters

method | method to invoke
obj | object instance
params | arguments to the method
exc | exception information.

Description
Invokes the method represented by method on the object obj.

obj is the `this` pointer, it should be `NULL` for static methods, a `MonoObject*` for object instances and a pointer to the value type for value types.

The params array contains the arguments to the method with the same convention: `MonoObject*` pointers for object instances and pointers to the value type otherwise. The `_invoke_array` variant takes a C# `object[]` as the params argument (`MonoArray*)`: in this case the value types are boxed inside the respective reference representation.

From unmanaged code you'll usually use the mono_runtime_invoke_checked() variant.

Note that this function doesn't handle virtual methods for you, it will exec the exact method you pass: we still need to expose a function to lookup the derived class implementation of a virtual method (there are examples of this in the code, though).

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.

If the method returns a value type, it is boxed in an object reference.
`mono_runtime_delegate_invoke`
Syntax
MonoObject* mono_runtime_delegate_invoke (MonoObject *delegate, void **params, MonoObject **exc)

Parameters

delegate | pointer to a delegate object.
params | parameters for the delegate.
exc | Pointer to the exception result.

Description

Invokes the delegate method delegate with the parameters provided.

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_method_body_get_object`
Syntax
MonoReflectionMethodBody* mono_method_body_get_object (MonoDomain *domain, MonoMethod *method)

Parameters

domain | an app domain
method | a method

Return value
A `System.Reflection.MethodBody` object representing the method method.

### Method Signatures

`mono_method_signature`
Syntax
MonoMethodSignature* mono_method_signature (MonoMethod *m)

Return value
the signature of the method m. On failure, returns `NULL`.
`mono_signature_explicit_this`
Syntax
gboolean mono_signature_explicit_this (MonoMethodSignature *sig)

Parameters

sig | the method signature inspected

Return value
`TRUE` if this the method signature sig has an explicit instance argument. `FALSE` otherwise.
`mono_signature_get_call_conv`
Syntax
guint32 mono_signature_get_call_conv (MonoMethodSignature *sig)

Parameters

sig | the method signature inspected

Return value
the call convention of the method signature sig.
`mono_signature_get_desc`
Syntax
char* mono_signature_get_desc (MonoMethodSignature *sig, gboolean include_namespace)

`mono_signature_get_param_count`
Syntax
guint32 mono_signature_get_param_count (MonoMethodSignature *sig)

Parameters

sig | the method signature inspected

Return value
the number of parameters in the method signature sig.
`mono_signature_get_params`
Syntax
MonoType* mono_signature_get_params (MonoMethodSignature *sig, gpointer *iter)

Parameters

sig | the method signature inspected
iter | pointer to an iterator

Return value
the next parameter type of the method signature sig, `NULL` when finished.
Description
Iterates over the parameters for the method signature sig. A `void*` pointer must be initialized to `NULL` to start the iteration and its address is passed to this function repeteadly until it returns `NULL`.
`mono_signature_get_return_type`
Syntax
MonoType* mono_signature_get_return_type (MonoMethodSignature *sig)

Parameters

sig | the method signature inspected

Return value
the return type of the method signature sig
`mono_signature_hash`
Syntax
guint mono_signature_hash (MonoMethodSignature *sig)

`mono_signature_is_instance`
Syntax
gboolean mono_signature_is_instance (MonoMethodSignature *sig)

Parameters

sig | the method signature inspected

Return value
`TRUE` if this the method signature sig has an implicit first instance argument. `FALSE` otherwise.
`mono_signature_param_is_out`
Syntax
mono_bool mono_signature_param_is_out (MonoMethodSignature *sig, int param_num)

Parameters

sig | the method signature inspected
param_num | the 0-based index of the inspected parameter

Return value
`TRUE` if the parameter is an out parameter, `FALSE` otherwise.
`mono_signature_vararg_start`
Syntax
int mono_signature_vararg_start (MonoMethodSignature *sig)

Parameters

sig | the method signature inspected

Return value
the number of the first vararg parameter in the method signature \param sig. `-1` if this is not a vararg signature.
`mono_param_get_objects`
Syntax
MonoArray* mono_param_get_objects (MonoDomain *domain, MonoMethod *method)

`mono_get_method_full`
Syntax
MonoMethod* mono_get_method_full (MonoImage *image, guint32 token, MonoClass *klass, MonoGenericContext *context)

`mono_get_method`
Syntax
MonoMethod* mono_get_method (MonoImage *image, guint32 token, MonoClass *klass)

### Methods Header Operations

`mono_method_get_header`
Syntax
MonoMethodHeader* mono_method_get_header (MonoMethod *method)

`mono_method_header_get_clauses`
Syntax
int mono_method_header_get_clauses (MonoMethodHeader *header, MonoMethod *method, gpointer *iter, MonoExceptionClause *clause)

Parameters

header | a `MonoMethodHeader` pointer
method | `MonoMethod` the header belongs to
iter | pointer to a iterator
clause | pointer to a `MonoExceptionClause` structure which will be filled with the info

Return value
`TRUE` if clause was filled with info, `FALSE` if there are no more exception clauses.
Description

Get the info about the exception clauses in the method. Set `*iter` to `NULL` to initiate the iteration, then call the method repeatedly until it returns `FALSE`. At each iteration, the structure pointed to by clause if filled with the exception clause information.

`mono_method_header_get_code`
Syntax
const unsigned char* mono_method_header_get_code (MonoMethodHeader *header, guint32* code_size, guint32* max_stack)

Parameters

header | a `MonoMethodHeader` pointer
code_size | memory location for returning the code size
max_stack | memory location for returning the max stack

Return value
pointer to the IL code represented by the method header.
Description

Method header accessor to retreive info about the IL code properties: a pointer to the IL code itself, the size of the code and the max number of stack slots used by the code.

`mono_method_header_get_locals`
Syntax
MonoType* mono_method_header_get_locals (MonoMethodHeader *header, guint32* num_locals, gboolean *init_locals)

Parameters

header | a `MonoMethodHeader` pointer
num_locals | memory location for returning the number of local variables
init_locals | memory location for returning the init_locals flag

Return value
pointer to an array of types of the local variables
Description

Method header accessor to retreive info about the local variables: an array of local types, the number of locals and whether the locals are supposed to be initialized to 0 on method entry