Image Manipulation
Images are the component of assemblies that actually hold
the CIL code and
metadata
in the extended PE/COFF file.
Synopsis
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
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
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
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
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
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.