pub struct Library(/* private fields */);Expand description
The platform-specific counterpart of the cross-platform Library.
Implementations§
Source§impl Library
impl Library
Sourcepub unsafe fn new<P: AsRef<OsStr>>(filename: P) -> Result<Library, Error>
pub unsafe fn new<P: AsRef<OsStr>>(filename: P) -> Result<Library, Error>
Find and load a module.
If the filename specifies a full path, the function only searches that path for the
module. Otherwise, if the filename specifies a relative path or a module name without a
path, the function uses a Windows-specific search strategy to find the module. For more
information, see the Remarks on MSDN.
If the filename specifies a library filename without a path and with the extension omitted,
the .dll extension is implicitly added. This behaviour may be suppressed by appending a
trailing . to the filename.
This is equivalent to Library::load_with_flags(filename, 0).
§Safety
When a library is loaded, initialisation routines contained within the library are executed. For the purposes of safety, the execution of these routines is conceptually the same calling an unknown foreign function and may impose arbitrary requirements on the caller for the call to be sound.
Additionally, the callers of this function must also ensure that execution of the termination routines contained within the library is safe as well. These routines may be executed when the library is unloaded.
Sourcepub fn this() -> Result<Library, Error>
pub fn this() -> Result<Library, Error>
Get the Library representing the original program executable.
Note that the behaviour of the Library loaded with this method is different from
Libraries loaded with os::unix::Library::this. For more information refer to MSDN.
Corresponds to GetModuleHandleExW(0, NULL, _).
Sourcepub fn open_already_loaded<P: AsRef<OsStr>>(
filename: P,
) -> Result<Library, Error>
pub fn open_already_loaded<P: AsRef<OsStr>>( filename: P, ) -> Result<Library, Error>
Get a module that is already loaded by the program.
This function returns a Library corresponding to a module with the given name that is
already mapped into the address space of the process. If the module isn’t found, an error is
returned.
If the filename does not include a full path and there are multiple different loaded
modules corresponding to the filename, it is impossible to predict which module handle
will be returned. For more information refer to MSDN.
If the filename specifies a library filename without a path and with the extension omitted,
the .dll extension is implicitly added. This behaviour may be suppressed by appending a
trailing . to the filename.
This is equivalent to GetModuleHandleExW(0, filename, _).
Sourcepub unsafe fn load_with_flags<P: AsRef<OsStr>>(
filename: P,
flags: u32,
) -> Result<Library, Error>
pub unsafe fn load_with_flags<P: AsRef<OsStr>>( filename: P, flags: u32, ) -> Result<Library, Error>
Find and load a module, additionally adjusting behaviour with flags.
See Library::new for documentation on the handling of the filename argument. See the
flag table on MSDN for information on applicable values for the flags argument.
Corresponds to LoadLibraryExW(filename, reserved: NULL, flags).
§Safety
When a library is loaded, initialisation routines contained within the library are executed. For the purposes of safety, the execution of these routines is conceptually the same calling an unknown foreign function and may impose arbitrary requirements on the caller for the call to be sound.
Additionally, the callers of this function must also ensure that execution of the termination routines contained within the library is safe as well. These routines may be executed when the library is unloaded.
Sourcepub fn pin(&self) -> Result<(), Error>
pub fn pin(&self) -> Result<(), Error>
Attempts to pin the module represented by the current Library into memory.
Calls GetModuleHandleExW with the flag GET_MODULE_HANDLE_EX_FLAG_PIN to pin the module.
See the MSDN documentation for more information.
If successful, the module will remain in memory regardless of the refcount for this Library
Sourcepub unsafe fn get<T>(&self, symbol: &[u8]) -> Result<Symbol<T>, Error>
pub unsafe fn get<T>(&self, symbol: &[u8]) -> Result<Symbol<T>, Error>
Get a pointer to a function or static variable by symbol name.
The symbol may not contain any null bytes, with the exception of the last byte. A null
terminated symbol may avoid a string allocation in some cases.
Symbol is interpreted as-is; no mangling is done. This means that symbols like x::y are
most likely invalid.
§Safety
Users of this API must specify the correct type of the function or variable loaded.
Sourcepub unsafe fn get_ordinal<T>(&self, ordinal: u16) -> Result<Symbol<T>, Error>
pub unsafe fn get_ordinal<T>(&self, ordinal: u16) -> Result<Symbol<T>, Error>
Get a pointer to a function or static variable by ordinal number.
§Safety
Users of this API must specify the correct type of the function or variable loaded.
Sourcepub unsafe fn from_raw(handle: isize) -> Library
pub unsafe fn from_raw(handle: isize) -> Library
Convert a raw handle to a Library.
§Safety
The handle must be the result of a successful call of LoadLibraryA, LoadLibraryW,
LoadLibraryExW, or LoadLibraryExA, or a handle previously returned by the
Library::into_raw call.
Sourcepub fn close(self) -> Result<(), Error>
pub fn close(self) -> Result<(), Error>
Unload the library.
You only need to call this if you are interested in handling any errors that may arise when
library is unloaded. Otherwise this will be done when Library is dropped.
The underlying data structures may still get leaked if an error does occur.