Struct Office

Source

pub struct Office { /* private fields */ }

Expand description

A Wrapper for the LibreOfficeKit C API.

Implementations§

Source §

impl Office

Source

pub fn new(install_path: &str) -> Result<Office, Error>

Create a new LibreOfficeKit instance.

§Arguments

install_path - The path to the LibreOffice installation.

§Example

use libreoffice_rs::Office;

let mut office = Office::new("/usr/lib/libreoffice/program")?;

assert_eq!("", office.get_error());

Source

pub fn get_error(&mut self) -> String

Returns the last error as a string

Source

pub fn register_callback<F: FnMut(c_int, *const c_char) + 'static>( &mut self, cb: F, ) -> Result<(), Error>

Registers a callback. LOK will invoke this function when it wants to inform the client about events.

§Arguments

cb - the callback to invoke (type, payload)

§Example

use libreoffice_rs::{Office, LibreOfficeKitOptionalFeatures};

let mut office = Office::new("/usr/lib/libreoffice/program")?;
office.set_optional_features(
   [LibreOfficeKitOptionalFeatures::LOK_FEATURE_DOCUMENT_PASSWORD]
)?;

office.register_callback(Box::new({
    move |_type, _payload| {
        println!("Call set_document_password and/or do something here!");
    }
}))?;

Source

pub fn document_load(&mut self, url: DocUrl) -> Result<Document, Error>

Loads a document from a URL.

§Arguments

url - The URL to load.

§Example

use libreoffice_rs::Office;
use libreoffice_rs::urls;

let mut office = Office::new("/usr/lib/libreoffice/program")?;
let doc_url = urls::local_into_abs("./test_data/test.odt")?;
office.document_load(doc_url)?;

Source

pub fn set_optional_features<T>( &mut self, optional_features: T, ) -> Result<u64, Error>
where T: IntoIterator<Item = LibreOfficeKitOptionalFeatures>,

Set bitmask of optional features supported by the client and return the flags set.

§Arguments

feature_flags - The feature flags to set.

@see LibreOfficeKitOptionalFeatures

@since LibreOffice 6.0

§Example

use libreoffice_rs::{Office, LibreOfficeKitOptionalFeatures};

let mut office = Office::new("/usr/lib/libreoffice/program")?;
let feature_flags = [
    LibreOfficeKitOptionalFeatures::LOK_FEATURE_DOCUMENT_PASSWORD,
    LibreOfficeKitOptionalFeatures::LOK_FEATURE_DOCUMENT_PASSWORD_TO_MODIFY,
];
let flags_set = office.set_optional_features(feature_flags)?;

// Integration tests assertions
for feature_flag in feature_flags {
  assert!(flags_set & feature_flag as u64 > 0,
    "Failed to set the flag with value: {}", feature_flag as u64
  );
}
assert!(flags_set &
LibreOfficeKitOptionalFeatures::LOK_FEATURE_PART_IN_INVALIDATION_CALLBACK as u64 == 0,
  "LOK_FEATURE_PART_IN_INVALIDATION_CALLBACK feature was wrongly set!"
);

Source

pub fn set_document_password( &mut self, url: DocUrl, password: &str, ) -> Result<(), Error>

Set password required for loading or editing a document.

Loading the document is blocked until the password is provided. This MUST be used in combination of features and within a callback

§Arguments

url - the URL of the document, as sent to the callback
password - the password, nullptr indicates no password

In response to LOK_CALLBACK_DOCUMENT_PASSWORD, a valid password will continue loading the document, an invalid password will result in another LOK_CALLBACK_DOCUMENT_PASSWORD request, and a NULL password will abort loading the document.

In response to LOK_CALLBACK_DOCUMENT_PASSWORD_TO_MODIFY, a valid password will continue loading the document, an invalid password will result in another LOK_CALLBACK_DOCUMENT_PASSWORD_TO_MODIFY request, and a NULL password will continue loading the document in read-only mode.

@since LibreOffice 6.0

§Example

use libreoffice_rs::{Office, LibreOfficeKitOptionalFeatures, urls};
use std::sync::atomic::{AtomicBool, Ordering};

let doc_url = urls::local_into_abs("./test_data/test_password.odt")?;
let password = "test";
let password_was_set = AtomicBool::new(false);
let mut office = Office::new("/usr/lib/libreoffice/program")?;

office.set_optional_features([LibreOfficeKitOptionalFeatures::LOK_FEATURE_DOCUMENT_PASSWORD])?;
office.register_callback({
    let mut office = office.clone();
    let doc_url = doc_url.clone();
    move |_, _| {
        if !password_was_set.load(Ordering::Acquire) {
            let ret = office.set_document_password(doc_url.clone(), &password);
            password_was_set.store(true, Ordering::Release);
        }
    }
})?;

let mut _doc = office.document_load(doc_url)?;

Source

pub fn unset_document_password(&mut self, url: DocUrl) -> Result<(), Error>

This method provides a defense mechanism against infinite loops, upon password entry failures:

Loading the document is blocked until a valid password is set within callbacks
A wrong password will result into infinite repeated callback loops
This method advises LibreOfficeKit to stop requesting a password “as soon as possible”

It is safe for this method to be invoked even if the originally provided password was correct:

LibreOfficeKit appears to maintain thread-local values of the password. It will stick to the first password entry value. That will translate into a a successfully loaded document.
LibreOfficeKit seems to send an “excessive” number of callbacks (potential internal issues with locks/monitors)

§Arguments

url - the URL of the document, as sent to the callback

§Example

use libreoffice_rs::{Office, LibreOfficeKitOptionalFeatures, urls};
use std::sync::atomic::{AtomicBool, Ordering};

let doc_url = urls::local_into_abs("./test_data/test_password.odt")?;
let password = "forgotten_invalid_password_which_is_just_test";
let password_was_set = AtomicBool::new(false);
let failed_password_attempt = AtomicBool::new(false);
let mut office = Office::new("/usr/lib/libreoffice/program")?;

office.set_optional_features([LibreOfficeKitOptionalFeatures::LOK_FEATURE_DOCUMENT_PASSWORD])?;
office.register_callback({
    let mut office = office.clone();
    let doc_url = doc_url.clone();
    move |_, _| {
        if !password_was_set.load(Ordering::Acquire) {
            let ret = office.set_document_password(doc_url.clone(), &password);
            password_was_set.store(true, Ordering::Release);
        } else {
            if !failed_password_attempt.load(Ordering::Acquire) {
                let ret = office.unset_document_password(doc_url.clone());
                failed_password_attempt.store(true, Ordering::Release);
            }
        }
    }
})?;

assert!(office.document_load(doc_url).is_err(),
        "Document loaded successfully with a wrong password!");

Source

pub fn document_load_with( &mut self, url: DocUrl, options: &str, ) -> Result<Document, Error>

Loads a document from a URL with additional options.

§Arguments

url - The URL to load.
options - options for the import filter, e.g. SkipImages. Another useful FilterOption is “Language=…”. It is consumed by the documentLoad() itself, and when provided, LibreOfficeKit switches the language accordingly first.

§Example

use libreoffice_rs::{Office, urls};

let mut office = Office::new("/usr/lib/libreoffice/program")?;
let doc_url = urls::local_into_abs("./test_data/test.odt")?;
office.document_load_with(doc_url, "en-US")?;