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.