428 lines
13 KiB
HTML
428 lines
13 KiB
HTML
<?xml version="1.0" encoding="utf-8"?><span>
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>mono-api-embedding.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>Embedding Mono</h2>
|
|
|
|
<p />The simplest way of embedding Mono is illustrated here:
|
|
<pre>
|
|
int main (int argc, char *argv)
|
|
{
|
|
/*
|
|
* Load the default Mono configuration file, this is needed
|
|
* if you are planning on using the dllmaps defined on the
|
|
* system configuration
|
|
*/
|
|
mono_config_parse (NULL);
|
|
|
|
/*
|
|
* mono_jit_init() creates a domain: each assembly is
|
|
* loaded and run in a MonoDomain.
|
|
*/
|
|
MonoDomain *domain = mono_jit_init ("startup.exe");
|
|
|
|
/*
|
|
* Optionally, add an internal call that your startup.exe
|
|
* code can call, this will bridge startup.exe to Mono
|
|
*/
|
|
mono_add_internal_call ("Sample::GetMessage", getMessage);
|
|
|
|
/*
|
|
* Open the executable, and run the Main method declared
|
|
* in the executable
|
|
*/
|
|
MonoAssembly *assembly = mono_domain_assembly_open (domain, "startup.exe");
|
|
|
|
if (!assembly)
|
|
exit (2);
|
|
/*
|
|
* mono_jit_exec() will run the Main() method in the assembly.
|
|
* The return value needs to be looked up from
|
|
* System.Environment.ExitCode.
|
|
*/
|
|
mono_jit_exec (domain, assembly, argc, argv);
|
|
}
|
|
|
|
/* The C# signature for this method is: string GetMessage () in class Sample */
|
|
MonoString*
|
|
getMessage ()
|
|
{
|
|
return mono_string_new (mono_domain_get (), "Hello, world");
|
|
}
|
|
</pre>
|
|
|
|
<a name="api:mono_jit_init"></a>
|
|
<div class="api">
|
|
<div class="api-entry">mono_jit_init</div>
|
|
|
|
<div class="prototype">Prototype: mono_jit_init</div>
|
|
<p />
|
|
|
|
</div> <a name="api:mono_jit_exec"></a>
|
|
<div class="api">
|
|
<div class="api-entry">mono_jit_exec</div>
|
|
|
|
<div class="prototype">int
|
|
mono_jit_exec (MonoDomain *domain, MonoAssembly *assembly, int argc, char *argv[])
|
|
|
|
</div>
|
|
<p />
|
|
<b>Parameters</b>
|
|
<blockquote><dt><i>assembly:</i></dt><dd> reference to an assembly</dd><dt><i>argc:</i></dt><dd> argument count</dd><dt><i>argv:</i></dt><dd> argument vector</dd></blockquote>
|
|
<b>Remarks</b>
|
|
<p />
|
|
Start execution of a program.
|
|
|
|
</div> <a name="api:mono_set_dirs"></a>
|
|
<div class="api">
|
|
<div class="api-entry">mono_set_dirs</div>
|
|
|
|
<div class="prototype">void
|
|
mono_set_dirs (const char *assembly_dir, const char *config_dir)
|
|
|
|
</div>
|
|
<p />
|
|
<b>Parameters</b>
|
|
<blockquote><dt><i>assembly_dir:</i></dt><dd> the base directory for assemblies</dd><dt><i>config_dir:</i></dt><dd> the base directory for configuration files</dd></blockquote>
|
|
<b>Remarks</b>
|
|
<p />
|
|
This routine is used internally and by developers embedding
|
|
the runtime into their own applications.
|
|
|
|
There are a number of cases to consider: Mono as a system-installed
|
|
package that is available on the location preconfigured or Mono in
|
|
a relocated location.
|
|
|
|
If you are using a system-installed Mono, you can pass NULL
|
|
to both parameters. If you are not, you should compute both
|
|
directory values and call this routine.
|
|
|
|
The values for a given PREFIX are:
|
|
|
|
assembly_dir: PREFIX/lib
|
|
config_dir: PREFIX/etc
|
|
|
|
Notice that embedders that use Mono in a relocated way must
|
|
compute the location at runtime, as they will be in control
|
|
of where Mono is installed.
|
|
|
|
</div> <a name="api:mono_main"></a>
|
|
<div class="api">
|
|
<div class="api-entry">mono_main</div>
|
|
|
|
<div class="prototype">int
|
|
mono_main (int argc, char* argv[])
|
|
|
|
</div>
|
|
<p />
|
|
<b>Parameters</b>
|
|
<blockquote><dt><i>argc:</i></dt><dd> number of arguments in the argv array</dd><dt><i>argv:</i></dt><dd> array of strings containing the startup arguments</dd></blockquote>
|
|
<b>Remarks</b>
|
|
<p />
|
|
Launches the Mono JIT engine and parses all the command line options
|
|
in the same way that the mono command line VM would.
|
|
|
|
</div> <a name="api:mono_parse_default_optimizations"></a>
|
|
<div class="api">
|
|
<div class="api-entry">mono_parse_default_optimizations</div>
|
|
|
|
<div class="prototype">Prototype: mono_parse_default_optimizations</div>
|
|
<p />
|
|
|
|
|
|
</div> <a name="api:mono_jit_cleanup"></a>
|
|
<div class="api">
|
|
<div class="api-entry">mono_jit_cleanup</div>
|
|
|
|
<div class="prototype">Prototype: mono_jit_cleanup</div>
|
|
<p />
|
|
|
|
</div> <a name="api:mono_set_defaults"></a>
|
|
<div class="api">
|
|
<div class="api-entry">mono_set_defaults</div>
|
|
|
|
<div class="prototype">Prototype: mono_set_defaults</div>
|
|
<p />
|
|
|
|
|
|
</div><h3>Internal Calls</h3>
|
|
|
|
<p />The Mono runtime provides two mechanisms to expose C code
|
|
to the CIL universe: internal calls and native C
|
|
code. Internal calls are tightly integrated with the runtime,
|
|
and have the least overhead, as they use the same data types
|
|
that the runtime uses.
|
|
|
|
<p />The other option is to use the Platform Invoke (P/Invoke)
|
|
to call C code from the CIL universe, using the standard
|
|
<a href="http://www.mono-project.com/Interop_with_Native_Libraries">P/Invoke</a>
|
|
mechanisms.
|
|
|
|
<p />To register an internal call, use this call you use the
|
|
<a href="#api:mono_add_internal_call"><tt>mono_add_internal_call</tt>
|
|
routine.
|
|
|
|
<a name="api:mono_add_internal_call"></a>
|
|
<div class="api">
|
|
<div class="api-entry">mono_add_internal_call</div>
|
|
|
|
<div class="prototype">Prototype: mono_add_internal_call</div>
|
|
<p />
|
|
|
|
|
|
</div><h3>P/Invoke with embedded applications</h3>
|
|
|
|
<p />Unlike internal calls, Platform/Invoke is easier to use and
|
|
more portable. It allows you to share code with Windows and
|
|
.NET that have a different setup for internal calls to their
|
|
own runtime.
|
|
|
|
<p />Usually P/Invoke declarations reference external libraries
|
|
like:
|
|
|
|
<pre>
|
|
[DllImport ("opengl")]
|
|
void glBegin (GLEnum mode)
|
|
</pre>
|
|
|
|
<p />Mono extends P/Invoke to support looking up symbols not in
|
|
an external library, but looking up those symbols into the
|
|
same address space as your program, to do this, use the
|
|
special library name "__Internal". This will direct Mono to
|
|
lookup the method in your own process.
|
|
|
|
<p />There are situations where the host operating system does
|
|
not support looking up symbols on the process address space.
|
|
For situations like this you can use
|
|
the <a href="#api:mono_dl_register_library">mono_dl_register_library</a>.
|
|
|
|
<h4><a name="api:mono_dl_register_library">mono_dl_register_library</a></h4>
|
|
|
|
<h3>Data Marshalling</h3>
|
|
|
|
<p />Managed objects are represented as <tt>MonoObject*</tt>
|
|
types. Those objects that the runtime consumes directly have
|
|
more specific C definitions (for example strings are of type
|
|
<tt>MonoString *</tt>, delegates are of type
|
|
<tt>MonoDelegate*</tt> but they are still <tt>MonoObject
|
|
*</tt>s).
|
|
|
|
<p />As of Mono 1.2.x types defined in mscorlib.dll do not have
|
|
their fields reordered in any way. But other libraries might
|
|
have their fields reordered. In these cases, Managed
|
|
structures and objects have the same layout in the C# code as
|
|
they do in the unmanaged world.
|
|
|
|
<p />Structures defined outside corlib must have a specific
|
|
StructLayout definition, and have it set as sequential if you
|
|
plan on accessing these fields directly from C code.
|
|
|
|
<p /><b>Important</b> Internal calls do not provide support for
|
|
marshalling structures. This means that any API calls that
|
|
take a structure (excluding the system types like int32,
|
|
int64, etc) must be passed as a pointer, in C# this means
|
|
passing the value as a "ref" or "out" parameter.
|
|
|
|
<h3>Mono Runtime Configuration</h3>
|
|
|
|
<p />Certain features of the Mono runtime, like DLL mapping, are
|
|
available through a configuration file that is loaded at
|
|
runtime. The default Mono implementation loads the
|
|
configuration file from <tt>$sysconfig/mono/config</tt>
|
|
(typically this is <tt>/etc/mono/config</tt>).
|
|
|
|
<p />See the <tt>mono-config(5)</tt> man page for more details
|
|
on what goes in this file.
|
|
|
|
<p />The following APIs expose this functionality:
|
|
|
|
<a name="api:mono_config_parse"></a>
|
|
<div class="api">
|
|
<div class="api-entry">mono_config_parse</div>
|
|
|
|
<div class="prototype">void
|
|
mono_config_parse (const char *filename)
|
|
</div>
|
|
<p />
|
|
<b>Parameters</b>
|
|
<blockquote><dt><i>filename:</i></dt><dd> the filename to load the configuration variables from.</dd></blockquote>
|
|
<b>Remarks</b>
|
|
<p />
|
|
Pass a NULL filename to parse the default config files
|
|
(or the file in the MONO_CONFIG env var).
|
|
|
|
</div> <a name="api:mono_config_parse_memory"></a>
|
|
<div class="api">
|
|
<div class="api-entry">mono_config_parse_memory</div>
|
|
|
|
<div class="prototype">void
|
|
mono_config_parse_memory (const char *buffer)
|
|
|
|
</div>
|
|
<p />
|
|
<b>Parameters</b>
|
|
<blockquote><dt><i>buffer:</i></dt><dd> a pointer to an string XML representation of the configuration</dd></blockquote>
|
|
<b>Remarks</b>
|
|
<p />
|
|
Parses the configuration from a buffer
|
|
|
|
</div> <a name="api:mono_get_config_dir"></a>
|
|
<div class="api">
|
|
<div class="api-entry">mono_get_config_dir</div>
|
|
|
|
<div class="prototype">Prototype: mono_get_config_dir</div>
|
|
<p />
|
|
|
|
|
|
</div><h3>Function Pointers</h3>
|
|
|
|
<p />To wrap a function pointer into something that the Mono
|
|
runtime can consume, you should use the mono_create_ftnptr.
|
|
This is only important if you plan on running on the IA64
|
|
architecture. Otherwise you can just use the function
|
|
pointer address.
|
|
|
|
<a name="api:mono_create_ftnptr"></a>
|
|
<div class="api">
|
|
<div class="api-entry">mono_create_ftnptr</div>
|
|
|
|
<div class="prototype">Prototype: mono_create_ftnptr</div>
|
|
<p />
|
|
|
|
|
|
</div><h3>Advanced Execution Setups</h3>
|
|
|
|
<p />These are not recommended ways of initializing Mono, they
|
|
are done internally by mono_jit_init, but are here to explain
|
|
what happens internally.
|
|
|
|
<a name="api:mono_runtime_exec_managed_code"></a>
|
|
<div class="api">
|
|
<div class="api-entry">mono_runtime_exec_managed_code</div>
|
|
|
|
<div class="prototype">void
|
|
mono_runtime_exec_managed_code (MonoDomain *domain,
|
|
MonoMainThreadFunc main_func,
|
|
gpointer main_args)
|
|
|
|
</div>
|
|
<p />
|
|
<b>Parameters</b>
|
|
<blockquote><dt><i>domain:</i></dt><dd> Application domain</dd><dt><i>main_func:</i></dt><dd> function to invoke from the execution thread</dd><dt><i>main_args:</i></dt><dd> parameter to the main_func</dd></blockquote>
|
|
<b>Remarks</b>
|
|
<p />
|
|
Launch a new thread to execute a function
|
|
|
|
main_func is called back from the thread with main_args as the
|
|
parameter. The callback function is expected to start Main()
|
|
eventually. This function then waits for all managed threads to
|
|
finish.
|
|
It is not necesseray anymore to execute managed code in a subthread,
|
|
so this function should not be used anymore by default: just
|
|
execute the code and then call mono_thread_manage ().
|
|
|
|
</div> <a name="api:mono_runtime_exec_main"></a>
|
|
<div class="api">
|
|
<div class="api-entry">mono_runtime_exec_main</div>
|
|
|
|
<div class="prototype">Prototype: mono_runtime_exec_main</div>
|
|
<p />
|
|
|
|
</div> <a name="api:mono_init_from_assembly"></a>
|
|
<div class="api">
|
|
<div class="api-entry">mono_init_from_assembly</div>
|
|
|
|
<div class="prototype">MonoDomain*
|
|
mono_init_from_assembly (const char *domain_name, const char *filename)
|
|
|
|
</div>
|
|
<p />
|
|
<b>Parameters</b>
|
|
<blockquote><dt><i>domain_name:</i></dt><dd> name to give to the initial domain</dd><dt><i>filename:</i></dt><dd> filename to load on startup</dd></blockquote>
|
|
<b>Returns</b>
|
|
<blockquote> the initial domain.
|
|
</blockquote>
|
|
<b>Remarks</b>
|
|
<p />
|
|
Used by the runtime, users should use mono_jit_init instead.
|
|
|
|
Creates the initial application domain and initializes the mono_defaults
|
|
structure.
|
|
This function is guaranteed to not run any IL code.
|
|
The runtime is initialized using the runtime version required by the
|
|
provided executable. The version is determined by looking at the exe
|
|
configuration file and the version PE field)
|
|
|
|
|
|
</div> <a name="api:mono_init"></a>
|
|
<div class="api">
|
|
<div class="api-entry">mono_init</div>
|
|
|
|
<div class="prototype">MonoDomain*
|
|
mono_init (const char *domain_name)
|
|
|
|
</div>
|
|
<p />
|
|
<b>Returns</b>
|
|
<blockquote> the initial domain.
|
|
</blockquote>
|
|
<b>Remarks</b>
|
|
<p /> <p />
|
|
|
|
Creates the initial application domain and initializes the mono_defaults
|
|
structure.
|
|
This function is guaranteed to not run any IL code.
|
|
The runtime is initialized using the default runtime version.
|
|
|
|
|
|
</div></a></body>
|
|
</html>
|
|
</span> |