/*
 * Copyright (C) 2024-2025 Intel Corporation
 *
 * Under the Apache License v2.0 with LLVM Exceptions. See LICENSE.TXT.
 * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
*/

#ifndef UMF_FILE_MEMORY_PROVIDER_H
#define UMF_FILE_MEMORY_PROVIDER_H

#include <umf/memory_provider.h>

#ifdef __cplusplus
extern "C" {
#endif

/// @cond
#define UMF_FILE_RESULTS_START_FROM 3000
/// @endcond

struct umf_file_memory_provider_params_t;

typedef struct umf_file_memory_provider_params_t
    *umf_file_memory_provider_params_handle_t;

/// @brief  Create a struct to store parameters of the File Memory Provider.
/// @param  path path to the file.
/// @param  hParams [out] handle to the newly created parameters struct.
/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
umf_result_t umfFileMemoryProviderParamsCreate(
    const char *path, umf_file_memory_provider_params_handle_t *hParams);

/// @brief  Destroy parameters struct.
/// @param  hParams handle to the parameters of the File Memory Provider.
/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
umf_result_t umfFileMemoryProviderParamsDestroy(
    umf_file_memory_provider_params_handle_t hParams);

/// @brief  Set the path in the parameters struct.
/// @param  hParams handle to the parameters of the File Memory Provider.
/// @param  path path to the file.
/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
umf_result_t umfFileMemoryProviderParamsSetPath(
    umf_file_memory_provider_params_handle_t hParams, const char *path);

/// @brief  Set the protection in the parameters struct.
/// @param  hParams handle to the parameters of the File Memory Provider.
/// @param  protection protection. Combination of \p umf_mem_protection_flags_t flags
/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
umf_result_t umfFileMemoryProviderParamsSetProtection(
    umf_file_memory_provider_params_handle_t hParams, unsigned protection);

/// @brief  Set the visibility in the parameters struct.
/// @param  hParams handle to the parameters of the File Memory Provider.
/// @param  visibility memory visibility mode.
/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
umf_result_t umfFileMemoryProviderParamsSetVisibility(
    umf_file_memory_provider_params_handle_t hParams,
    umf_memory_visibility_t visibility);

/// @brief File Memory Provider operation results
typedef enum umf_file_memory_provider_native_error {
    UMF_FILE_RESULT_SUCCESS = UMF_FILE_RESULTS_START_FROM, ///< Success
    UMF_FILE_RESULT_ERROR_ALLOC_FAILED,       ///< Memory allocation failed
    UMF_FILE_RESULT_ERROR_FREE_FAILED,        ///< Memory deallocation failed
    UMF_FILE_RESULT_ERROR_PURGE_FORCE_FAILED, ///< Force purging failed
} umf_file_memory_provider_native_error_t;

const umf_memory_provider_ops_t *umfFileMemoryProviderOps(void);

/// @brief  Set custom name of the File Memory Provider.
/// @param  hParams handle to the parameters of the File Memory Provider.
/// @param  name custom name. Must not be NULL. Name longer than 63 characters
///         will be truncated.
/// \details Name should contain only [a-zA-Z0-9_-] characters.
/// Other names are deprecated and may limit CTL functionality.
/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
umf_result_t umfFileMemoryProviderParamsSetName(
    umf_file_memory_provider_params_handle_t hParams, const char *name);

#ifdef __cplusplus
}
#endif

#endif /* UMF_FILE_MEMORY_PROVIDER_H */
