docs/sources/mono-api-embedding.html

   1 <h2>Embedding Mono</h2>
   2
   3         <p>The simplest way of embedding Mono is illustrated here:
   4 <pre>
   5 int main (int argc, char *argv)
   6 {
   7         /*
   8          * Load the default Mono configuration file, this is needed
   9          * if you are planning on using the dllmaps defined on the
  10          * system configuration
  11          */
  12         mono_config_parse (NULL);
  13
  14         /*
  15          * mono_jit_init() creates a domain: each assembly is
  16          * loaded and run in a MonoDomain.
  17          */
  18         MonoDomain *domain = mono_jit_init ("startup.exe");
  19
  20         /*
  21          * Optionally, add an internal call that your startup.exe
  22          * code can call, this will bridge startup.exe to Mono
  23          */
  24         mono_add_internal_call ("Sample::GetMessage", getMessage);
  25
  26         /*
  27          * Open the executable, and run the Main method declared
  28          * in the executable
  29          */
  30         MonoAssembly *assembly = mono_domain_assembly_open (domain, "startup.exe");
  31
  32         if (!assembly)
  33                 exit (2);
  34         /*
  35          * mono_jit_exec() will run the Main() method in the assembly.
  36          * The return value needs to be looked up from
  37          * System.Environment.ExitCode.
  38          */
  39         mono_jit_exec (domain, assembly, argc, argv);
  40 }
  41
  42 /* The C# signature for this method is: string GetMessage () in class Sample */
  43 MonoString*
  44 getMessage ()
  45 {
  46         return mono_string_new (mono_domain_get (), "Hello, world");
  47 }
  48 </pre>
  49
  50 <h4><a name="api:mono_jit_init">mono_jit_init</a></h4>
  51 <h4><a name="api:mono_jit_exec">mono_jit_exec</a></h4>
  52 <h4><a name="api:mono_set_dirs">mono_set_dirs</a></h4>
  53 <h4><a name="api:mono_main">mono_main</a></h4>
  54 <h4><a name="api:mono_parse_default_optimizations">mono_parse_default_optimizations</a></h4>
  55
  56 <h4><a name="api:mono_jit_cleanup">mono_jit_cleanup</a></h4>
  57 <h4><a name="api:mono_set_defaults">mono_set_defaults</a></h4>
  58
  59 <h3>Internal Calls</h3>
  60
  61         <p>The Mono runtime provides two mechanisms to expose C code
  62         to the CIL universe: internal calls and native C
  63         code. Internal calls are tightly integrated with the runtime,
  64         and have the least overhead, as they use the same data types
  65         that the runtime uses.
  66
  67         <p>The other option is to use the Platform Invoke (P/Invoke)
  68         to call C code from the CIL universe, using the standard
  69         <a href="http://www.mono-project.com/Interop_with_Native_Libraries">P/Invoke</a>
  70         mechanisms.
  71
  72         <p>To register an internal call, use this call you use the
  73         <a href="#api:mono_add_internal_call"><tt>mono_add_internal_call</tt>
  74         routine.
  75
  76 <h4><a name="api:mono_add_internal_call">mono_add_internal_call</a></h4>
  77
  78 <h3>P/Invoke with embedded applications</h3>
  79
  80         <p>Unlike internal calls, Platform/Invoke is easier to use and
  81         more portable.  It allows you to share code with Windows and
  82         .NET that have a different setup for internal calls to their
  83         own runtime.
  84
  85         <p>Usually P/Invoke declarations reference external libraries
  86         like:
  87
  88         <pre>
  89         [DllImport ("opengl")]
  90         void glBegin (GLEnum mode)
  91         </pre>
  92
  93         <p>Mono extends P/Invoke to support looking up symbols not in
  94         an external library, but looking up those symbols into the
  95         same address space as your program, to do this, use the
  96         special library name "__Internal".   This will direct Mono to
  97         lookup the method in your own process.
  98
  99         <p>There are situations where the host operating system does
 100         not support looking up symbols on the process address space.
 101         For situations like this you can use
 102         the <a href="#api:mono_dl_register_library">mono_dl_register_library</a>.
 103
 104 <h4><a name="api:mono_dl_register_library">mono_dl_register_library</h4>
 105
 106 <h3>Data Marshalling</h3>
 107
 108         <p>Managed objects are represented as <tt>MonoObject*</tt>
 109         types.  Those objects that the runtime consumes directly have
 110         more specific C definitions (for example strings are of type
 111         <tt>MonoString *</tt>, delegates are of type
 112         <tt>MonoDelegate*</tt> but they are still <tt>MonoObject
 113         *</tt>s).
 114
 115         <p>As of Mono 1.2.x types defined in mscorlib.dll do not have
 116         their fields reordered in any way.   But other libraries might
 117         have their fields reordered.   In these cases, Managed
 118         structures and objects have the same layout in the C# code as
 119         they do in the unmanaged world.
 120
 121         <p>Structures defined outside corlib must have a specific
 122         StructLayout definition, and have it set as sequential if you
 123         plan on accessing these fields directly from C code.
 124
 125         <p><b>Important</B> Internal calls do not provide support for
 126         marshalling structures.  This means that any API calls that
 127         take a structure (excluding the system types like int32,
 128         int64, etc) must be passed as a pointer, in C# this means
 129         passing the value as a "ref" or "out" parameter.
 130
 131 <h3>Mono Runtime Configuration</h3>
 132
 133         <p>Certain features of the Mono runtime, like DLL mapping, are
 134         available through a configuration file that is loaded at
 135         runtime.   The default Mono implementation loads the
 136         configuration file from <tt>$sysconfig/mono/config</tt>
 137         (typically this is <tt>/etc/mono/config</tt>).
 138
 139         <p>See the <tt>mono-config(5)</tt> man page for more details
 140         on what goes in this file.
 141
 142         <p>The following APIs expose this functionality:
 143
 144 <h4><a name="api:mono_config_parse">mono_config_parse</a></h4>
 145 <h4><a name="api:mono_config_parse_memory">mono_config_parse_memory</a></h4>
 146 <h4><a name="api:mono_get_config_dir">mono_get_config_dir</a></h4>
 147
 148 <h3>Function Pointers</h3>
 149
 150         <p>To wrap a function pointer into something that the Mono
 151         runtime can consume, you should use the mono_create_ftnptr.
 152         This is only important if you plan on running on the IA64
 153         architecture.   Otherwise you can just use the function
 154         pointer address.
 155
 156 <h4><a name="api:mono_create_ftnptr">mono_create_ftnptr</a></h4>
 157
 158 <h3>Advanced Execution Setups</h3>
 159
 160         <p>These are not recommended ways of initializing Mono, they
 161         are done internally by mono_jit_init, but are here to explain
 162         what happens internally.
 163
 164 <h4><a name="api:mono_runtime_exec_managed_code">mono_runtime_exec_managed_code</a></h4>
 165 <h4><a name="api:mono_runtime_exec_main">mono_runtime_exec_main</a></h4>
 166 <h4><a name="api:mono_init_from_assembly">mono_init_from_assembly</a></h4>
 167 <h4><a name="api:mono_init">mono_init</a></h4>
 168 <h4><a name="api:mono_init_version">mono_init_version</a></h4>