nethost_sys/lib.rs
1#![no_std]
2#![warn(clippy::pedantic, clippy::cargo, unsafe_op_in_unsafe_fn)]
3#![allow(
4 clippy::missing_safety_doc,
5 clippy::missing_errors_doc,
6 clippy::missing_panics_doc,
7 clippy::module_name_repetitions,
8 clippy::multiple_crate_versions,
9 clippy::doc_markdown,
10 non_camel_case_types,
11 dead_code
12)]
13
14//! FFI bindings for [nethost](https://github.com/dotnet/runtime/blob/main/docs/design/features/host-components.md#components-of-the-hosting).
15//!
16//! Supports automatically downloading the latest version of the [nethost](https://github.com/dotnet/runtime/blob/main/docs/design/features/host-components.md#components-of-the-hosting) library from [NuGet](https://www.nuget.org/packages/Microsoft.NETCore.DotNetHost/) with the `download-nuget` feature.
17//!
18//! ## Related crates
19//! - [hostfxr-sys](https://crates.io/crates/hostfxr-sys) - bindings for the hostfxr library.
20//! - [coreclr-hosting-shared](https://crates.io/crates/coreclr-hosting-shared) - shared bindings between this crate and [hostfxr-sys](https://crates.io/crates/hostfxr-sys).
21//! - [netcorehost](https://crates.io/crates/netcorehost) - rusty wrapper over the nethost and hostfxr libraries.
22//!
23//! ## Additional Information
24//! - [Hosting layer APIs](https://github.com/dotnet/core-setup/blob/master/Documentation/design-docs/hosting-layer-apis.md)
25//! - [Native hosting](https://github.com/dotnet/core-setup/blob/master/Documentation/design-docs/native-hosting.md#runtime-properties)
26//! - [Write a custom .NET Core host to control the .NET runtime from your native code](https://docs.microsoft.com/en-us/dotnet/core/tutorials/netcore-hosting)
27//!
28//! ## License
29//! Licensed under the MIT license ([LICENSE](https://github.com/OpenByteDev/nethost-sys/blob/master/LICENSE) or <http://opensource.org/licenses/MIT>)
30
31use core::{mem, ptr};
32use coreclr_hosting_shared::{char_t, size_t};
33
34// for some reason we need the link attribute here for unix, but the rustc argument in build.rs for windows.
35// #[cfg_attr(windows, link(name = "libnethost"))]
36#[cfg_attr(unix, link(name = "nethost", kind = "static"))]
37#[cfg_attr(
38 all(unix, not(target_os = "macos")),
39 link(name = "stdc++", kind = "dylib")
40)]
41#[cfg_attr(target_os = "macos", link(name = "c++", kind = "dylib"))]
42extern "system" {
43 /// Get the path to the `hostfxr` library.
44 ///
45 /// # Arguments
46 /// * `buffer`:
47 /// Buffer that will be populated with the hostfxr path, including a null terminator.
48 /// * `buffer_size`:
49 /// * \[in\] Size of buffer in [`char_t`] units.
50 /// * \[out\] Size of buffer used in [`char_t`] units. If the input value is too small
51 /// or `buffer` is [`null`](core::ptr::null()), this is populated with the minimum required size
52 /// in [`char_t`] units for a buffer to hold the hostfxr path
53 ///
54 /// * `get_hostfxr_parameters`:
55 /// Optional. Parameters that modify the behaviour for locating the hostfxr library.
56 /// If [`null`](core::ptr::null()), hostfxr is located using the enviroment variable or global registration
57 ///
58 /// # Return value
59 /// * `0` on success, otherwise failure
60 /// * `0x80008098` - `buffer` is too small ([`HostApiBufferTooSmall`](https://docs.rs/coreclr-hosting-shared/0.1.2/coreclr_hosting_shared/enum.StatusCode.html#variant.HostApiBufferTooSmall)
61 ///
62 /// # Remarks
63 /// The full search for the hostfxr library is done on every call. To minimize the need
64 /// to call this function multiple times, pass a large buffer (e.g. [`MAX_PATH`](https://docs.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation?tabs=cmd)).
65 pub fn get_hostfxr_path(
66 buffer: *mut char_t,
67 buffer_size: *mut size_t,
68 parameters: *const get_hostfxr_parameters,
69 ) -> i32;
70}
71
72/// Parameters for [`get_hostfxr_path`].
73#[repr(C)]
74pub struct get_hostfxr_parameters {
75 /// Size of the struct.
76 /// This is used for versioning.
77 pub size: size_t,
78 /// Path to the compenent's assembly.
79 /// If specified, hostfxr is located as if the `assembly_path` is the apphost
80 pub assembly_path: *const char_t,
81 /// Path to directory containing the dotnet executable.
82 /// If specified, hostfxr is located as if an application is started using
83 /// `dotnet app.dll`, which means it will be searched for under the `dotnet_root`
84 /// path and the `assembly_path` is ignored.
85 pub dotnet_root: *const char_t,
86}
87
88impl get_hostfxr_parameters {
89 /// Creates a new instance of [`get_hostfxr_parameters`] with the given `dotnet_root`.
90 /// The `size` field is set accordingly to the size of the struct and `assembly_path` to [`ptr::null()`].
91 #[must_use]
92 pub fn with_dotnet_root(dotnet_root: *const char_t) -> Self {
93 Self {
94 size: mem::size_of::<Self>(),
95 assembly_path: ptr::null(),
96 dotnet_root,
97 }
98 }
99 /// Creates a new instance of [`get_hostfxr_parameters`] with the given `assembly_path`.
100 /// The `size` field is set accordingly to the size of the struct and `dotnet_root` to [`ptr::null()`].
101 #[must_use]
102 pub fn with_assembly_path(assembly_path: *const char_t) -> Self {
103 Self {
104 size: mem::size_of::<Self>(),
105 assembly_path,
106 dotnet_root: ptr::null(),
107 }
108 }
109}