2016-01-18 21:29:19 -05:00
<?xml version="1.0" encoding="utf-8"?> < span >
2015-04-26 19:10:23 +01:00
< html xmlns = "http://www.w3.org/1999/xhtml" >
< head >
< title > mono-api-image.html< / title >
< style type = "text/css" >
h3 {
font-size: 18px;
padding-bottom: 4pt;
border-bottom: 2px solid #dddddd;
}
.api {
border: 1px solid;
padding: 10pt;
margin: 10pt;
}
.api-entry {
border-bottom: none;
font-size: 18px;
}
.prototype {
border: 1px solid;
background-color: #f2f2f2;
padding: 5pt;
margin-top: 5pt;
margin-bottom: 5pt;
}
.header {
border: 1px solid;
padding: 0 0 5pt 5pt;
margin: 10pt;
white-space: pre;
font-family: monospace;
}
.code {
border: 1px solid;
padding: 0 0 5pt 5pt;
margin: 10pt;
white-space: pre;
font-family: monospace;
}
< / style >
< / head >
< body >
< h2 > Image Manipulation< / h2 >
< p / > Images are the component of assemblies that actually hold
the CIL code and < a href = "mono-api-metadata.html" > metadata< / a >
in the extended PE/COFF file.
< h3 > Synopsis< / h3 >
< div class = "header" >
#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* < a href = "#api:mono_image_open" > mono_image_open< / a > (const char *fname,
MonoImageOpenStatus *status);
< a href = "#api:mono_image_open_full" > < / a >
< a href = "#api:mono_image_open_from_data" > < / a >
< a href = "#api:mono_image_open_from_data_full" > < / a >
void < a href = "#api:mono_image_close" > mono_image_close< / a > (MonoImage *image);
void < a href = "#api:mono_image_addref" > mono_image_addref< / a > (MonoImage *image);
< a href = "#api:mono_image_load_file_for_image" > < / a >
< a href = "#api:mono_image_get_guid" > < / a >
MonoAssembly* < a href = "#api:mono_image_get_assembly" > mono_image_get_assembly< / a > (MonoImage *image);
guint32 < a href = "#api:mono_image_get_entry_point" > mono_image_get_entry_point< / a > (MonoImage *image);
const char* < a href = "#api:mono_image_get_filename" > mono_image_get_filename< / a > (MonoImage *image);
const char* < a href = "#api:mono_image_get_name" > mono_image_get_name< / a > (MonoImage *image);
const char* < a href = "#api:mono_image_get_resource" > mono_image_get_resource< / a > (MonoImage *image,
guint32 offset,
guint32 *size);
< a href = "#api:mono_image_get_table_info" > < / a >
< a href = "#api:mono_image_get_table_rows" > < / a >
gboolean < a href = "#api:mono_image_is_dynamic" > mono_image_is_dynamic< / a > (MonoImage *image);
< a href = "#api:mono_image_loaded_by_guid" > < / a >
MonoImage* < a href = "#api:mono_image_loaded" > mono_image_loaded< / a > (const char *name);
gpointer < a href = "#api:mono_image_lookup_resource" > mono_image_lookup_resource< / a > (MonoImage *image,
guint32 res_id,
guint32 lang_id,
gunichar2 *name);
const char * < a href = "#api:mono_image_strerror" > mono_image_strerror< / a > (MonoImageOpenStatus status);
guint32 < a href = "#api:mono_image_strong_name_position" > mono_image_strong_name_position< / a > (MonoImage *image,
guint32 *size);
const char* < a href = "#api:mono_image_get_public_key" > mono_image_get_public_key< / a > (MonoImage *image,
guint32 *size);
const char* < a href = "#api:mono_image_get_strong_name" > mono_image_get_strong_name< / a > (MonoImage *image,
guint32 *size);
gboolean < a href = "#api:mono_image_has_authenticode_entry" > mono_image_has_authenticode_entry< / a > (MonoImage *image);
< a href = "#api:mono_image_rva_map" > < / a >
int < a href = "#api:mono_image_ensure_section_idx" > mono_image_ensure_section_idx< / a > (MonoImage *image,
int section);
int < a href = "#api:mono_image_ensure_section" > mono_image_ensure_section< / a > (MonoImage *image,
const char *section);
< / div >
< h3 > Image APIs< / h3 >
< p / > Images are the actual elements in the runtime that contain
the actual code being executed.
< a name = "cil_image_open" > < / a >
< h3 > Opening and closing MonoImages< / h3 >
< a name = "api:mono_image_open" > < / a >
< div class = "api" >
< div class = "api-entry" > mono_image_open< / div >
< div class = "prototype" > MonoImage*
mono_image_open (const char *fname, MonoImageOpenStatus *status)
< / div >
< p / >
< b > Parameters< / b >
< blockquote > < dt > < i > fname:< / i > < / dt > < dd > filename that points to the module we want to open< / dd > < dt > < i > status:< / i > < / dt > < dd > An error condition is returned in this field< / dd > < / blockquote >
< b > Returns< / b >
< blockquote > 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 < i > status< / i > for details on the error< / blockquote >
< / div > < a name = "api:mono_image_open_full" > < / a >
< div class = "api" >
< div class = "api-entry" > mono_image_open_full< / div >
< div class = "prototype" > Prototype: mono_image_open_full< / div >
< p / >
< / div > < a name = "api:mono_image_open_from_data" > < / a >
< div class = "api" >
< div class = "api-entry" > mono_image_open_from_data< / div >
< div class = "prototype" > Prototype: mono_image_open_from_data< / div >
< p / >
< / div > < a name = "api:mono_image_open_from_data_full" > < / a >
< div class = "api" >
< div class = "api-entry" > mono_image_open_from_data_full< / div >
< div class = "prototype" > Prototype: mono_image_open_from_data_full< / div >
< p / >
< / div > < a name = "api:mono_image_close" > < / a >
< div class = "api" >
< div class = "api-entry" > mono_image_close< / div >
< div class = "prototype" > void
mono_image_close (MonoImage *image)
< / div >
< p / >
< b > Parameters< / b >
< blockquote > < dt > < i > image:< / i > < / dt > < dd > The image file we wish to close< / dd > < / blockquote >
< b > Remarks< / b >
< p / >
Closes an image file, deallocates all memory consumed and
unmaps all possible sections of the file
< / div > < a name = "api:mono_image_addref" > < / a >
< div class = "api" >
< div class = "api-entry" > mono_image_addref< / div >
< div class = "prototype" > void
mono_image_addref (MonoImage *image)
< / div >
< p / >
< b > Parameters< / b >
< blockquote > < dt > < i > image:< / i > < / dt > < dd > The image file we wish to add a reference to< / dd > < / blockquote >
< b > Remarks< / b >
< p / >
Increases the reference count of an image.
< / div > < a name = "api:mono_image_load_file_for_image" > < / a >
< div class = "api" >
< div class = "api-entry" > mono_image_load_file_for_image< / div >
< div class = "prototype" > Prototype: mono_image_load_file_for_image< / div >
< p / >
< / div > < h3 > Image Information< / h3 >
< a name = "api:mono_image_get_guid" > < / a >
< div class = "api" >
< div class = "api-entry" > mono_image_get_guid< / div >
< div class = "prototype" > Prototype: mono_image_get_guid< / div >
< p / >
< / div > < a name = "api:mono_image_get_assembly" > < / a >
< div class = "api" >
< div class = "api-entry" > mono_image_get_assembly< / div >
< div class = "prototype" > MonoAssembly*
mono_image_get_assembly (MonoImage *image)
< / div >
< p / >
< b > Parameters< / b >
< blockquote > < dt > < i > image:< / i > < / dt > < dd > the MonoImage.< / dd > < / blockquote >
< b > Returns< / b >
< blockquote > the assembly that holds this image.
< / blockquote >
< b > Remarks< / b >
< p / >
Use this routine to get the assembly that owns this image.
< / div > < a name = "api:mono_image_get_entry_point" > < / a >
< div class = "api" >
< div class = "api-entry" > mono_image_get_entry_point< / div >
< div class = "prototype" > guint32
mono_image_get_entry_point (MonoImage *image)
< / div >
< p / >
< b > Parameters< / b >
< blockquote > < dt > < i > image:< / i > < / dt > < dd > the image where the entry point will be looked up.< / dd > < / blockquote >
< b > Returns< / b >
< blockquote > the token for the entry point method in the image
< / blockquote >
< b > Remarks< / b >
< p / >
Use this routine to determine the metadata token for method that
has been flagged as the entry point.
< / div > < a name = "api:mono_image_get_filename" > < / a >
< div class = "api" >
< div class = "api-entry" > mono_image_get_filename< / div >
< div class = "prototype" > const char*
mono_image_get_filename (MonoImage *image)
< / div >
< p / >
< b > Parameters< / b >
< blockquote > < dt > < i > image:< / i > < / dt > < dd > a MonoImage< / dd > < / blockquote >
< b > Returns< / b >
< blockquote > the filename.
< / blockquote >
< b > Remarks< / b >
< p / >
Used to get the filename that hold the actual MonoImage
< / div > < a name = "api:mono_image_get_name" > < / a >
< div class = "api" >
< div class = "api-entry" > mono_image_get_name< / div >
< div class = "prototype" > const char*
mono_image_get_name (MonoImage *image)
< / div >
< p / >
< b > Parameters< / b >
< blockquote > < dt > < i > name:< / i > < / dt > < dd > a MonoImage< / dd > < / blockquote >
< b > Returns< / b >
< blockquote > the name of the assembly.
< / blockquote >
< / div > < a name = "api:mono_image_get_resource" > < / a >
< div class = "api" >
< div class = "api-entry" > mono_image_get_resource< / div >
< div class = "prototype" > const char*
mono_image_get_resource (MonoImage *image, guint32 offset, guint32 *size)
< / div >
< p / >
< b > Parameters< / b >
< blockquote > < dt > < i > image:< / i > < / dt > < dd > the image where the resource will be looked up.< / dd > < dt > < i > offset:< / i > < / dt > < dd > The offset to add to the resource< / dd > < dt > < i > size:< / i > < / dt > < dd > a pointer to an int where the size of the resource will be stored< / dd > < / blockquote >
< b > Returns< / b >
< blockquote > the pointer to the resource whose offset is < i > offset< / i > .
< / blockquote >
< b > Remarks< / b >
< p / >
This is a low-level routine that fetches a resource from the
metadata that starts at a given < i > offset< / i > . The < i > size< / i > parameter is
filled with the data field as encoded in the metadata.
< / div > < a name = "api:mono_image_get_table_info" > < / a >
< div class = "api" >
< div class = "api-entry" > mono_image_get_table_info< / div >
< div class = "prototype" > Prototype: mono_image_get_table_info< / div >
< p / >
< / div > < a name = "api:mono_image_get_table_rows" > < / a >
< div class = "api" >
< div class = "api-entry" > mono_image_get_table_rows< / div >
< div class = "prototype" > Prototype: mono_image_get_table_rows< / div >
< p / >
< / div > < a name = "api:mono_image_is_dynamic" > < / a >
< div class = "api" >
< div class = "api-entry" > mono_image_is_dynamic< / div >
< div class = "prototype" > gboolean
mono_image_is_dynamic (MonoImage *image)
< / div >
< p / >
< b > Parameters< / b >
< blockquote > < dt > < i > image:< / i > < / dt > < dd > the MonoImage< / dd > < / blockquote >
< b > Returns< / b >
< blockquote > TRUE if the image was created dynamically, FALSE if not.
< / blockquote >
< b > Remarks< / b >
< p / >
Determines if the given image was created dynamically through the
System.Reflection.Emit API
< / div > < a name = "api:mono_image_loaded_by_guid" > < / a >
< div class = "api" >
< div class = "api-entry" > mono_image_loaded_by_guid< / div >
< div class = "prototype" > Prototype: mono_image_loaded_by_guid< / div >
< p / >
< / div > < a name = "api:mono_image_loaded" > < / a >
< div class = "api" >
< div class = "api-entry" > mono_image_loaded< / div >
< div class = "prototype" > MonoImage*
mono_image_loaded (const char *name)
< / div >
< p / >
< b > Parameters< / b >
2016-02-22 11:00:01 -05:00
< blockquote > < dt > < i > name:< / i > < / dt > < dd > path or assembly name of the image to load< / dd > < / blockquote >
2015-04-26 19:10:23 +01:00
< b > Returns< / b >
< blockquote > the loaded MonoImage, or NULL on failure.
< / blockquote >
< b > Remarks< / b >
< p / >
2016-02-22 11:00:01 -05:00
This routine verifies that the given image is loaded. Reflection-only loads do not count.
2015-04-26 19:10:23 +01:00
< / div > < a name = "api:mono_image_lookup_resource" > < / a >
< div class = "api" >
< div class = "api-entry" > mono_image_lookup_resource< / div >
< div class = "prototype" > gpointer
mono_image_lookup_resource (MonoImage *image, guint32 res_id, guint32 lang_id, gunichar2 *name)
< / div >
< p / >
< b > Parameters< / b >
< blockquote > < dt > < i > image:< / i > < / dt > < dd > the image to look up the resource in< / dd > < dt > < i > res_id:< / i > < / dt > < dd > A MONO_PE_RESOURCE_ID_ that represents the resource ID to lookup.< / dd > < dt > < i > lang_id:< / i > < / dt > < dd > The language id.< / dd > < dt > < i > name:< / i > < / dt > < dd > the resource name to lookup.< / dd > < / blockquote >
< b > Returns< / b >
< blockquote > 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.< / blockquote >
< / div > < a name = "api:mono_image_strerror" > < / a >
< div class = "api" >
< div class = "api-entry" > mono_image_strerror< / div >
< div class = "prototype" > const char *
mono_image_strerror (MonoImageOpenStatus status)
< / div >
< p / >
< b > Parameters< / b >
< blockquote > < dt > < i > status:< / i > < / dt > < dd > an code indicating the result from a recent operation< / dd > < / blockquote >
< b > Returns< / b >
< blockquote > a string describing the error
< / blockquote >
< / div > < h3 > Public Keys, Strong Names and Certificates< / h3 >
< a name = "api:mono_image_strong_name_position" > < / a >
< div class = "api" >
< div class = "api-entry" > mono_image_strong_name_position< / div >
< div class = "prototype" > guint32
mono_image_strong_name_position (MonoImage *image, guint32 *size)
< / div >
< p / >
< b > Parameters< / b >
< blockquote > < dt > < i > image:< / i > < / dt > < dd > a MonoImage< / dd > < dt > < i > size:< / i > < / dt > < dd > a guint32 pointer, or NULL.< / dd > < / blockquote >
< b > Returns< / b >
< blockquote > the position within the image file where the strong name
is stored.< / blockquote >
< b > Remarks< / b >
< p / >
If the image has a strong name, and < i > size< / i > is not NULL, the value
pointed to by size will have the size of the strong name.
< / div > < a name = "api:mono_image_get_public_key" > < / a >
< div class = "api" >
< div class = "api-entry" > mono_image_get_public_key< / div >
< div class = "prototype" > const char*
mono_image_get_public_key (MonoImage *image, guint32 *size)
< / div >
< p / >
< b > Parameters< / b >
< blockquote > < dt > < i > image:< / i > < / dt > < dd > a MonoImage< / dd > < dt > < i > size:< / i > < / dt > < dd > a guint32 pointer, or NULL.< / dd > < / blockquote >
< b > Returns< / b >
< blockquote > NULL if the image does not have a public key, or a pointer
to the public key.< / blockquote >
< b > Remarks< / b >
< p / >
This is used to obtain the public key in the < i > image< / i > .
< p / >
If the image has a public key, and < i > size< / i > is not NULL, the value
pointed to by size will have the size of the public key.
< p / >
< / div > < a name = "api:mono_image_get_strong_name" > < / a >
< div class = "api" >
< div class = "api-entry" > mono_image_get_strong_name< / div >
< div class = "prototype" > const char*
mono_image_get_strong_name (MonoImage *image, guint32 *size)
< / div >
< p / >
< b > Parameters< / b >
< blockquote > < dt > < i > image:< / i > < / dt > < dd > a MonoImage< / dd > < dt > < i > size:< / i > < / dt > < dd > a guint32 pointer, or NULL.< / dd > < / blockquote >
< b > Returns< / b >
< blockquote > NULL if the image does not have a strong name, or a
pointer to the public key.< / blockquote >
< b > Remarks< / b >
< p / >
If the image has a strong name, and < i > size< / i > is not NULL, the value
pointed to by size will have the size of the strong name.
< / div > < a name = "api:mono_image_has_authenticode_entry" > < / a >
< div class = "api" >
< div class = "api-entry" > mono_image_has_authenticode_entry< / div >
< div class = "prototype" > gboolean
mono_image_has_authenticode_entry (MonoImage *image)
< / div >
< p / >
< b > Parameters< / b >
< blockquote > < dt > < i > image:< / i > < / dt > < dd > the MonoImage< / dd > < / blockquote >
< b > Returns< / b >
< blockquote > TRUE if the image contains an authenticode entry in the PE
directory.< / blockquote >
< b > Remarks< / b >
< p / >
Use this routine to determine if the image has a Authenticode
Certificate Table.
< / div > < h3 > Low-level features< / h3 >
< a name = "api:mono_image_rva_map" > < / a >
< div class = "api" >
< div class = "api-entry" > mono_image_rva_map< / div >
< div class = "prototype" > Prototype: mono_image_rva_map< / div >
< p / >
< / div > < a name = "api:mono_image_ensure_section_idx" > < / a >
< div class = "api" >
< div class = "api-entry" > mono_image_ensure_section_idx< / div >
< div class = "prototype" > int
mono_image_ensure_section_idx (MonoImage *image, int section)
< / div >
< p / >
< b > Parameters< / b >
< blockquote > < dt > < i > image:< / i > < / dt > < dd > The image we are operating on< / dd > < dt > < i > section:< / i > < / dt > < dd > section number that we will load/map into memory< / dd > < / blockquote >
< b > Returns< / b >
< blockquote > TRUE on success
< / blockquote >
< b > Remarks< / b >
< p / >
This routine makes sure that we have an in-memory copy of
an image section (.text, .rsrc, .data).
< / div > < / body >
< / html >
< / span >
