/*!
 * @header
 * Interfaces for manipulating Image4 firmware images.
 */
#ifndef __IMG4_IMAGE_H
#define __IMG4_IMAGE_H

#ifndef __IMG4_INDIRECT
#error "Please #include <img4/firmware.h> instead of this file directly"
#endif // __IMG4_INDIRECT

__BEGIN_DECLS
OS_ASSUME_NONNULL_BEGIN
OS_ASSUME_PTR_ABI_SINGLE_BEGIN

/*!
 * @function img4_image_get_bytes
 * Returns the authenticated payload from an Image4 image.
 *
 * @param image
 * The image to query. May be NULL.
 *
 * @result
 * A buffer which describes the authenticated payload. If the payload was not
 * authenticated, NULL is returned.
 */
#if !XNU_KERNEL_PRIVATE
IMG4_API_AVAILABLE_20200508
OS_EXPORT OS_WARN_RESULT
const img4_buff_t *_Nullable
img4_image_get_bytes(img4_image_t _Nullable image);
#else
#define img4_image_get_bytes(...) (img4if->i4if_v7.image_get_bytes(__VA_ARGS__))
#endif

/*!
 * @function img4_image_get_property_bool
 * Retrieves the Boolean value for the requested image property.
 *
 * @param image
 * The image to query.
 *
 * @param _4cc
 * The 4cc of the desired image property.
 *
 * @param storage
 * A pointer to storage for a Boolean value.
 *
 * @result
 * If the property is present for the image, a pointer to the storage provided
 * in {@link storage}. If the property is not present in the image or its value
 * is not a Boolean, NULL is returned.
 */
#if !XNU_KERNEL_PRIVATE
IMG4_API_AVAILABLE_20200508
OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL3
const bool *
img4_image_get_property_bool(img4_image_t image,
		img4_4cc_t _4cc,
		bool *storage);
#else
#define img4_image_get_property_bool(...) \
		(img4if->i4if_v7.image_get_property_bool(__VA_ARGS__))
#endif

/*!
 * @function img4_image_get_property_uint32
 * Retrieves the unsigned 32-bit integer value for the requested image property.
 *
 * @param image
 * The image to query.
 *
 * @param _4cc
 * The 4cc of the desired image property.
 *
 * @param storage
 * A pointer to storage for a 32-bit unsigned integer value.
 *
 * @result
 * If the property is present for the image, a pointer to the storage provided
 * in {@link storage}. If the property is not present in the image or its value
 * is not an unsigned 32-bit integer, NULL is returned.
 */
#if !XNU_KERNEL_PRIVATE
IMG4_API_AVAILABLE_20200508
OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL3
const uint32_t *
img4_image_get_property_uint32(img4_image_t image,
		img4_4cc_t _4cc,
		uint32_t *storage);
#else
#define img4_image_get_property_uint32(...) \
		(img4if->i4if_v7.image_get_property_uint32(__VA_ARGS__))
#endif

/*!
 * @function img4_image_get_property_uint64
 * Retrieves the unsigned 64-bit integer value for the requested image property.
 *
 * @param image
 * The image to query.
 *
 * @param _4cc
 * The 4cc of the desired image property.
 *
 * @param storage
 * A pointer to storage for a 64-bit unsigned integer value.
 *
 * @result
 * If the property is present for the image, a pointer to the storage provided
 * in {@link storage}. If the property is not present in the image or its value
 * is not an unsigned 64-bit integer, NULL is returned.
 */
#if !XNU_KERNEL_PRIVATE
IMG4_API_AVAILABLE_20200508
OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL3
const uint64_t *
img4_image_get_property_uint64(img4_image_t image,
		img4_4cc_t _4cc,
		uint64_t *storage);
#else
#define img4_image_get_property_uint64(...) \
		(img4if->i4if_v7.image_get_property_uint64(__VA_ARGS__))
#endif

/*!
 * @function img4_image_get_property_data
 * Retrieves the buffer value for the requested image property.
 *
 * @param image
 * The image to query.
 *
 * @param _4cc
 * The 4cc of the desired image property.
 *
 * @param storage
 * A pointer to storage for a buffer value.
 *
 * @result
 * If the property is present for the image, a pointer to the storage provided
 * in {@link storage}. If the property is not present in the image or its value
 * is not a data, NULL is returned.
 */
#if !XNU_KERNEL_PRIVATE
IMG4_API_AVAILABLE_20200508
OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL3
const img4_buff_t *
img4_image_get_property_data(img4_image_t image,
		img4_4cc_t _4cc,
		img4_buff_t *storage);
#else
#define img4_image_get_property_data(...) \
		(img4if->i4if_v7.image_get_property_data(__VA_ARGS__))
#endif

/*!
 * @function img4_image_get_entitlement_bool
 * Retrieves the Boolean value for the requested image entitlement.
 *
 * @param image
 * The image to query.
 *
 * @param _4cc
 * The 4cc of the desired image entitlement.
 *
 * @param storage
 * A pointer to storage for a Boolean value.
 *
 * @result
 * If the  entitlement is present for the image, a pointer to the storage
 * provided in {@link storage}. If the property is not present in the image or
 * its value is not a Boolean, NULL is returned.
 */
#if !XNU_KERNEL_PRIVATE
IMG4_API_AVAILABLE_20220513
OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL3
const bool *
img4_image_get_entitlement_bool(img4_image_t image,
		img4_4cc_t _4cc,
		bool *storage);
#else
#define img4_image_get_entitlement_bool(...) \
		(img4if->i4if_v18.image_get_entitlement_bool(__VA_ARGS__))
#endif

/*!
 * @function img4_image_get_entitlement_uint32
 * Retrieves the unsigned 32-bit integer value for the requested image
 * entitlement.
 *
 * @param image
 * The image to query.
 *
 * @param _4cc
 * The 4cc of the desired image entitlement.
 *
 * @param storage
 * A pointer to storage for a 32-bit unsigned integer value.
 *
 * @result
 * If the entitlement is present for the image, a pointer to the storage
 * provided in {@link storage}. If the property is not present in the image or
 * its value is not an unsigned 32-bit integer, NULL is returned.
 */
#if !XNU_KERNEL_PRIVATE
IMG4_API_AVAILABLE_20220513
OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL3
const uint32_t *
img4_image_get_entitlement_uint32(img4_image_t image,
		img4_4cc_t _4cc,
		uint32_t *storage);
#else
#define img4_image_get_entitlement_uint32(...) \
		(img4if->i4if_v18.image_get_entitlement_uint32(__VA_ARGS__))
#endif

/*!
 * @function img4_image_get_entitlement_uint64
 * Retrieves the unsigned 64-bit integer value for the requested image
 * entitlement.
 *
 * @param image
 * The image to query.
 *
 * @param _4cc
 * The 4cc of the desired image entitlement.
 *
 * @param storage
 * A pointer to storage for a 64-bit unsigned integer value.
 *
 * @result
 * If the entitlement is present for the image, a pointer to the storage
 * provided in {@link storage}. If the property is not present in the image or
 * its value is not an unsigned 64-bit integer, NULL is returned.
 */
#if !XNU_KERNEL_PRIVATE
IMG4_API_AVAILABLE_20220513
OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL3
const uint64_t *
img4_image_get_entitlement_uint64(img4_image_t image,
		img4_4cc_t _4cc,
		uint64_t *storage);
#else
#define img4_image_get_entitlement_uint64(...) \
		(img4if->i4if_v18.image_get_entitlement_uint64(__VA_ARGS__))
#endif

/*!
 * @function img4_image_get_entitlement_data
 * Retrieves the buffer value for the requested image entitlement.
 *
 * @param image
 * The image to query.
 *
 * @param _4cc
 * The 4cc of the desired image entitlement.
 *
 * @param storage
 * A pointer to storage for a buffer value.
 *
 * @result
 * If the entitlement is present for the image, a pointer to the storage
 * provided in {@link storage}. If the property is not present in the image or
 * its value is not a data, NULL is returned.
 */
#if !XNU_KERNEL_PRIVATE
IMG4_API_AVAILABLE_20220513
OS_EXPORT OS_WARN_RESULT OS_NONNULL1 OS_NONNULL3
const img4_buff_t *
img4_image_get_entitlement_data(img4_image_t image,
		img4_4cc_t _4cc,
		img4_buff_t *storage);
#else
#define img4_image_get_entitlement_data(...) \
		(img4if->i4if_v18.image_get_entitlement_data(__VA_ARGS__))
#endif

OS_ASSUME_PTR_ABI_SINGLE_END
OS_ASSUME_NONNULL_END
__END_DECLS

#endif // __IMG4_IMAGE_H