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; MonoImage* mono_image_open (const char *fname, MonoImageOpenStatus *status); void mono_image_close (MonoImage *image); void mono_image_addref (MonoImage *image); MonoAssembly* mono_image_get_assembly (MonoImage *image); guint32 mono_image_get_entry_point (MonoImage *image); const char* mono_image_get_filename (MonoImage *image); const char* mono_image_get_name (MonoImage *image); const char* mono_image_get_resource (MonoImage *image, guint32 offset, guint32 *size); gboolean mono_image_is_dynamic (MonoImage *image); MonoImage* mono_image_loaded (const char *name); gpointer mono_image_lookup_resource (MonoImage *image, guint32 res_id, guint32 lang_id, gunichar2 *name); const char * mono_image_strerror (MonoImageOpenStatus status); guint32 mono_image_strong_name_position (MonoImage *image, guint32 *size); const char* mono_image_get_public_key (MonoImage *image, guint32 *size); const char* mono_image_get_strong_name (MonoImage *image, guint32 *size); gboolean mono_image_has_authenticode_entry (MonoImage *image); int mono_image_ensure_section_idx (MonoImage *image, int section); int mono_image_ensure_section (MonoImage *image, const char *section);

Image APIs

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

Opening and closing MonoImages

mono_image_open
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
Returns
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
Prototype: mono_image_open_full

mono_image_open_from_data
Prototype: mono_image_open_from_data

mono_image_open_from_data_full
Prototype: mono_image_open_from_data_full

mono_image_close
void mono_image_close (MonoImage *image)

Parameters

image:
The image file we wish to close
Remarks

Closes an image file, deallocates all memory consumed and unmaps all possible sections of the file

mono_image_addref
void mono_image_addref (MonoImage *image)

Parameters

image:
The image file we wish to add a reference to
Remarks

Increases the reference count of an image.

mono_image_load_file_for_image
Prototype: mono_image_load_file_for_image

Image Information

mono_image_get_guid
Prototype: mono_image_get_guid

mono_image_get_assembly
MonoAssembly* mono_image_get_assembly (MonoImage *image)

Parameters

image:
the MonoImage.
Returns
the assembly that holds this image.
Remarks

Use this routine to get the assembly that owns this image.

mono_image_get_entry_point
guint32 mono_image_get_entry_point (MonoImage *image)

Parameters

image:
the image where the entry point will be looked up.
Returns
the token for the entry point method in the image
Remarks

Use this routine to determine the metadata token for method that has been flagged as the entry point.

mono_image_get_filename
const char* mono_image_get_filename (MonoImage *image)

Parameters

image:
a MonoImage
Returns
the filename.
Remarks

Used to get the filename that hold the actual MonoImage

mono_image_get_name
const char* mono_image_get_name (MonoImage *image)

Parameters

name:
a MonoImage
Returns
the name of the assembly.
mono_image_get_resource
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
Returns
the pointer to the resource whose offset is offset.
Remarks

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
Prototype: mono_image_get_table_info

mono_image_get_table_rows
Prototype: mono_image_get_table_rows

mono_image_is_dynamic
gboolean mono_image_is_dynamic (MonoImage *image)

Parameters

image:
the MonoImage
Returns
TRUE if the image was created dynamically, FALSE if not.
Remarks

Determines if the given image was created dynamically through the System.Reflection.Emit API

mono_image_loaded_by_guid
Prototype: mono_image_loaded_by_guid

mono_image_loaded
MonoImage* mono_image_loaded (const char *name)

Parameters

name:
path or assembly name of the image to load
Returns
the loaded MonoImage, or NULL on failure.
Remarks

This routine verifies that the given image is loaded. Reflection-only loads do not count.

mono_image_lookup_resource
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.
Returns
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
const char * mono_image_strerror (MonoImageOpenStatus status)

Parameters

status:
an code indicating the result from a recent operation
Returns
a string describing the error

Public Keys, Strong Names and Certificates

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

Parameters

image:
a MonoImage
size:
a guint32 pointer, or NULL.
Returns
the position within the image file where the strong name is stored.
Remarks

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
const char* mono_image_get_public_key (MonoImage *image, guint32 *size)

Parameters

image:
a MonoImage
size:
a guint32 pointer, or NULL.
Returns
NULL if the image does not have a public key, or a pointer to the public key.
Remarks

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
const char* mono_image_get_strong_name (MonoImage *image, guint32 *size)

Parameters

image:
a MonoImage
size:
a guint32 pointer, or NULL.
Returns
NULL if the image does not have a strong name, or a pointer to the public key.
Remarks

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
gboolean mono_image_has_authenticode_entry (MonoImage *image)

Parameters

image:
the MonoImage
Returns
TRUE if the image contains an authenticode entry in the PE directory.
Remarks

Use this routine to determine if the image has a Authenticode Certificate Table.

Low-level features

mono_image_rva_map
Prototype: mono_image_rva_map

mono_image_ensure_section_idx
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
Returns
TRUE on success
Remarks

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