ITokens.h

Fully qualified name: carb/tokens/ITokens.h

File members: carb/tokens/ITokens.h

// SPDX-FileCopyrightText: Copyright (c) 2019-2025 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

#include "../Interface.h"
#include "../cpp/ZStringView.h"
#include "../cpp/StringView.h"
#include "../../omni/String.h"

#define carb_tokens_ITokens_latest CARB_HEXVERSION(1, 1)
#ifndef carb_tokens_ITokens
#    define carb_tokens_ITokens CARB_HEXVERSION(1, 0)
#endif

namespace carb
{
namespace tokens
{

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

enum class StringEndingMode
{
    eNullTerminator,
    eNoNullTerminator
};

using ResolveFlags = uint32_t;
const ResolveFlags kResolveFlagNone = 0;
const ResolveFlags kResolveFlagLeaveTokenIfNotFound = 1;

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

    bool(CARB_ABI* setValue)(const char* name, const char* value);

    void setInitialValue(const char* name, const char* value) const;

    bool removeToken(const char* name) const;

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

    size_t(CARB_ABI* calculateDestinationBufferSize)(const char* sourceBuf,
                                                     size_t sourceBufLen,
                                                     StringEndingMode endingMode,
                                                     ResolveFlags resolveFlags,
                                                     ResolveResult* resolveResult);

    bool(CARB_ABI* exists)(const char* tokenName);

#if CARB_VERSION_ATLEAST(carb_tokens_ITokens, 1, 1)

    // Extended interface functions (v1.1)
    bool(CARB_ABI* setValueS)(const cpp::zstring_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::zstring_view& tokenName);

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

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

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

#endif
};

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

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

} // namespace tokens
} // namespace carb