517 lines
17 KiB
HTML
517 lines
17 KiB
HTML
<?xml version="1.0" encoding="us-ascii"?><span>
|
|
<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>
|
|
<blockquote><dt><i>name:</i></dt><dd> name of the image to load</dd></blockquote>
|
|
<b>Returns</b>
|
|
<blockquote> the loaded MonoImage, or NULL on failure.
|
|
</blockquote>
|
|
<b>Remarks</b>
|
|
<p />
|
|
This routine ensures that the given image is loaded.
|
|
|
|
|
|
</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> |