Native C ABI

Use a supported higher-level wrapper whenever one exists. Direct C consumers are responsible for callback threading, handle serialization, consent presentation, and terminal cleanup.

Version and capabilities

uint32_t sdk_abi_version(void);
uint64_t sdk_abi_capabilities(void);

SDK 1.0.0 exposes ABI major 1. Reject an unsupported ABI before creating a handle.

Construction

void* sdk_new_with_consent(const char* api_key, bool consent);
void* sdk_new_with_debug_and_consent(
    const char* api_key,
    bool debug,
    bool consent);
void* sdk_new_with_debug_device_identity_and_consent(
    const char* api_key,
    bool debug,
    const char* device_identity_seed,
    bool consent);
void* sdk_new_with_debug_device_identity_and_consent_receipt(
    const char* api_key,
    bool debug,
    const char* device_identity_seed,
    const char* consent_receipt);

Legacy constructors without consent remain exported for ABI compatibility but return NULL.

Identity helper

char* sdk_resolve_device_identity(
    const char* api_key,
    const char* device_identity_seed);
void sdk_string_free(char* value);

Free returned owned strings with sdk_string_free.

Lifecycle callbacks

void sdk_set_callbacks(
    void* handle,
    void (*on_connect)(void* user_data),
    void (*on_disconnect)(int reason, void* user_data),
    void* user_data);

bool sdk_connect(void* handle);
void sdk_disconnect(void* handle);
bool sdk_is_online(void* handle);
int sdk_last_disconnect_reason(void* handle);
void sdk_free(void* handle);

Passing NULL for both callbacks clears callback registration. Do this before releasing managed callback state.

Error accessors

const char* sdk_last_error_message(void);
int sdk_last_error_code(void);
bool sdk_last_error_retryable(void);
int sdk_last_error_disconnect_reason(void);

Read the message immediately after failure and copy it if it must outlive the next SDK call on the same thread.

Ownership rules

• One non-null handle represents one logical peer.
• Serialize calls when multiple threads can touch a handle.
• Do not free during another call or callback.
• Clear callbacks before releasing their context.
• Call sdk_free exactly once and never reuse the pointer.

Platform signature difference

Desktop constructors place api_key before debug; generated iOS declarations preserve their platform signature order. Use the header supplied with the exact artifact instead of copying declarations from this overview.