ITokens1.h

Fully qualified name: carb/tokens/detail/ITokens1.h

File members: carb/tokens/detail/ITokens1.h

// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: LicenseRef-NvidiaProprietary
//
// NVIDIA CORPORATION, its affiliates and licensors retain all intellectual
// property and proprietary rights in and to this material, related
// documentation and any modifications thereto. Any use, reproduction,
// disclosure or distribution of this material and related documentation
// without an express license agreement from NVIDIA CORPORATION or
// its affiliates is strictly prohibited.

#pragma once

#ifndef carb_tokens_ITokens_latest
#    error Must include via ../ITokens.h
#endif

#if CARB_VERSION_ATLEAST(carb_tokens_ITokens, 2, 0)
#    error Version too high to be included
#endif

#ifndef CARB_TOKENS_DEPRECATIONS
#    define CARB_TOKENS_DEPRECATIONS 1
#endif

#if CARB_TOKENS_DEPRECATIONS && CARB_VERSION_ATLEAST(carb_tokens_ITokens, 1, 1)
#    define CARB_TOKENS_DEPRECATED(msg) CARB_DEPRECATED(msg)
#else
#    define CARB_TOKENS_DEPRECATED(msg)
#endif

namespace carb::tokens
{

#ifndef DOXYGEN_BUILD
inline namespace v1
{
#endif

enum class ResolveResult
{
    eSuccess,
    eTruncated,
    eFailure,
};

enum class StringEndingMode
{
    eNullTerminator,
    eNoNullTerminator
};

struct ITokens
{
    // 1.0 - Initial release
    // 1.1 - added string_view-based functions
    CARB_PLUGIN_INTERFACE_EX("carb::tokens::ITokens", carb_tokens_ITokens_latest, carb_tokens_ITokens)
    // Ensure proper initialization order
    // Members must be declared in the same sequence as initialized

    CARB_TOKENS_DEPRECATED("Use setValueS instead")
    bool(CARB_ABI* setValue)(const char* name, const char* value);

    CARB_TOKENS_DEPRECATED("Use setInitialValueS instead")
    void setInitialValue(const char* name, const char* value) const;

    CARB_TOKENS_DEPRECATED("Use deleteValueS instead")
    bool removeToken(const char* name) const;

    CARB_TOKENS_DEPRECATED("Use resolveStringS instead")
    ResolveResult(CARB_ABI* resolveString)(const char* sourceBuf,
                                           size_t sourceBufLen,
                                           char* destBuf,
                                           size_t destBufLen,
                                           StringEndingMode endingMode,
                                           ResolveFlags resolveFlags,
                                           size_t* resolvedSize);

    CARB_TOKENS_DEPRECATED("Use calculateDestinationBufferSizeS instead")
    size_t(CARB_ABI* calculateDestinationBufferSize)(const char* sourceBuf,
                                                     size_t sourceBufLen,
                                                     StringEndingMode endingMode,
                                                     ResolveFlags resolveFlags,
                                                     ResolveResult* resolveResult);

    CARB_TOKENS_DEPRECATED("Use existsS instead")
    bool(CARB_ABI* exists)(const char* tokenName);

    // Extended interface functions (v1.1)
#if CARB_VERSION_ATLEAST(carb_tokens_ITokens, 1, 1)
    bool(CARB_ABI* setValueS)(const cpp::string_view& name, const cpp::string_view& value);

    ResolveResult(CARB_ABI* resolveStringS)(const cpp::string_view& sourceBuf,
                                            omni::string& destBuf,
                                            ResolveFlags resolveFlags);

    bool(CARB_ABI* existsS)(const cpp::string_view& tokenName);

    bool(CARB_ABI* deleteValueS)(const cpp::string_view& name);

    size_t(CARB_ABI* calculateDestinationBufferSizeS)(const cpp::string_view& sourceBuf,
                                                      StringEndingMode endingMode,
                                                      ResolveFlags resolveFlags,
                                                      ResolveResult* resolveResult);

    void setInitialValueS(cpp::string_view name, cpp::string_view value) const
    {
        CARB_IGNORE_DEPRECATION_BEGIN
        if (!existsS(name))
        {
            setValueS(name, value);
        }
        CARB_IGNORE_DEPRECATION_END
    }

#endif
};

inline void ITokens::setInitialValue(const char* name, const char* value) const
{
    CARB_IGNORE_DEPRECATION_BEGIN
    if (!exists(name) && value)
    {
        setValue(name, value);
    }
    CARB_IGNORE_DEPRECATION_END
}

inline bool ITokens::removeToken(const char* name) const
{
    CARB_IGNORE_DEPRECATION_BEGIN
    return setValue(name, nullptr);
    CARB_IGNORE_DEPRECATION_END
}

#ifndef DOXYGEN_BUILD
} // namespace v1
#endif

} // namespace carb::tokens