You've already forked linux-packaging-mono
Imported Upstream version 4.0.1
Former-commit-id: 6d37e02debfe41dd5c13ba6f6a2428c8b1ff5e28
This commit is contained in:
Jo Shields
428
docs/deploy/mono-api-embedding.html
Normal file
428
docs/deploy/mono-api-embedding.html
Normal file
@ -0,0 +1,428 @@
|
||||
<?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>
|
||||
Reference in New Issue
Block a user