/* Copyright (c) 2026 Juhapekka Piiroinen * All Rights Reserved. * AmoosedWeb project: https://amoosed.com */ #ifndef AMOOSEDWEB_PREVIEW_C_H #define AMOOSEDWEB_PREVIEW_C_H #include #if defined(_WIN32) # define AMW_PREVIEW_CALL __cdecl # if defined(AMW_PREVIEW_C_BUILD) # define AMW_PREVIEW_API __declspec(dllexport) # else # define AMW_PREVIEW_API __declspec(dllimport) # endif #else # define AMW_PREVIEW_CALL # define AMW_PREVIEW_API __attribute__((visibility("default"))) #endif #ifdef __cplusplus extern "C" { #endif /* Experimental ABI revision. These amw_preview_* names are not the 1.0 ABI. */ #define AMW_PREVIEW_ABI_REVISION 16u /* Query bits describe callable features in this binary, not licensing or * permissions for an individual site. Unknown bits must be ignored. */ #define AMW_PREVIEW_CAP_CATALOGUE UINT64_C(0x0001) #define AMW_PREVIEW_CAP_HOSTED_INDEX UINT64_C(0x0002) #define AMW_PREVIEW_CAP_EXTERNAL_INDEX UINT64_C(0x0004) #define AMW_PREVIEW_CAP_BYTE_CARRIERS UINT64_C(0x0008) #define AMW_PREVIEW_CAP_MEMBER_CONTENT UINT64_C(0x0010) #define AMW_PREVIEW_CAP_GAME_SESSION UINT64_C(0x0020) #define AMW_PREVIEW_CAP_OPERATION_CANCEL UINT64_C(0x0040) #define AMW_PREVIEW_CAP_PNG_LOW_BITS UINT64_C(0x0080) #define AMW_PREVIEW_CAP_FRAME_LUMA UINT64_C(0x0100) #define AMW_PREVIEW_CAP_WAV_TONES UINT64_C(0x0200) #define AMW_PREVIEW_CAP_MEMORY_READ UINT64_C(0x0400) #define AMW_PREVIEW_CAP_AUDIO_FILE UINT64_C(0x0800) #define AMW_PREVIEW_CAP_CALLBACK_HTTP UINT64_C(0x1000) #define AMW_PREVIEW_MEMORY_LIMIT UINT64_C(67108864) #define AMW_PREVIEW_AUDIO_WAV_LIMIT UINT64_C(67108864) /* Supplied scalar and handle outputs are cleared to zero/NULL before failure. * Caller-owned text buffers are unchanged on failure; a valid text query or * BUFFER_TOO_SMALL reports the required byte length excluding its NUL. * Required lengths are zero for other failures. Diagnostic error buffers are * separate and may contain bounded text on failure. */ /* Length-delimited text inputs must be strict UTF-8 without embedded NUL; * malformed text returns INVALID_ARGUMENT. Binary credentials and member keys * are byte arrays and are not interpreted as UTF-8. JSON catalogue parsing * reports malformed UTF-8 as BAD_FORMAT. */ #define AMW_PREVIEW_OK 0 #define AMW_PREVIEW_INVALID_ARGUMENT 1 /* Retained numeric slots from older previews; revision 13 uses typed results. */ #define AMW_PREVIEW_INVALID_DATA 2 #define AMW_PREVIEW_BUFFER_TOO_SMALL 3 #define AMW_PREVIEW_INTERNAL_ERROR 4 #define AMW_PREVIEW_READ_ERROR 5 #define AMW_PREVIEW_OUTPUT_ERROR 6 #define AMW_PREVIEW_CANCELLED 7 #define AMW_PREVIEW_ALREADY_EXISTS 8 #define AMW_PREVIEW_BAD_FORMAT 9 #define AMW_PREVIEW_AUTHENTICATION_FAILED 10 #define AMW_PREVIEW_VERIFICATION_FAILED 11 #define AMW_PREVIEW_NETWORK_ERROR 12 #define AMW_PREVIEW_UNSUPPORTED 13 #define AMW_PREVIEW_NOT_FOUND 14 #define AMW_PREVIEW_INVALID_STATE 15 #define AMW_PREVIEW_STALE_REVISION 16 #define AMW_PREVIEW_FIELD_ID 1u #define AMW_PREVIEW_FIELD_KIND 2u #define AMW_PREVIEW_FIELD_PATH 3u #define AMW_PREVIEW_RESOURCE_PATH 1u #define AMW_PREVIEW_RESOURCE_SHA256 2u #define AMW_PREVIEW_RESOURCE_MIME 3u #define AMW_PREVIEW_RESOURCE_ACCESS 4u #define AMW_PREVIEW_RESOURCE_DELIVERY 5u typedef struct amw_preview_catalogue amw_preview_catalogue; AMW_PREVIEW_API uint32_t AMW_PREVIEW_CALL amw_preview_abi_revision(void); /* On failure *out_capabilities is zero. Query the actual binary; the preview * catalogue, site, and game operations are implemented on Windows and Linux. */ AMW_PREVIEW_API int32_t AMW_PREVIEW_CALL amw_preview_capabilities( uint64_t* out_capabilities); /* Decode one self-contained AWA1 standalone WAV, independent of a website * index. The caller owns the WAV, raw 32-byte media key, and output buffer. * WAV input is limited to AUDIO_WAV_LIMIT bytes. The complete WAV is decoded * and authenticated before output is touched. NULL output with zero capacity * queries the authenticated plaintext length. A short buffer returns * BUFFER_TOO_SMALL with *required set; all other failures clear *required and * leave output unchanged. This synchronous local operation is not cancellable. * The caller must keep input, key, and output valid until it returns. */ AMW_PREVIEW_API int32_t AMW_PREVIEW_CALL amw_preview_audio_decode_file( const uint8_t* wav, uint64_t wav_length, const uint8_t* media_key, uint64_t media_key_length, uint8_t* output, uint64_t capacity, uint64_t* required, char* error, uint64_t error_capacity); /* JSON bytes need not have a trailing NUL. On failure *out is NULL. The error * buffer is optional and, when capacity > 0, always NUL terminated. */ AMW_PREVIEW_API int32_t AMW_PREVIEW_CALL amw_preview_catalogue_parse( const char* json, uint64_t json_length, amw_preview_catalogue** out, char* error, uint64_t error_capacity); AMW_PREVIEW_API void AMW_PREVIEW_CALL amw_preview_catalogue_release(amw_preview_catalogue* catalogue); AMW_PREVIEW_API int32_t AMW_PREVIEW_CALL amw_preview_catalogue_revision( const amw_preview_catalogue* catalogue, uint64_t* out_revision); AMW_PREVIEW_API int32_t AMW_PREVIEW_CALL amw_preview_catalogue_item_count( const amw_preview_catalogue* catalogue, uint64_t* out_count); /* Required length excludes the NUL. Call with output=NULL, capacity=0 to * query it. A too-small buffer is left untouched; caller retries with * required+1 bytes. Output remains valid only in caller-owned memory. */ AMW_PREVIEW_API int32_t AMW_PREVIEW_CALL amw_preview_catalogue_item_string( const amw_preview_catalogue* catalogue, uint64_t item_index, uint32_t field, char* output, uint64_t capacity, uint64_t* required); typedef struct amw_preview_site amw_preview_site; typedef struct amw_preview_game amw_preview_game; typedef struct amw_preview_operation amw_preview_operation; /* The callback runs synchronously on the caller's Reader worker. Return OK, * NETWORK_ERROR, or CANCELLED. Output pointers are borrowed only until the * callback returns and are copied by the Reader before the next request. * On OK, supply a final URL exactly equal to origin + the requested path; * redirects, changed paths, oversized bodies, and invalid headers fail. * Report Content-Encoding exactly as received, or leave it empty when absent. * Only absent or identity encoding is accepted; other values fail as NETWORK_ERROR. * Do not call the same site handle from inside the callback. The caller must * retain context until all operations and the site handle are released. * Cancellation sets the operation flag, but a blocked callback must arrange * its own wakeup before the worker can return. No keys enter the callback. */ #define AMW_PREVIEW_FETCH_RANGE 1u #define AMW_PREVIEW_FETCH_SUFFIX 2u #define AMW_PREVIEW_FETCH_COMPLETE 3u typedef struct amw_preview_http_response { 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 char* content_encoding; uint64_t content_encoding_length; const uint8_t* body; uint64_t body_length; } amw_preview_http_response; typedef int32_t (AMW_PREVIEW_CALL *amw_preview_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, amw_preview_http_response* response); /* Create before dispatching a synchronous site/game call to a worker thread. * Another thread may cancel the operation. One handle is single-use; release * it only after the worker call returns. Operations on one site/game remain * serialized. Cancellation before dispatch returns CANCELLED. */ AMW_PREVIEW_API int32_t AMW_PREVIEW_CALL amw_preview_operation_prepare( amw_preview_operation** out); AMW_PREVIEW_API void AMW_PREVIEW_CALL amw_preview_operation_cancel( amw_preview_operation* operation); AMW_PREVIEW_API void AMW_PREVIEW_CALL amw_preview_operation_release( amw_preview_operation* operation); /* Native preview uses HTTPS, or loopback HTTP for local development. The * origin must be an HTTPS origin (or loopback HTTP), with no path, credentials, * query, or fragment. * All site functions except cancel require caller serialization. Release only * after in-flight operations return; cancel may run from another thread. * Prepare creates a handle without network I/O. Register or share that handle * before load so another thread can cancel an in-progress index opening. * Load may be called once; a failed load leaves the handle releasable. */ AMW_PREVIEW_API int32_t AMW_PREVIEW_CALL amw_preview_site_prepare( const char* origin_utf8, uint64_t origin_length, amw_preview_site** out, char* error, uint64_t error_capacity); AMW_PREVIEW_API int32_t AMW_PREVIEW_CALL amw_preview_site_prepare_callback( const char* origin_utf8, uint64_t origin_length, amw_preview_http_fetch fetch, void* context, amw_preview_site** out, char* error, uint64_t error_capacity); AMW_PREVIEW_API int32_t AMW_PREVIEW_CALL amw_preview_site_load_hosted( amw_preview_site* site, char* error, uint64_t error_capacity); AMW_PREVIEW_API int32_t AMW_PREVIEW_CALL amw_preview_site_load_hosted_operation( amw_preview_site* site, amw_preview_operation* operation, char* error, uint64_t error_capacity); AMW_PREVIEW_API int32_t AMW_PREVIEW_CALL amw_preview_site_load_external( amw_preview_site* site, const uint8_t* credential, uint64_t credential_length, char* error, uint64_t error_capacity); AMW_PREVIEW_API int32_t AMW_PREVIEW_CALL amw_preview_site_load_external_operation( amw_preview_site* site, amw_preview_operation* operation, const uint8_t* credential, uint64_t credential_length, char* error, uint64_t error_capacity); /* Convenience open calls remain available but cannot cancel an in-progress * open because they return the handle only after verification completes. */ AMW_PREVIEW_API int32_t AMW_PREVIEW_CALL amw_preview_site_open_hosted( const char* origin_utf8, uint64_t origin_length, amw_preview_site** out, char* error, uint64_t error_capacity); /* Credential bytes are an AMWKEY1 text file or packed ICO, not a path. */ AMW_PREVIEW_API int32_t AMW_PREVIEW_CALL amw_preview_site_open_external( const char* origin_utf8, uint64_t origin_length, const uint8_t* credential, uint64_t credential_length, amw_preview_site** out, char* error, uint64_t error_capacity); AMW_PREVIEW_API void AMW_PREVIEW_CALL amw_preview_site_release(amw_preview_site* site); AMW_PREVIEW_API void AMW_PREVIEW_CALL amw_preview_site_cancel(amw_preview_site* site); AMW_PREVIEW_API int32_t AMW_PREVIEW_CALL amw_preview_site_resource_count( const amw_preview_site* site, uint64_t* out_count); AMW_PREVIEW_API int32_t AMW_PREVIEW_CALL amw_preview_site_entry_path( const amw_preview_site* site, char* output, uint64_t capacity, uint64_t* required); /* Empty for a public-only site. Use this to reject a member key file whose * embedded edition ID belongs to a different verified index. */ AMW_PREVIEW_API int32_t AMW_PREVIEW_CALL amw_preview_site_member_key_id( const amw_preview_site* site, char* output, uint64_t capacity, uint64_t* required); AMW_PREVIEW_API int32_t AMW_PREVIEW_CALL amw_preview_site_resource_path( const amw_preview_site* site, uint64_t index, char* output, uint64_t capacity, uint64_t* required); /* Full metadata for List-style callers. Length is the verified plaintext byte * count. String fields use the same caller-owned query/copy contract as paths. */ AMW_PREVIEW_API int32_t AMW_PREVIEW_CALL amw_preview_site_resource_length( const amw_preview_site* site, uint64_t index, uint64_t* out_length); AMW_PREVIEW_API int32_t AMW_PREVIEW_CALL amw_preview_site_resource_string( const amw_preview_site* site, uint64_t index, uint32_t field, char* output, uint64_t capacity, uint64_t* required); /* Caller selects an absolute path in a trusted local directory. The DLL * stages a new sibling file, verifies the full resource, and publishes only * if the destination is still absent. A member key is 32 raw bytes or NULL * with length 0 for public resources. An existing destination, including one * created during the operation, returns ALREADY_EXISTS. Never pass secrets * in process args. */ AMW_PREVIEW_API int32_t AMW_PREVIEW_CALL amw_preview_site_download( amw_preview_site* site, 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); AMW_PREVIEW_API int32_t AMW_PREVIEW_CALL amw_preview_site_download_operation( amw_preview_site* site, amw_preview_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); /* Read at most MEMORY_LIMIT verified plaintext bytes into caller memory. * NULL output with zero capacity queries the verified index length without * fetching the resource. A short buffer returns BUFFER_TOO_SMALL and reports * the required length without changing output or starting I/O. Other failures * clear *required and leave output unchanged. A member key has the same raw * 32-byte contract as site_download. The operation variant permits in-flight * cancellation; a query or short buffer consumes its single-use handle. */ AMW_PREVIEW_API int32_t AMW_PREVIEW_CALL amw_preview_site_read_memory( amw_preview_site* site, 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); AMW_PREVIEW_API int32_t AMW_PREVIEW_CALL amw_preview_site_read_memory_operation( amw_preview_site* site, amw_preview_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); /* A game handle pins the last fully verified index+catalogue pair. Refresh * stages a replacement; failure retains the previous pair. Calls other than * cancel require serialization. Call release only after in-flight calls return; * cancel may run from another thread. A cancelled refresh or fetch returns * AMW_PREVIEW_CANCELLED. */ AMW_PREVIEW_API int32_t AMW_PREVIEW_CALL amw_preview_game_create( const char* origin_utf8, uint64_t origin_length, const char* game_id_utf8, uint64_t game_id_length, const char* game_version_utf8, uint64_t game_version_length, amw_preview_game** out, char* error, uint64_t error_capacity); AMW_PREVIEW_API void AMW_PREVIEW_CALL amw_preview_game_release(amw_preview_game* game); AMW_PREVIEW_API void AMW_PREVIEW_CALL amw_preview_game_cancel(amw_preview_game* game); AMW_PREVIEW_API int32_t AMW_PREVIEW_CALL amw_preview_game_refresh_hosted( amw_preview_game* game, uint32_t allow_rollback, char* error, uint64_t error_capacity); AMW_PREVIEW_API int32_t AMW_PREVIEW_CALL amw_preview_game_refresh_hosted_operation( amw_preview_game* game, amw_preview_operation* operation, uint32_t allow_rollback, char* error, uint64_t error_capacity); AMW_PREVIEW_API int32_t AMW_PREVIEW_CALL amw_preview_game_refresh_external( amw_preview_game* game, const uint8_t* credential, uint64_t credential_length, uint32_t allow_rollback, char* error, uint64_t error_capacity); AMW_PREVIEW_API int32_t AMW_PREVIEW_CALL amw_preview_game_refresh_external_operation( amw_preview_game* game, amw_preview_operation* operation, const uint8_t* credential, uint64_t credential_length, uint32_t allow_rollback, char* error, uint64_t error_capacity); AMW_PREVIEW_API int32_t AMW_PREVIEW_CALL amw_preview_game_catalogue_revision( const amw_preview_game* game, uint64_t* out_revision); AMW_PREVIEW_API int32_t AMW_PREVIEW_CALL amw_preview_game_item_count( const amw_preview_game* game, uint64_t* out_count); AMW_PREVIEW_API int32_t AMW_PREVIEW_CALL amw_preview_game_item_string( const amw_preview_game* game, uint64_t item_index, uint32_t field, char* output, uint64_t capacity, uint64_t* required); AMW_PREVIEW_API int32_t AMW_PREVIEW_CALL amw_preview_game_index_digest( const amw_preview_game* game, char* output, uint64_t capacity, uint64_t* required); AMW_PREVIEW_API int32_t AMW_PREVIEW_CALL amw_preview_game_fetch_item( amw_preview_game* game, const char* item_id_utf8, uint64_t item_id_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); AMW_PREVIEW_API int32_t AMW_PREVIEW_CALL amw_preview_game_fetch_item_operation( amw_preview_game* game, amw_preview_operation* operation, const char* item_id_utf8, uint64_t item_id_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); #ifdef __cplusplus } #endif #endif