Skip to main content

Crate oxigdal_mobile

Crate oxigdal_mobile 

Source
Expand description

OxiGDAL Mobile SDK - FFI bindings for iOS and Android

This crate provides C-compatible FFI bindings that enable OxiGDAL to be used from iOS (Swift/Objective-C) and Android (Kotlin/Java) applications.

§Architecture

The mobile SDK is organized into several layers:

  • FFI Layer (ffi module): C-compatible types and functions
  • Platform Layer (ios/android modules): Platform-specific utilities
  • Language Bindings (Swift/Kotlin): High-level wrappers (in bindings/ directory)

§Safety

While this crate uses unsafe extensively due to FFI requirements, it provides safety guarantees through:

  • Extensive null pointer validation
  • Bounds checking on all array operations
  • UTF-8 validation on string conversions
  • Proper resource lifecycle management
  • Thread-safe error handling

§Memory Management

The FFI layer follows these conventions:

  • Handles: Created by *_open or *_create, freed by *_close or *_free
  • Strings: Returned strings must be freed with oxigdal_string_free
  • Buffers: Caller-allocated, OxiGDAL only writes to them
  • Opaque Types: Must not be dereferenced on the foreign side

§Error Handling

All FFI functions return OxiGdalErrorCode:

  • Success (0) indicates success
  • Non-zero values indicate specific error types
  • Detailed messages available via oxigdal_get_last_error()

§Example (C API)

// Initialize
oxigdal_init();

// Open dataset
OxiGdalDataset* dataset;
if (oxigdal_dataset_open("/path/to/file.tif", &dataset) != Success) {
    char* error = oxigdal_get_last_error();
    printf("Error: %s\n", error);
    oxigdal_string_free(error);
    return;
}

// Get metadata
OxiGdalMetadata metadata;
oxigdal_dataset_get_metadata(dataset, &metadata);
printf("Size: %d x %d\n", metadata.width, metadata.height);

// Read region
OxiGdalBuffer* buffer = oxigdal_buffer_alloc(256, 256, 3);
oxigdal_dataset_read_region(dataset, 0, 0, 256, 256, 1, buffer);

// Cleanup
oxigdal_buffer_free(buffer);
oxigdal_dataset_close(dataset);
oxigdal_cleanup();

§Features

  • std (default): Enable standard library support
  • ios: Enable iOS-specific bindings
  • android: Enable Android JNI bindings
  • offline: Enable offline COG reading
  • filters: Enable image enhancement filters
  • tiles: Enable map tile generation

§Platform Support

§iOS

  • Target: aarch64-apple-ios, x86_64-apple-ios (simulator)
  • Swift bindings available in bindings/ios/
  • Integration: CocoaPods, Swift Package Manager

§Android

  • Targets: aarch64-linux-android, armv7-linux-androideabi, x86_64-linux-android
  • Kotlin bindings available in bindings/android/
  • Integration: Gradle, AAR library

§COOLJAPAN Policies

This crate adheres to COOLJAPAN ecosystem policies:

  • Pure Rust: No C/C++ dependencies by default
  • No Unwrap: All error cases explicitly handled
  • Workspace: Version management via workspace
  • Latest Crates: Always use latest stable dependencies

Re-exports§

pub use ffi::oxigdal_cleanup;
pub use ffi::oxigdal_init;
pub use ffi::types::*;

Modules§

android
Android-specific bindings and utilities.
common
Common mobile utilities shared between iOS and Android.
ffi
Foreign Function Interface (FFI) layer for mobile bindings.
ios
iOS-specific bindings and utilities.

Macros§

check_null
Macro to check for null pointers.
deref_ptr
Macro to wrap pointer dereferencing safely.
deref_ptr_mut
Macro to wrap mutable pointer dereferencing safely.
ffi_result
Macro to safely handle Result types in FFI functions.