Crate aviso_ffi 

Stable C ABI for aviso, the client library for ECMWF’s aviso-server notification service, plus a hand-written header-only C++ facade (include/aviso.hpp) over it.

This crate is a peer consumer of the core aviso crate: it depends on aviso and never the reverse, and the core carries no FFI machinery. The generated C header is include/aviso.h; regenerate it with the gen-header feature (see the crate README). The design rationale lives in plans/decisions.md (ADR D21).

Boundary contract

• Every fallible call returns an owning AvisoOutcome; inspect it, take any success value with the matching typed take, then free it.
• Handles are owning pointers, each freed by its aviso_*_free. Builder and request handles are consumed through a pointer-to-pointer that is nulled on consumption.
• Strings cross as UTF-8 const char*; JSON crosses as compact-JSON const char*.
• Blocking calls must not run on a thread already inside the runtime.
• Every entry point traps Rust panics and reports them as AvisoErrorKind::Panic rather than unwinding across the boundary.

Structs

AvisoClient

Opaque client handle. Wraps the core client (cheap to clone, shares the connection pool and auth state).

AvisoClientBuilder

Opaque client-builder handle. Setters mutate it in place; the first error (a bad argument or an auth-construction failure) is remembered and surfaced at aviso_client_builder_build.

AvisoError

C-visible error detail. The const char* fields borrow from the owning AvisoOutcome and are valid until it is freed. A pointer is null when the field does not apply (request_id when unknown, trigger_kind / error_kind unless kind is AvisoErrorKind_Trigger).

AvisoNotification

A read-only view of one notification, valid only for the on_notification call it is passed to. The identifier and payload are pre-serialized to compact JSON; the accessors return borrowed pointers into this view.

AvisoOutcome

Result of a fallible C ABI call. Opaque to C; always freed with aviso_outcome_free.

AvisoTrigger

Opaque trigger handle. Built by a factory, tuned by the setters, and consumed by aviso_watch_request_add_trigger (which nulls the caller’s pointer) or freed with aviso_trigger_free.

AvisoWatch

Opaque handle to a running watch. Stop it with aviso_watch_stop, block for its completion with aviso_watch_wait, and release it with aviso_watch_free.

AvisoWatchRequest

Opaque builder for a watch request. Setters mutate it in place; the first bad argument is remembered and surfaced through on_end when the watch starts. Consumed by aviso_client_watch (which nulls the caller’s pointer) or freed with aviso_watch_request_free.

Enums

AvisoErrorKind

Discriminates an AvisoError.

AvisoHttpMethod

HTTP method for the webhook trigger. Discriminants are fixed for ABI stability and mirror the core HttpMethod.

Functions

aviso_version

Returns the library version as a static, NUL-terminated string. The pointer is valid for the life of the process and must not be freed.