Struct Session 

pub struct Session { /* private fields */ }

A Windows Installer session passed to custom actions.

Example

use msica::prelude::*;
const ERROR_SUCCESS: u32 = 0;

#[no_mangle]
pub extern "C" fn MyCustomAction(session: Session) -> u32 {
    let record = Record::with_fields(
        Some("this is [1] [2]"),
        vec![Field::IntegerData(1), Field::StringData("example".to_owned())],
    ).expect("failed to create record");
    session.message(MessageType::User, &record);
    ERROR_SUCCESS
}

Implementations

impl Session

pub fn database(&self) -> Database

Returns the active database for the installation. This function returns a read-only Database.

Examples found in repository

examples/deferred/lib.rs (line 8)

pub extern "C" fn DeferredExampleCustomAction(session: Session) -> CustomActionResult {
    let database = session.database();
    let view = database
        .open_view("SELECT `Cardinal`, `Ordinal` FROM `DeferredExample` ORDER BY `Cardinal`")?;

    // Add another row.
    view.modify(
        ModifyMode::InsertTemporary,
        &Record::with_fields(
            None,
            vec![
                Field::IntegerData(100),
                Field::StringData("last".to_string()),
            ],
        )?,
    )?;

    // Schedule custom actions for each row.
    view.execute(None)?;
    for record in view {
        let data = format!(
            "{}\t{}",
            record.integer_data(1).unwrap_or(0),
            record.string_data(2)?,
        );
        session.do_deferred_action("DeferredExampleCustomActionDeferred", &data)?;
    }
    Success
}

pub fn do_action(&self, action: Option<&str>) -> Result<()>

Runs the specified immediate custom action, or schedules a deferred custom action. If None the default action is run e.g., INSTALL.

To schedule a deferred custom action with its CustomActionData, call Session::do_deferred_action().

pub fn do_deferred_action( &self, action: &str, custom_action_data: &str, ) -> Result<()>

Sets custom action data and schedules a deferred custom action.

Example

use msica::prelude::*;
const ERROR_SUCCESS: u32 = 0;

#[no_mangle]
pub extern "C" fn MyCustomAction(session: Session) -> u32 {
    for i in 0..5 {
        session.do_deferred_action("MyDeferredCustomAction", &i.to_string());
    }
    ERROR_SUCCESS
}

#[no_mangle]
pub extern "C" fn MyDeferredCustomAction(session: Session) -> u32 {
    let data = session.property("CustomActionData").expect("failed to get CustomActionData");
    let record = Record::try_from(data).expect("failed to create record");
    session.message(MessageType::Info, &record);
    ERROR_SUCCESS
}

Examples found in repository

examples/skip/lib.rs (line 15)

pub extern "C" fn SkipExampleCustomAction(session: Session) -> CustomActionResult {
    let deferred = session.mode(RunMode::Scheduled);
    match deferred {
        false => {
            let data = session.property("SKIP")?;
            if data == "1" {
                return Skip;
            }
            session.do_deferred_action("SkipExampleCustomActionDeferred", data.as_str())?;
        }
        true => {
            let data = session.property("CustomActionData")?;
            if data.is_empty() {
                return Success;
            }

            // Unnecessarily parsing the string demonstrates using ? for any possible error.
            let data = data.parse::<u32>()?;
            if data == 2 {
                return Skip;
            }
        }
    }
    Success
}

examples/deferred/lib.rs (line 32)

pub extern "C" fn DeferredExampleCustomAction(session: Session) -> CustomActionResult {
    let database = session.database();
    let view = database
        .open_view("SELECT `Cardinal`, `Ordinal` FROM `DeferredExample` ORDER BY `Cardinal`")?;

    // Add another row.
    view.modify(
        ModifyMode::InsertTemporary,
        &Record::with_fields(
            None,
            vec![
                Field::IntegerData(100),
                Field::StringData("last".to_string()),
            ],
        )?,
    )?;

    // Schedule custom actions for each row.
    view.execute(None)?;
    for record in view {
        let data = format!(
            "{}\t{}",
            record.integer_data(1).unwrap_or(0),
            record.string_data(2)?,
        );
        session.do_deferred_action("DeferredExampleCustomActionDeferred", &data)?;
    }
    Success
}

pub fn language(&self) -> u16

The numeric language ID used by the current install session.

pub fn message(&self, kind: MessageType, record: &Record) -> i32

Processes a Record within the Session.

Examples found in repository

examples/deferred/lib.rs (line 50)

pub extern "C" fn DeferredExampleCustomActionDeferred(session: Session) -> CustomActionResult {
    // Process the custom action data passed by the immediate custom action.
    // This data is always made available in a property named "CustomActionData".
    let data = session.property("CustomActionData")?;
    let fields: Vec<&str> = data.split('\t').collect();
    let record = Record::with_fields(
        Some("Running the [2] ([1]) deferred custom action"),
        vec![
            Field::StringData(fields[0].to_string()),
            Field::StringData(fields[1].to_string()),
        ],
    )?;
    session.message(MessageType::Info, &record);
    Success
}

pub fn mode(&self, mode: RunMode) -> bool

Returns a boolean indicating whether the specific property passed into the function is currently set (true) or not set (false).

Example

You could use the same custom action entry point for scheduling and executing deferred actions:

use msica::prelude::*;
const ERROR_SUCCESS: u32 = 0;

#[no_mangle]
pub extern "C" fn MyCustomAction(session: Session) -> u32 {
    if !session.mode(RunMode::Scheduled) {
        session.do_deferred_action("MyCustomAction", "Hello, world!");
    } else {
        let data = session.property("CustomActionData").expect("failed to get CustomActionData");
        let record = Record::with_fields(Some(data.as_str()), vec![]).expect("failed to create record");
        session.message(MessageType::User, &record);
    }
    ERROR_SUCCESS
}

Examples found in repository

examples/skip/lib.rs (line 8)

pub extern "C" fn SkipExampleCustomAction(session: Session) -> CustomActionResult {
    let deferred = session.mode(RunMode::Scheduled);
    match deferred {
        false => {
            let data = session.property("SKIP")?;
            if data == "1" {
                return Skip;
            }
            session.do_deferred_action("SkipExampleCustomActionDeferred", data.as_str())?;
        }
        true => {
            let data = session.property("CustomActionData")?;
            if data.is_empty() {
                return Success;
            }

            // Unnecessarily parsing the string demonstrates using ? for any possible error.
            let data = data.parse::<u32>()?;
            if data == 2 {
                return Skip;
            }
        }
    }
    Success
}

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

Gets the value of the named property, or an empty string if undefined.

Examples found in repository

examples/deferred/lib.rs (line 41)

pub extern "C" fn DeferredExampleCustomActionDeferred(session: Session) -> CustomActionResult {
    // Process the custom action data passed by the immediate custom action.
    // This data is always made available in a property named "CustomActionData".
    let data = session.property("CustomActionData")?;
    let fields: Vec<&str> = data.split('\t').collect();
    let record = Record::with_fields(
        Some("Running the [2] ([1]) deferred custom action"),
        vec![
            Field::StringData(fields[0].to_string()),
            Field::StringData(fields[1].to_string()),
        ],
    )?;
    session.message(MessageType::Info, &record);
    Success
}

examples/skip/lib.rs (line 11)

pub extern "C" fn SkipExampleCustomAction(session: Session) -> CustomActionResult {
    let deferred = session.mode(RunMode::Scheduled);
    match deferred {
        false => {
            let data = session.property("SKIP")?;
            if data == "1" {
                return Skip;
            }
            session.do_deferred_action("SkipExampleCustomActionDeferred", data.as_str())?;
        }
        true => {
            let data = session.property("CustomActionData")?;
            if data.is_empty() {
                return Success;
            }

            // Unnecessarily parsing the string demonstrates using ? for any possible error.
            let data = data.parse::<u32>()?;
            if data == 2 {
                return Skip;
            }
        }
    }
    Success
}

pub fn set_property(&self, name: &str, value: Option<&str>) -> Result<()>

Sets the value of the named property. Pass None to clear the field.