/*
 * Copyright 2024 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#pragma once

#include <stddef.h>
#include <stdint.h>

//! @file applib_resource.h
//! Wrapper functions for the resource syscalls. These functions give us a nice interface to export to 3rd party apps.

//! @addtogroup Foundation
//! @{
//!   @addtogroup Resources
//! \brief Managing application resources
//!
//! Resources are data files that are bundled with your application binary and can be
//! loaded at runtime. You use resources to embed images or custom fonts in your app,
//! but also to embed any data file. Resources are always read-only.
//!
//! Resources are stored on Pebble’s flash memory and only loaded in RAM when you load
//! them. This means that you can have a large number of resources embedded inside your app,
//! even though Pebble’s RAM memory is very limited.
//!
//! See \htmlinclude UsingResources.html for information on how to embed
//! resources into your app's bundle.

//!
//!   @{

#define RESOURCE_ID_FONT_FALLBACK RESOURCE_ID_GOTHIC_14

//! Opaque reference to a resource.
//! @see \ref resource_get_handle()
typedef void * ResHandle;

//! Gets the resource handle for a file identifier.
//! @param resource_id The resource ID
//!
//! The resource IDs are auto-generated by the Pebble build process, based
//! on the `appinfo.json`. The "name" field of each resource is prefixed
//! by `RESOURCE_ID_` and made visible to the application (through the
//! `build/src/resource_ids.auto.h` header which is automatically included).
//!
//! For example, given the following fragment of `appinfo.json`:
//! \code{.json}
//!   ...
//!   "resources" : {
//!     "media": [
//!        {
//!           "name": "MY_ICON",
//!           "file": "img/icon.png",
//!           "type": "png",
//!        },
//!    ...
//! \endcode
//! The generated file identifier for this resource is `RESOURCE_ID_MY_ICON`.
//! To get a resource handle for that resource write:
//! \code{.c}
//! ResHandle rh = resource_get_handle(RESOURCE_ID_MY_ICON);
//! \endcode
ResHandle applib_resource_get_handle(uint32_t resource_id);

//! Gets the size of the resource given a resource handle.
//! @param h The handle to the resource
//! @return The size of the resource in bytes
size_t applib_resource_size(ResHandle h);

//! Copies the bytes for the resource with a given handle from flash storage into a given buffer.
//! @param h The handle to the resource
//! @param buffer The buffer to load the resource data into
//! @param max_length The maximum number of bytes to copy
//! @return The number of bytes actually copied
size_t applib_resource_load(ResHandle h, uint8_t *buffer, size_t max_length);

//! Copies a range of bytes from a resource with a given handle into a given buffer.
//! @param h The handle to the resource
//! @param start_offset The offset in bytes at which to start reading from the resource
//! @param buffer The buffer to load the resource data into
//! @param num_bytes The maximum number of bytes to copy
//! @return The number of bytes actually copied
size_t applib_resource_load_byte_range(
    ResHandle h, uint32_t start_offset, uint8_t *buffer, size_t num_bytes);

//!   @} // end addtogroup Resources
//! @} // end addtogroup Foundation