Crate i2pd_sys

Expand description

Raw, bindgen-generated FFI bindings to the i2pd-sys/shim C shim over libi2pd (PurpleI2P/i2pd) — a real I2P router built in-process, not a client for a separately-running i2pd daemon.

§What’s here

Every symbol in this module is generated at build time from shim/shim.h (the only header bindgen ever runs against — never libi2pd’s own C++ headers, which use std::shared_ptr/STL types with no stable C ABI). See that file for the fully documented API surface; the short version:

Group	Functions
Lifecycle	`i2pd_init`, `i2pd_start`, `i2pd_stop`, `i2pd_terminate`
Destinations	`i2pd_create_transient_destination`, `i2pd_generate_keys`, `i2pd_create_persistent_destination`, `i2pd_destroy_destination`, `i2pd_destination_b32_address`, `i2pd_destination_ident_hash`, `i2pd_accept_stream`
Streams	`i2pd_create_stream`, `i2pd_stream_send`, `i2pd_stream_receive`, `i2pd_stream_is_open`, `i2pd_stream_close`, `i2pd_destroy_stream`
Memory	`i2pd_free_buffer`, `i2pd_free_string`

§Example

use i2pd_sys::*;
use std::ffi::CString;

unsafe {
    let app_name = CString::new("my-app").unwrap();
    i2pd_init(app_name.as_ptr()); // exactly once, before anything else
    i2pd_start();

    let dest = i2pd_create_transient_destination();
    assert!(!dest.is_null());

    // ... i2pd_accept_stream / i2pd_create_stream / i2pd_stream_send / i2pd_stream_receive ...

    i2pd_destroy_destination(dest);
    i2pd_stop();
    i2pd_terminate();
}

§Safety

This is a raw C ABI with all the usual obligations: i2pd_init must be called exactly once before any other function; every I2pdDestination/I2pdStream pointer must be destroyed exactly once (via the matching i2pd_destroy_*) and never used afterwards; buffers returned by i2pd_generate_keys/i2pd_destination_b32_address must be freed with i2pd_free_buffer/i2pd_free_string respectively, exactly once.

i2pd_stream_send and i2pd_stream_receive are safe to call concurrently from different threads on the same stream (one sending, one receiving) — each posts work onto i2pd’s internal io_service and blocks the calling thread on a condition variable, the same pattern i2pd’s own SAM/BOB bridges use. The callback registered via i2pd_accept_stream runs on i2pd’s own internal thread and must return quickly without blocking, or it stalls the event loop for every destination sharing that router.

Every shim function catches all C++ exceptions internally, so a C++ exception can never unwind across the extern "C" boundary (which would be undefined behavior) — failures surface as NULL/0/-1 return values instead, not panics or aborts.

§Crypto backend: `aws-lc` (default) vs `fips`

i2pd needs an OpenSSL-API-compatible crypto library; this crate provides one via exactly one of two backends, chosen with a priority rule rather than a hard exclusivity check:

aws-lc (default): regular AWS-LC via aws-lc-sys.
fips: the FIPS-validated AWS-LC-FIPS module via aws-lc-fips-sys instead. fips wins if both end up enabled (e.g. because a dependent crate’s own default pulled in aws-lc while a workspace-wide fips flag also reached in here) — aws-lc-sys may still get compiled in that case (as an unused, inert dependency), but build.rs only ever emits link directives for the fips backend, and aws-lc/aws-lc-fips link with per-version-prefixed symbol names (see their own links metadata), so nothing actually collides at link time. See the “FIPS” section of README.md for what this does (and does not) get you, and what it costs, before reaching for it to satisfy a compliance requirement.