Struct memflow::plugins::Inventory

pub struct Inventory { /* private fields */ }

The core of the plugin system

It scans system directories and collects valid memflow plugins. They can then be instantiated easily. The reason the libraries are collected is to allow for reuse, and save performance

Examples

Creating a OS instance, the recommended way:

use memflow::plugins::Inventory;
let inventory = Inventory::scan();
inventory
  .builder()
  .connector("qemu")
  .os("win32")
  .build()

Nesting connectors and os plugins:

use memflow::plugins::{Inventory, Args};
let inventory = Inventory::scan();
let os = inventory
  .builder()
  .connector("qemu")
  .os("linux")
  .connector("qemu")
  .os("win32")
  .build();

Implementations

impl Inventory

pub fn scan_path<P: AsRef<Path>>(path: P) -> Result<Self>

Creates a new inventory of plugins from the provided path. The path has to be a valid directory or the function will fail with an Error::IO error.

Examples

Creating a inventory:

use memflow::plugins::Inventory;

let inventory = Inventory::scan_path("./")
    .unwrap();

pub fn scan() -> Self

Creates a new inventory of plugins by searching various paths.

It will query PATH, and an additional set of of directories (standard unix ones, if unix, and “HOME/.local/lib” on all OSes) for “memflow” directory, and if there is one, then search for libraries in there.

Examples

Creating an inventory:

use memflow::plugins::Inventory;

let inventory = Inventory::scan();

pub fn add_dir_filtered( &mut self, dir: PathBuf, filter: &str ) -> Result<&mut Self>

Adds a library directory to the inventory

This function applies additional filter to only scan potentially wanted files

Safety

Same as previous functions - compiler can not guarantee the safety of third party library implementations.

pub fn add_dir(&mut self, dir: PathBuf) -> Result<&mut Self>

Adds a library directory to the inventory

Safety

Same as previous functions - compiler can not guarantee the safety of third party library implementations.

pub fn with_workspace(self) -> Result<Self>

Adds cargo workspace to the inventory

This function is used behind the scenes by the documentation, however, is not particularly useful for end users.

pub fn load(&mut self, path: PathBuf) -> &mut Self

Adds a single library to the inventory

Safety

Same as previous functions - compiler can not guarantee the safety of third party library implementations.

pub fn available_connectors(&self) -> Vec<String>

Returns the names of all currently available connectors that can be used.

pub fn available_os(&self) -> Vec<String>

Returns the names of all currently available os plugins that can be used.

pub fn connector_help(&self, name: &str) -> Result<String>

Returns the help string of the given Connector.

This function returns an error in case the Connector was not found or does not implement the help feature.

pub fn os_help(&self, name: &str) -> Result<String>

Returns the help string of the given Os Plugin.

This function returns an error in case the Os Plugin was not found or does not implement the help feature.

pub fn connector_target_list(&self, name: &str) -> Result<Vec<TargetInfo>>

Returns a list of all available targets of the connector.

This function returns an error in case the connector does not implement this feature.

pub fn builder(&self) -> BuilderEmpty<'_>

Creates a new Connector / OS builder.

Examples

Create a connector:

use memflow::plugins::Inventory;

let inventory = Inventory::scan();
let os = inventory
  .builder()
  .connector("qemu")
  .build();

Create a Connector with arguments:

use memflow::plugins::{Inventory, Args};

let inventory = Inventory::scan();
let os = inventory
  .builder()
  .connector("qemu")
  .args(str::parse("vm-win10").unwrap())
  .build();

Create a Connector and OS with arguments:

use memflow::plugins::{Inventory, Args};

let inventory = Inventory::scan();
let os = inventory
  .builder()
  .connector("qemu")
  .args(str::parse("vm-win10").unwrap())
  .os("win10")
  .build();

Create a OS without a connector and arguments:

use memflow::plugins::Inventory;

let inventory = Inventory::scan();
let os = inventory
  .builder()
  .os("native")
  .build();

pub fn create_connector( &self, name: &str, input: ConnectorInputArg, args: Option<&ConnectorArgs> ) -> Result<ConnectorInstanceArcBox<'static>>

Tries to create a new instance for the library with the given name. The instance will be initialized with the args provided to this call.

In case no library could be found this will throw an Error::Library.

Safety

This function assumes all libraries were loaded with appropriate safety checks in place. This function is safe, but can crash if previous checks fail.

Examples

Creating a connector instance:

use memflow::plugins::{Inventory, Args};

let inventory = Inventory::scan_path("./").unwrap();
let connector = inventory
    .create_connector("coredump", None, None)
    .unwrap();

Defining a dynamically loaded connector:

use memflow::error::Result;
use memflow::types::size;
use memflow::dummy::DummyMemory;
use memflow::plugins::ConnectorArgs;
use memflow::derive::connector;
use memflow::mem::phys_mem::*;

#[connector(name = "dummy_conn")]
pub fn create_connector(_args: &ConnectorArgs) -> Result<DummyMemory> {
    Ok(DummyMemory::new(size::mb(16)))
}

pub fn create_os( &self, name: &str, input: OsInputArg, args: Option<&OsArgs> ) -> Result<OsInstanceArcBox<'static>>

Create OS instance

This is the primary way of building a OS instance.

Arguments

• name - name of the target OS
• input - connector to be passed to the OS
• args - arguments to be passed to the OS

Examples

Creating a OS instance with custom arguments

use memflow::plugins::{Inventory, ConnectorArgs};

let args = str::parse(":4m").unwrap();
let os = inventory.create_os("dummy", None, Some(&args))
    .unwrap();
std::mem::drop(os);

pub fn set_max_log_level(&self, level: LevelFilter)

Sets the maximum logging level in all plugins and updates the internal PluginLogger in each plugin instance.