Struct PropertyObjectFile 

pub struct PropertyObjectFile { /* private fields */ }

A file holding property objects (PropertyObjectFile).

The file view of something that also has a richer identity, a sequence file reached through as_property_object_file, or a workspace’s options file. This is where a file’s registered types live.

Implementations

impl PropertyObjectFile

pub fn save_file_if_modified(&self, prompt: bool) -> Result<bool, Error>

Writes the file to disk if it has changed (PropertyObjectFile.SaveFileIfModified).

Does nothing when the file is unmodified. The path written is whatever path reports.

Pass prompt = false from a host with no operator. With true the engine puts a dialog on screen offering to save, and a headless caller would block on a question nobody can answer. The returned false means only that someone declined at that dialog, so under prompt = false a false should not happen.

Errors

Error if the COM call fails or returns an unexpected type.

pub fn type_usage_list(&self) -> Result<TypeUsageList, Error>

The types registered in this file (TypeUsageList).

Errors

Error if the COM call fails or returns an unexpected type.

Examples found in repository

examples/data_type_manage.rs (line 111)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = Engine::new()?;
    let sequence_file = engine.new_sequence_file()?;
    let file = sequence_file.as_property_object_file()?;
    let types = file.type_usage_list()?;

    types.insert_type(
        &build_multimeter_type(&engine)?,
        types.num_types()?,
        TypeCategory::CustomDataTypes,
    )?;
    let coupling = register_enum(
        &engine,
        &types,
        "Coupling",
        &[("AC", 0.0), ("DC", 1.0)],
        true,
    )?;

    // A variable of the enum type, so the change below has an instance to update.
    let main_sequence = sequence_file.get_sequence_by_name("MainSequence")?;
    main_sequence.locals()?.new_sub_property(
        "InputCoupling",
        PropValType::NamedType,
        false,
        "Coupling",
        INSERT_IF_MISSING,
    )?;

    println!(
        "Registered custom data types ({} in file):",
        types.num_types()?
    );
    print_enumerators(&coupling)?;

    // Evolve it: add an enumerator and raise the version.
    println!(
        "\nCoupling version before update: {}",
        coupling.type_version()?
    );
    coupling.update_enumerators(&enumerator_array(
        &engine,
        &[("AC", 0.0), ("DC", 1.0), ("GND", 2.0)],
        true,
    )?)?;

    // Raising the lowest field signals a change the engine applies silently;
    // raising a higher one marks it as deliberate.
    let version = coupling.type_version()?;
    let mut fields = version.split('.');
    let major: u32 = fields.next().unwrap_or("0").parse().unwrap_or(0);
    let minor: u32 = fields.next().unwrap_or("0").parse().unwrap_or(0);
    coupling.set_type_version(&format!("{major}.{}.0.0", minor + 1))?;
    println!(
        "Coupling version after  update: {}",
        coupling.type_version()?
    );

    println!("\nCoupling now defines (InputCoupling reflects this):");
    print_enumerators(&coupling)?;

    // Saving does nothing unless the file believes it changed.
    file.inc_change_count()?;
    let path = std::env::temp_dir().join("rs_teststand_with_custom_types.seq");
    sequence_file.save(&path.to_string_lossy())?;
    println!("\nSaved to {}", path.display());

    engine.release_sequence_file_ex(sequence_file, NO_OPTIONS)?;
    Ok(())
}

pub fn inc_change_count(&self) -> Result<(), Error>

Marks the file as modified (IncChangeCount).

Saving does nothing when the file does not believe it has changed, so a change made through the API needs this before the save will write.

Errors

Error if the COM call fails.

Examples found in repository

examples/template_manage_complex.rs (line 172)

fn apply_templates(
    sequence_file: &SequenceFile,
    step: &PropertyObject,
    sequence: &PropertyObject,
    variable: &PropertyObject,
) -> Result<(), Error> {
    let main_sequence = sequence_file.get_sequence_by_name(MAIN_SEQUENCE)?;

    // Inserting returns the copy on the Step interface, so it can be renamed
    // and re-identified straight away. Without a new step ID the copy would go
    // on claiming the prototype's identity.
    let inserted_step = main_sequence.insert_step_from_template(step, 0, StepGroup::Main)?;
    inserted_step.set_name("Step From Template")?;
    inserted_step.create_new_unique_step_id()?;
    println!("  step:     {}", inserted_step.name()?);

    let inserted_sequence = sequence_file.insert_sequence_from_template(sequence)?;
    inserted_sequence.create_new_unique_step_ids()?;
    println!(
        "  sequence: {} ({} step(s))",
        inserted_sequence.name()?,
        inserted_sequence.get_num_steps(StepGroup::Main)?
    );

    // A variable is the easy case: Locals is a property tree, so a clone drops
    // straight in under the template's own name.
    let locals = main_sequence.locals()?;
    locals.set_property_object(
        &variable.name()?,
        PropertyOptions::INSERT_IF_MISSING.bits(),
        &variable.clone_property("", PropertyOptions::NONE.bits())?,
    )?;
    println!(
        "  variable: {} = {:?}",
        variable.name()?,
        locals.get_val_string(&variable.name()?, PropertyOptions::NONE.bits())?
    );

    // A file that does not believe it changed will not write anything.
    sequence_file
        .as_property_object_file()?
        .inc_change_count()?;
    Ok(())
}

examples/data_type_manage.rs (line 169)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = Engine::new()?;
    let sequence_file = engine.new_sequence_file()?;
    let file = sequence_file.as_property_object_file()?;
    let types = file.type_usage_list()?;

    types.insert_type(
        &build_multimeter_type(&engine)?,
        types.num_types()?,
        TypeCategory::CustomDataTypes,
    )?;
    let coupling = register_enum(
        &engine,
        &types,
        "Coupling",
        &[("AC", 0.0), ("DC", 1.0)],
        true,
    )?;

    // A variable of the enum type, so the change below has an instance to update.
    let main_sequence = sequence_file.get_sequence_by_name("MainSequence")?;
    main_sequence.locals()?.new_sub_property(
        "InputCoupling",
        PropValType::NamedType,
        false,
        "Coupling",
        INSERT_IF_MISSING,
    )?;

    println!(
        "Registered custom data types ({} in file):",
        types.num_types()?
    );
    print_enumerators(&coupling)?;

    // Evolve it: add an enumerator and raise the version.
    println!(
        "\nCoupling version before update: {}",
        coupling.type_version()?
    );
    coupling.update_enumerators(&enumerator_array(
        &engine,
        &[("AC", 0.0), ("DC", 1.0), ("GND", 2.0)],
        true,
    )?)?;

    // Raising the lowest field signals a change the engine applies silently;
    // raising a higher one marks it as deliberate.
    let version = coupling.type_version()?;
    let mut fields = version.split('.');
    let major: u32 = fields.next().unwrap_or("0").parse().unwrap_or(0);
    let minor: u32 = fields.next().unwrap_or("0").parse().unwrap_or(0);
    coupling.set_type_version(&format!("{major}.{}.0.0", minor + 1))?;
    println!(
        "Coupling version after  update: {}",
        coupling.type_version()?
    );

    println!("\nCoupling now defines (InputCoupling reflects this):");
    print_enumerators(&coupling)?;

    // Saving does nothing unless the file believes it changed.
    file.inc_change_count()?;
    let path = std::env::temp_dir().join("rs_teststand_with_custom_types.seq");
    sequence_file.save(&path.to_string_lossy())?;
    println!("\nSaved to {}", path.display());

    engine.release_sequence_file_ex(sequence_file, NO_OPTIONS)?;
    Ok(())
}

pub fn data(&self) -> Result<PropertyObject, Error>

The root of the file’s property tree (Data).

Everything a file stores hangs off here, which is how a file with no richer identity, the templates file, for one, is read at all.

Errors

Error if the COM call fails or returns an unexpected type.

Examples found in repository

examples/step_insert_from_template.rs (line 36)

fn describe_templates(engine: &Engine) -> Result<(), Error> {
    let templates_file = engine.get_templates_file(GetTemplatesFileOptions::LOAD_IF_NOT_LOADED)?;
    let root = templates_file
        .data()?
        .get_property_object("Root", PropertyOptions::NONE.bits())?;
    for index in 0..root.get_num_elements()? {
        let category = root.get_property_object_by_offset(index, PropertyOptions::NONE.bits())?;
        if category.name()? == "Steps" {
            println!(
                "Step templates defined on this station: {}",
                category.get_num_elements()?
            );
        }
    }
    Ok(())
}

examples/template_manage_complex.rs (line 43)

fn describe_station_templates(engine: &Engine) -> Result<(), Error> {
    let templates_file = engine.get_templates_file(GetTemplatesFileOptions::LOAD_IF_NOT_LOADED)?;
    let root = templates_file
        .data()?
        .get_property_object("Root", PropertyOptions::NONE.bits())?;

    println!("Station templates file: {}", templates_file.path()?);
    for index in 0..root.get_num_elements()? {
        let category = root.get_property_object_by_offset(index, PropertyOptions::NONE.bits())?;
        println!(
            "  {}: {} template(s)",
            category.name()?,
            category.get_num_elements()?
        );
    }
    Ok(())
}

pub fn path(&self) -> Result<String, Error>

The file’s path (Path).

Errors

Error if the COM call fails or returns an unexpected type.

Examples found in repository

examples/template_manage_complex.rs (line 46)

fn describe_station_templates(engine: &Engine) -> Result<(), Error> {
    let templates_file = engine.get_templates_file(GetTemplatesFileOptions::LOAD_IF_NOT_LOADED)?;
    let root = templates_file
        .data()?
        .get_property_object("Root", PropertyOptions::NONE.bits())?;

    println!("Station templates file: {}", templates_file.path()?);
    for index in 0..root.get_num_elements()? {
        let category = root.get_property_object_by_offset(index, PropertyOptions::NONE.bits())?;
        println!(
            "  {}: {} template(s)",
            category.name()?,
            category.get_num_elements()?
        );
    }
    Ok(())
}

examples/users_manage.rs (line 102)

fn main() -> Result<(), rs_teststand::Error> {
    let engine = Engine::new()?;

    // Passing no profile means the user inherits nothing.
    let user = engine.new_user(None)?;
    user.set_login_name("operator1")?;
    user.set_full_name("Test Operator")?;
    user.set_password("ts-secret")?;

    println!("User: {} ({})", user.login_name()?, user.full_name()?);

    // Check a credential without handling the stored value.
    println!(
        "  password 'ts-secret' valid: {}",
        user.validate_password("ts-secret")?
    );
    println!(
        "  password 'wrong' valid:     {}",
        user.validate_password("wrong")?
    );

    println!("  privilege checks:");
    report_privileges(
        &user,
        &[
            UserPrivilege::Operate,
            UserPrivilege::Execute,
            UserPrivilege::Develop,
            UserPrivilege::Debug,
            UserPrivilege::EditUsers,
        ],
    )?;

    // A privilege can also be named by its full path, which is how a leaf
    // inside a category is reached.
    println!(
        "  Debug.RunSelectedTests:  {}",
        user.has_privilege_named("Debug.RunSelectedTests")?
    );

    // The privilege tree is nested: categories hold the individual rights.
    let privileges = user.privileges()?;
    let count = privileges.get_num_sub_properties("")?;
    println!("  privilege tree ({count} categories):");
    for index in 0..count {
        let name = privileges.get_nth_sub_property_name("", index, 0)?;
        let members = privileges
            .get_property_object(&name, 0)?
            .get_num_sub_properties("")?;
        println!("    {name:<12} {members} member(s)");
    }

    // The station itself, read-only.
    println!("\nStation:");
    match engine.current_user()? {
        Some(current) => println!("  logged in as {}", current.login_name()?),
        None => println!("  nobody logged in (usual when login is not required)"),
    }
    println!(
        "  is 'operator1' a real account here? {}",
        engine.user_name_exists("operator1")?
    );

    // Where accounts actually live. Everything above this point exists only in
    // memory: `new_user` builds a User, it does not enrol one. A user becomes
    // part of the station when it is inserted into this file's list and the
    // file is written.
    let users_file = engine.users_file()?;
    let file = users_file.as_property_object_file()?;
    println!(
        "
Users file:"
    );
    println!("  path            {}", file.path()?);
    println!(
        "  users           {}",
        users_file.user_list()?.get_num_elements()?
    );
    println!(
        "  groups          {}",
        users_file.user_group_list()?.get_num_elements()?
    );
    println!(
        "  profiles        {}",
        users_file.user_profile_list()?.get_num_elements()?
    );

    // Deliberately not run: it would edit the station this example is reading.
    // The two calls a host makes to enrol the user built above are
    //
    //     users_file.user_list()?.set_num_elements(count + 1, 0)?;   // then fill
    //     file.save_file_if_modified(false)?;                        // then write
    //
    // `false` matters: with `true` the engine puts a save dialog on screen, and
    // a host with no operator would wait for an answer that never comes.
    println!(
        "
  (this example does not write; enrolling a user would alter the station)"
    );

    Ok(())
}

pub fn set_path(&self, path: &str) -> Result<(), Error>

Sets the file’s path (Path).

Errors

Error if the COM call fails.

Trait Implementations

impl Debug for PropertyObjectFile

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.