/*
 * Copyright 2025-2026 NVIDIA CORPORATION & AFFILIATES.  All rights reserved.
 *
 * NOTICE TO LICENSEE:
 *
 * This source code and/or documentation ("Licensed Deliverables") are
 * subject to NVIDIA intellectual property rights under U.S. and
 * international Copyright laws.
 *
 * These Licensed Deliverables contained herein is PROPRIETARY and
 * CONFIDENTIAL to NVIDIA and is being provided under the terms and
 * conditions of a form of NVIDIA software license agreement by and
 * between NVIDIA and Licensee ("License Agreement") or electronically
 * accepted by Licensee.  Notwithstanding any terms or conditions to
 * the contrary in the License Agreement, reproduction or disclosure
 * of the Licensed Deliverables to any third party without the express
 * written consent of NVIDIA is prohibited.
 *
 * NOTWITHSTANDING ANY TERMS OR CONDITIONS TO THE CONTRARY IN THE
 * LICENSE AGREEMENT, NVIDIA MAKES NO REPRESENTATION ABOUT THE
 * SUITABILITY OF THESE LICENSED DELIVERABLES FOR ANY PURPOSE.  IT IS
 * PROVIDED "AS IS" WITHOUT EXPRESS OR IMPLIED WARRANTY OF ANY KIND.
 * NVIDIA DISCLAIMS ALL WARRANTIES WITH REGARD TO THESE LICENSED
 * DELIVERABLES, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY,
 * NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE.
 * NOTWITHSTANDING ANY TERMS OR CONDITIONS TO THE CONTRARY IN THE
 * LICENSE AGREEMENT, IN NO EVENT SHALL NVIDIA BE LIABLE FOR ANY
 * SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, OR ANY
 * DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
 * WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
 * ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
 * OF THESE LICENSED DELIVERABLES.
 *
 * U.S. Government End Users.  These Licensed Deliverables are a
 * "commercial item" as that term is defined at 48 C.F.R. 2.101 (OCT
 * 1995), consisting of "commercial computer software" and "commercial
 * computer software documentation" as such terms are used in 48
 * C.F.R. 12.212 (SEPT 1995) and is provided to the U.S. Government
 * only as a commercial end item.  Consistent with 48 C.F.R.12.212 and
 * 48 C.F.R. 227.7202-1 through 227.7202-4 (JUNE 1995), all
 * U.S. Government End Users acquire the Licensed Deliverables with
 * only those rights set forth herein.
 *
 * Any use of the Licensed Deliverables in individual and commercial
 * software must include, in the user documentation and internal
 * comments to the code, the above Disclaimer and U.S. Government End
 * Users Notice.
 */

 #ifndef RESULTS_API_H
 #define RESULTS_API_H
 
 #include <stddef.h>
 #include <stdint.h>
 
 #include "../macros.h"
 #include "../types/cuest_types.h"
 #include "../types/cuest_result_types.h"
 #include "../types/workspace_api.h"
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 /**
  * @brief Create a new cuEST results object of the specified type.
  * @ingroup Results
  *
  * Allocates and initializes an opaque results object of the type specified by \c resultsType.
  * The created object is returned via \c outResults and must be destroyed with \c cuestResultsDestroy.
  *
  * @param[in]  resultsType      Type of results object to create (see \c cuestResultsType_t).
  * @param[out] outResults       Pointer to receive allocated opaque results handle. Must not be NULL.
  *
  * @return
  *   - \c CUEST_STATUS_SUCCESS on success;
  *   - \c CUEST_STATUS_NULL_POINTER if \c outResults is NULL;
  *   - \c CUEST_STATUS_INVALID_TYPE if \c resultsType is invalid;
  *   - \c CUEST_STATUS_EXCEPTION or \c CUEST_STATUS_UNKNOWN_ERROR for internal errors.
  *
  * @note On error, \c *outResults is set to NULL.
  */
 CUEST_API
 cuestStatus_t cuestResultsCreate(
     cuestResultsType_t resultsType,
     void** outResults);
 
 /**
  * @brief Destroy and free a cuEST results object of the specified type.
  * @ingroup Results
  *
  * Properly deallocates and cleans up resources for a results handle created by \c cuestResultsCreate.
  *
  * @param[in] resultsType    Type of results object (must match creation).
  * @param[in] results        Opaque results handle to destroy; must not be NULL.
  *
  * @return
  *   - \c CUEST_STATUS_SUCCESS on success;
  *   - \c CUEST_STATUS_NULL_POINTER if \c results is NULL;
  *   - \c CUEST_STATUS_INVALID_TYPE if \c resultsType does not match the actual type of \c results;
  *   - \c CUEST_STATUS_EXCEPTION or \c CUEST_STATUS_UNKNOWN_ERROR for internal errors.
  */
 CUEST_API
 cuestStatus_t cuestResultsDestroy(
     cuestResultsType_t resultsType,
     void* results);
 
 /**
  * @brief Query the value of a given attribute from a cuEST results object.
  * @ingroup Results
  *
  * Retrieves the value associated with an attribute for the given \c results object. The type and meaning
  * of \c results and \c resultValue depend on \c resultsType. The result is placed in \c resultValue, whose
  * size must match the expected value size.
  *
  * @param[in]  resultsType      Type of results object being queried.
  * @param[in]  results          Opaque handle of the results object (must not be NULL).
  * @param[in]  attribute        Integer attribute identifier (cast to appropriate attribute enum internally).
  * @param[out] resultValue      Destination for the queried value (must not be NULL).
  * @param[in]  resultValueSize  Size in bytes of \c resultValue buffer (must match queried type).
  *
  * @return
  *   - \c CUEST_STATUS_SUCCESS on success;
  *   - \c CUEST_STATUS_NULL_POINTER if \c results or \c resultValue is NULL;
  *   - \c CUEST_STATUS_INVALID_TYPE if \c results is not of the specified \c resultsType;
  *   - \c CUEST_STATUS_INVALID_SIZE if \c resultValueSize does not match attribute type size;
  *   - \c CUEST_STATUS_INVALID_ATTRIBUTE if \c attribute is not recognized;
  *   - \c CUEST_STATUS_EXCEPTION or \c CUEST_STATUS_UNKNOWN_ERROR for internal errors.
  */
 CUEST_API
 cuestStatus_t cuestResultsQuery(
     cuestResultsType_t resultsType,
     const void* results,
     int attribute,
     void* resultValue,
     size_t resultValueSize);
 
 #ifdef __cplusplus
 }
 #endif
 
 #endif /* RESULTS_API_H */
 
