/* Copyright (c) 2026 Juhapekka Piiroinen * All Rights Reserved. * AmoosedWeb project: https://amoosed.com * * DESIGN DRAFT ONLY. No amw1_ binary exports these declarations yet. * This file is outside the installed SDK include tree and is not a 1.0 * compatibility baseline. Numeric values and signatures may change. */ #ifndef AMOOSEDWEB_READER1_DRAFT_H #define AMOOSEDWEB_READER1_DRAFT_H #include #if defined(_WIN32) # define AMW1_CALL __cdecl # if defined(AMW1_C_BUILD) # define AMW1_API __declspec(dllexport) # else # define AMW1_API __declspec(dllimport) # endif #else # define AMW1_CALL # define AMW1_API __attribute__((visibility("default"))) #endif #ifdef __cplusplus extern "C" { #endif #define AMW1_ABI_MINOR 0u #define AMW1_MEMORY_LIMIT UINT64_C(67108864) /* Query bits describe this binary's compiled capabilities. Unknown bits are * ignored. A caller checks every bit it needs before using that feature. */ #define AMW1_CAP_HOSTED_INDEX UINT64_C(0x0001) #define AMW1_CAP_EXTERNAL_INDEX UINT64_C(0x0002) #define AMW1_CAP_BYTE_CARRIERS UINT64_C(0x0004) #define AMW1_CAP_MEMBER_CONTENT UINT64_C(0x0008) #define AMW1_CAP_OPERATION_CANCEL UINT64_C(0x0010) #define AMW1_CAP_PNG_LOW_BITS UINT64_C(0x0020) #define AMW1_CAP_FRAME_LUMA UINT64_C(0x0040) #define AMW1_CAP_WAV_TONES UINT64_C(0x0080) #define AMW1_CAP_MEMORY_READ UINT64_C(0x0100) #define AMW1_CAP_CALLBACK_HTTP UINT64_C(0x0200) /* Every fallible call returns a status. Unknown nonzero codes are failures; * callers must retain their numeric value. Diagnostic strings are never a * machine-readable error category. */ #define AMW1_STATUS_OK 0 #define AMW1_STATUS_INVALID_ARGUMENT 1 #define AMW1_STATUS_INVALID_STATE 2 #define AMW1_STATUS_NOT_FOUND 3 #define AMW1_STATUS_BAD_FORMAT 4 #define AMW1_STATUS_AUTHENTICATION_FAILED 5 #define AMW1_STATUS_VERIFICATION_FAILED 6 #define AMW1_STATUS_NETWORK_ERROR 7 #define AMW1_STATUS_OUTPUT_ERROR 8 #define AMW1_STATUS_ALREADY_EXISTS 9 #define AMW1_STATUS_UNSUPPORTED 10 #define AMW1_STATUS_BUFFER_TOO_SMALL 11 #define AMW1_STATUS_CANCELLED 12 #define AMW1_STATUS_INTERNAL_ERROR 13 #define AMW1_RESOURCE_PATH 1u #define AMW1_RESOURCE_SHA256 2u #define AMW1_RESOURCE_MIME 3u #define AMW1_RESOURCE_ACCESS 4u #define AMW1_RESOURCE_DELIVERY 5u typedef struct amw1_site amw1_site; typedef struct amw1_operation amw1_operation; /* Optional caller-supplied HTTP transport. The callback runs synchronously * on the Reader worker thread and may return OK, NETWORK_ERROR, or CANCELLED. * Its borrowed response pointers remain valid until the callback returns; * the Reader copies the response before requesting another range. A final URL * must equal origin plus the requested path. Native verification still checks * origin, status, range, body bounds, carrier hashes, and resource hashes. * The caller keeps context alive until every operation and site are released. * Cancellation of a blocked callback requires the caller to wake it. No key * or protected plaintext is passed to the transport. */ #define AMW1_FETCH_RANGE 1u #define AMW1_FETCH_SUFFIX 2u #define AMW1_FETCH_COMPLETE 3u typedef struct amw1_http_response { uint32_t struct_size; uint32_t status; const char* final_url_utf8; uint64_t final_url_length; const char* content_range; uint64_t content_range_length; const char* etag; uint64_t etag_length; const uint8_t* body; uint64_t body_length; } amw1_http_response; typedef int32_t (AMW1_CALL *amw1_http_fetch)( void* context, uint32_t kind, const char* path_utf8, uint64_t path_length, uint64_t first, uint64_t last_or_length, uint64_t max_body, amw1_http_response* response); /* Every 1.x binary exports this symbol. The major is encoded in its name. * On failure, both outputs are zero. Unknown capability bits are ignored. */ AMW1_API int32_t AMW1_CALL amw1_query( uint32_t* out_minor, uint64_t* out_capabilities); /* Prepare before worker dispatch; this call performs no I/O. An operation is * single-use. Another thread may cancel it; release only after its worker call * returns. A cancelled call does not publish partial output. */ AMW1_API int32_t AMW1_CALL amw1_operation_prepare(amw1_operation** out); AMW1_API void AMW1_CALL amw1_operation_cancel(amw1_operation* operation); AMW1_API void AMW1_CALL amw1_operation_release(amw1_operation* operation); /* The origin is HTTPS, or loopback HTTP for development. UTF-8 text inputs are * length-delimited and reject malformed UTF-8 and embedded NUL. Credential * and member-key inputs are binary bytes. The caller keeps every input valid * until the synchronous call returns. Diagnostic buffers are optional, with * NULL plus zero capacity, and never contain key or protected content bytes. */ AMW1_API int32_t AMW1_CALL amw1_site_prepare( const char* origin_utf8, uint64_t origin_length, amw1_site** out, char* error, uint64_t error_capacity); /* Same prepared-site lifecycle as amw1_site_prepare. The callback cannot * bypass the Reader's format, authentication, and verification checks. */ AMW1_API int32_t AMW1_CALL amw1_site_prepare_callback( const char* origin_utf8, uint64_t origin_length, amw1_http_fetch fetch, void* context, amw1_site** out, char* error, uint64_t error_capacity); AMW1_API int32_t AMW1_CALL amw1_site_load_hosted( amw1_site* site, amw1_operation* operation, char* error, uint64_t error_capacity); AMW1_API int32_t AMW1_CALL amw1_site_load_external( amw1_site* site, amw1_operation* operation, const uint8_t* credential, uint64_t credential_length, char* error, uint64_t error_capacity); /* A site loads once. Other site calls require caller serialization; release * only after every in-flight call returns. */ AMW1_API void AMW1_CALL amw1_site_release(amw1_site* site); /* Supplied scalar and handle outputs become zero or NULL on failure. String * queries use output=NULL, capacity=0 and report required bytes without NUL. * A short buffer returns BUFFER_TOO_SMALL with required length and leaves * caller bytes unchanged. Other failures report required=0. */ AMW1_API int32_t AMW1_CALL amw1_site_resource_count( const amw1_site* site, uint64_t* out_count); AMW1_API int32_t AMW1_CALL amw1_site_entry_path( const amw1_site* site, char* output, uint64_t capacity, uint64_t* required); AMW1_API int32_t AMW1_CALL amw1_site_member_key_id( const amw1_site* site, char* output, uint64_t capacity, uint64_t* required); AMW1_API int32_t AMW1_CALL amw1_site_resource_length( const amw1_site* site, uint64_t index, uint64_t* out_length); AMW1_API int32_t AMW1_CALL amw1_site_resource_string( const amw1_site* site, uint64_t index, uint32_t field, char* output, uint64_t capacity, uint64_t* required); /* Read to an absolute caller-selected local path. Publish only a fully * verified file and never replace an existing destination. A member key is * either NULL with length zero or exactly 32 raw bytes. On failure, out_bytes * is zero and no final file exists unless it already existed. */ AMW1_API int32_t AMW1_CALL amw1_site_download( amw1_site* site, amw1_operation* operation, const char* resource_utf8, uint64_t resource_length, const uint8_t* member_key, uint64_t member_key_length, const char* output_path_utf8, uint64_t output_path_length, uint64_t* out_bytes, char* error, uint64_t error_capacity); /* A NULL output with zero capacity queries the verified index's plaintext * length without fetching the resource. A short buffer returns * BUFFER_TOO_SMALL without I/O. Only after full verification and optional * authentication are bytes copied into caller memory. On any other failure, * required is zero and the entire caller buffer remains unchanged. An * operation is consumed even by a length query or short-buffer result. */ AMW1_API int32_t AMW1_CALL amw1_site_read_memory( amw1_site* site, amw1_operation* operation, const char* resource_utf8, uint64_t resource_length, const uint8_t* member_key, uint64_t member_key_length, uint8_t* output, uint64_t capacity, uint64_t* required, char* error, uint64_t error_capacity); #ifdef __cplusplus } #endif #endif