mono-api-image.html

## Image Manipulation

Images are the component of assemblies that actually hold the CIL code and metadata in the extended PE/COFF file.

### Synopsis

#include <metadata/image.h> typedef struct _MonoImage MonoImage; typedef enum { MONO_IMAGE_OK, MONO_IMAGE_ERROR_ERRNO, MONO_IMAGE_MISSING_ASSEMBLYREF, MONO_IMAGE_IMAGE_INVALID } MonoImageOpenStatus;

### Image APIs

Images are the actual elements in the runtime that contain the actual code being executed.

### Opening and closing MonoImages

`mono_image_open`
Syntax
MonoImage* mono_image_open (const char *fname, MonoImageOpenStatus *status)

Parameters

fname | filename that points to the module we want to open
status | An error condition is returned in this field

Return value
An open image of type `MonoImage` or `NULL` on error. The caller holds a temporary reference to the returned image which should be cleared when no longer needed by calling `mono_image_close`. if `NULL`, then check the value of status for details on the error
`mono_image_open_full`
Syntax
MonoImage* mono_image_open_full (const char *fname, MonoImageOpenStatus *status, gboolean refonly)

`mono_image_open_from_data`
Syntax
MonoImage* mono_image_open_from_data (char *data, guint32 data_len, gboolean need_copy, MonoImageOpenStatus *status)

`mono_image_open_from_data_full`
Syntax
MonoImage* mono_image_open_from_data_full (char *data, guint32 data_len, gboolean need_copy, MonoImageOpenStatus *status, gboolean refonly)

`mono_image_close`
Syntax
void mono_image_close (MonoImage *image)

Parameters

image | The image file we wish to close

Description
Closes an image file, deallocates all memory consumed and unmaps all possible sections of the file
`mono_image_addref`
Syntax
void mono_image_addref (MonoImage *image)

Parameters

image | The image file we wish to add a reference to

Description
Increases the reference count of an image.
`mono_image_load_file_for_image`
Syntax
MonoImage* mono_image_load_file_for_image (MonoImage *image, int fileidx)

`mono_image_open_from_data_with_name`
Syntax
MonoImage* mono_image_open_from_data_with_name (char *data, guint32 data_len, gboolean need_copy, MonoImageOpenStatus *status, gboolean refonly, const char *name)

`mono_image_load_module`
Syntax
MonoImage* mono_image_load_module (MonoImage *image, int idx)

### Image Information

`mono_image_get_guid`
Syntax
const char* mono_image_get_guid (MonoImage *image)

`mono_image_get_assembly`
Syntax
MonoAssembly* mono_image_get_assembly (MonoImage *image)

Parameters

image | the `MonoImage` .

Return value
the assembly that holds this image.
Description
Use this routine to get the assembly that owns this image.
`mono_image_get_entry_point`
Syntax
guint32 mono_image_get_entry_point (MonoImage *image)

Parameters

image | the image where the entry point will be looked up.

Return value
the token for the entry point method in the image
Description
Use this routine to determine the metadata token for method that has been flagged as the entry point.
`mono_image_get_filename`
Syntax
const char* mono_image_get_filename (MonoImage *image)

Parameters

image | a `MonoImage`

Return value
the filename.
Description
Used to get the filename that hold the actual `MonoImage`
`mono_image_get_name`
Syntax
const char* mono_image_get_name (MonoImage *image)

Parameters

name | a `MonoImage`

Return value
the name of the assembly.
`mono_image_get_resource`
Syntax
const char* mono_image_get_resource (MonoImage *image, guint32 offset, guint32 *size)

Parameters

image | the image where the resource will be looked up.
offset | The offset to add to the resource
size | a pointer to an int where the size of the resource will be stored

Return value
the pointer to the resource whose offset is offset.
Description

This is a low-level routine that fetches a resource from the metadata that starts at a given offset. The size parameter is filled with the data field as encoded in the metadata.

`mono_image_get_table_info`
Syntax
const MonoTableInfo* mono_image_get_table_info (MonoImage *image, int table_id)

`mono_image_get_table_rows`
Syntax
int mono_image_get_table_rows (MonoImage *image, int table_id)

`mono_image_is_dynamic`
Syntax
gboolean mono_image_is_dynamic (MonoImage *image)

Parameters

image | the `MonoImage`

Return value
`TRUE` if the image was created dynamically, `FALSE` if not.
Description

Determines if the given image was created dynamically through the `System.Reflection.Emit` API
`mono_image_loaded_by_guid`
Syntax
MonoImage* mono_image_loaded_by_guid (const char *guid)

Description

Looks only in the global loaded images hash, will miss assemblies loaded into an AssemblyLoadContext.
`mono_image_loaded`
Syntax
MonoImage* mono_image_loaded (const char *name)

Parameters

name | path or assembly name of the image to load

Return value
the loaded `MonoImage`, or `NULL` on failure.
Description
This routine verifies that the given image is loaded. Reflection-only loads do not count.
`mono_image_lookup_resource`
Syntax
gpointer mono_image_lookup_resource (MonoImage *image, guint32 res_id, guint32 lang_id, gunichar2 *name)

Parameters

image | the image to look up the resource in
res_id | A `MONO_PE_RESOURCE_ID_` that represents the resource ID to lookup.
lang_id | The language id.
name | the resource name to lookup.

Return value
`NULL` if not found, otherwise a pointer to the in-memory representation of the given resource. The caller should free it using `g_free` when no longer needed.
`mono_image_strerror`
Syntax
const char * mono_image_strerror (MonoImageOpenStatus status)

Parameters

status | an code indicating the result from a recent operation

Return value
a string describing the error
`mono_get_method_constrained`
Syntax
MonoMethod* mono_get_method_constrained (MonoImage *image, guint32 token, MonoClass *constrained_class, MonoGenericContext *context, MonoMethod **cil_method)

Return value
The contrained method, which has been inflated as the function return value; and the original CIL-stream method as declared in cil_method. The latter is used for verification.
Description
This is used when JITing the `constrained.` opcode.

### Public Keys, Strong Names and Certificates

`mono_image_strong_name_position`
Syntax
guint32 mono_image_strong_name_position (MonoImage *image, guint32 *size)

Parameters

image | a `MonoImage`
size | a `guint32` pointer, or `NULL`.

Return value
the position within the image file where the strong name is stored.
Description

If the image has a strong name, and size is not `NULL`, the value pointed to by size will have the size of the strong name.

`mono_image_get_public_key`
Syntax
const char* mono_image_get_public_key (MonoImage *image, guint32 *size)

Parameters

image | a `MonoImage`
size | a `guint32` pointer, or `NULL`.

Return value
`NULL` if the image does not have a public key, or a pointer to the public key.
Description

This is used to obtain the public key in the image.

If the image has a public key, and size is not `NULL`, the value pointed to by size will have the size of the public key.

`mono_image_get_strong_name`
Syntax
const char* mono_image_get_strong_name (MonoImage *image, guint32 *size)

Parameters

image | a MonoImage
size | a `guint32` pointer, or `NULL`.

Return value
`NULL` if the image does not have a strong name, or a pointer to the public key.
Description

If the image has a strong name, and size is not `NULL`, the value pointed to by size will have the size of the strong name.

`mono_image_has_authenticode_entry`
Syntax
gboolean mono_image_has_authenticode_entry (MonoImage *image)

Parameters

image | the `MonoImage`

Return value
`TRUE` if the image contains an authenticode entry in the PE directory.
Description
Use this routine to determine if the image has a Authenticode Certificate Table.

### Low-level features

`mono_image_rva_map`
Syntax
char* mono_image_rva_map (MonoImage *image, guint32 addr)

Parameters

image | a `MonoImage`
addr | relative virtual address (RVA)

Return value
the address in memory for the given RVA, or `NULL` if the RVA is not valid for this image.
Description

This is a low-level routine used by the runtime to map relative virtual address (RVA) into their location in memory.

`mono_image_ensure_section_idx`
Syntax
int mono_image_ensure_section_idx (MonoImage *image, int section)

Parameters

image | The image we are operating on
section | section number that we will load/map into memory

Return value
`TRUE` on success
Description

This routine makes sure that we have an in-memory copy of an image section (`.text`, `.rsrc`, `.data`).

`mono_image_ensure_section`
Syntax
int mono_image_ensure_section (MonoImage *image, const char *section)

Parameters

image | The image we are operating on
section | section name that we will load/map into memory

Return value
`TRUE` on success
Description

This routine makes sure that we have an in-memory copy of an image section (.text, .rsrc, .data).

`mono_image_init`
Syntax
void mono_image_init (MonoImage *image)

`mono_images_init`
Syntax
void mono_images_init (void)

Description

Initialize the global variables used by this module.
`mono_images_cleanup`
Syntax
void mono_images_cleanup (void)

Description

Free all resources used by this module.
`mono_image_add_to_name_cache`
Syntax
void mono_image_add_to_name_cache (MonoImage *image, const char *nspace, const char *name, guint32 index)

`mono_image_fixup_vtable`
Syntax
void mono_image_fixup_vtable (MonoImage *image)

`mono_image_loaded_by_guid_full`
Syntax
MonoImage* mono_image_loaded_by_guid_full (const char *guid, gboolean refonly)

Description

Looks only in the global loaded images hash, will miss assemblies loaded into an AssemblyLoadContext.
`mono_image_loaded_full`
Syntax
MonoImage* mono_image_loaded_full (const char *name, gboolean refonly)

Parameters

name | path or assembly name of the image to load
refonly | Check with respect to reflection-only loads?

Return value
the loaded `MonoImage`, or `NULL` on failure.
Description

This routine verifies that the given image is loaded. It checks either reflection-only loads only, or normal loads only, as specified by parameter.