#unsafe-bindings #storj #protocols #uplink #api #storage #libuplink

sys uplink-sys

Unsafe rust bindings for libuplink - the storj protocol library

12 releases (6 breaking)

new 0.7.1 Nov 14, 2024
0.7.0 May 30, 2024
0.6.1 Nov 27, 2023
0.5.2 Jul 14, 2022
0.1.1 May 18, 2021

#2 in #uplink


Used in uplink

Apache-2.0

25MB
4K SLoC

Go 2.5K SLoC // 0.2% comments C 1.5K SLoC // 0.0% comments Rust 76 SLoC // 0.3% comments Shell 24 SLoC // 0.4% comments

Contains (static library, 14MB) .docs-rs/libuplink.a, (ELF lib, 11MB) .docs-rs/libuplink.so

uplink-sys

CI Status Crates.io docs.rs Crates.io

This crate provides auto-generated unsafe Rust bindings, through bindgen, to C functions provided by uplink-c, the C interface for the Storj uplink API library.

Building (from repo)

Linux

  • Install Go
  • Install Rust
  • Install GCC and make sudo apt install build-essential
  • Install libclang (required by bindgen for generating platform specific c bindings) sudo apt install libclang-dev
  • Checkout this repo
  • Build crate make build (from uplink-sys directory)

macOS

  • Install Go
  • Install Rust
  • Checkout this repo
  • Build crate make build (from uplink-sys directory)

Building (from crates.io)

Linux

  • Install Go
  • Install libclang (required by bindgen for generating platform specific c bindings)
  • Add uplink-sys to Cargo.toml

Tests

NOTE the project has been tested on the following operating systems:

* ubuntu
	* Version: 20.04.2 LTS
	* Processor: Intel® Core™ i7-10510U CPU @ 1.80GHz × 8
* macOS
	* Version: 10.15.7
	* Processor: 2.6 GHz 6-Core Intel Corei7

Setup

To allow the integrations tests access to the test project, create a file in this directory with the satellite address and api key for running tests. Do not commit this file to the repo. test_secrets.txt:

<satellite_addresss>
<api_key>

Run

make test

Usage

See the examples directory to see how use the uplink-sys crate.

Below is an example showing how to list buckets using the crate's unsafe C bindings.

// Access parameters
let satellite_address = CString::new("SATELLITE ADDRESS HERE").expect("CString::new failed");
let api_key = CString::new("API KEY HERE").expect("CString::new failed");
let passphrase = CString::new("PASSPHRASE HERE").expect("CString::new failed");

unsafe {
    // Request access
    let access_result = uplink_sys::uplink_request_access_with_passphrase(
        satellite_address.as_ptr() as *mut uplink_sys::uplink_const_char,
        api_key.as_ptr() as *mut uplink_sys::uplink_const_char,
        passphrase.as_ptr() as *mut uplink_sys::uplink_const_char,
    );
    if access_result.error != std::ptr::null_mut() {
        println!("Error requesting access: {:?}", *(access_result.error));
    }

    // Access project
    let project_result = uplink_sys::uplink_open_project(access_result.access);
    if project_result.error != std::ptr::null_mut() {
        println!("Error accessing project: {:?}", *(project_result.error));
    }

    // Create empty string for bucket option struct
    let bucket_options_str = CString::new("").expect("CString::new failed");
    let mut bucket_options = uplink_sys::UplinkListBucketsOptions {
        cursor: bucket_options_str.as_ptr(),
    };

    // Request bucket iterator
    let p_bucket_iterator =
        uplink_sys::uplink_list_buckets(project_result.project, &mut bucket_options);

    // Check for valid bucket iterator
    let p_bucket_iterator_err = uplink_sys::uplink_bucket_iterator_err(p_bucket_iterator);
    if p_bucket_iterator_err == std::ptr::null_mut() {
        println!("Valid bucket iterator.");
    } else {
        println!(
            "Invalid bucket iterator. Error: {:?}.",
            *p_bucket_iterator_err
        );
    }

    // Iterate through all buckets
    let mut bucket_count = 0;
    while uplink_sys::uplink_bucket_iterator_next(p_bucket_iterator) {
        bucket_count += 1;

        let p_bucket_result = uplink_sys::uplink_bucket_iterator_item(p_bucket_iterator);
        let bucket_name = CStr::from_ptr((*p_bucket_result).name)
            .to_str()
            .expect("Invalid bucket name C string.");
        let created = datetime_string_from_unix_time((*p_bucket_result).created);

        println!(
            "Bucket {} => name: {}, created: {}",
            bucket_count, bucket_name, created
        );

        // Free memory
        uplink_sys::uplink_free_bucket(p_bucket_result);
    }

    // Free memory
    uplink_sys::uplink_free_access_result(access_result);
    uplink_sys::uplink_free_project_result(project_result);
    uplink_sys::uplink_free_bucket_iterator(p_bucket_iterator);
    uplink_sys::uplink_free_error(p_bucket_iterator_err);
}

Dependencies