Open 3D Engine AzCore API Reference 23.10.0
O3DE is an open-source, fully-featured, high-fidelity, modular 3D engine for building games and simulations, available to every industry.
AZ::SettingsRegistryInterface Class Referenceabstract

#include <SettingsRegistry.h>

Inherited by AZ::MockSettingsRegistry, and AZ::SettingsRegistryImpl.

Classes

struct  CommandLineArgumentSettings
 
struct  MergeEventArgs
 
struct  MergeSettingsResult
 
struct  NotifyEventArgs
 
struct  SettingsType
 Encapsulate stored value and its signedness. More...
 
class  Specializations
 
struct  VisitArgs
 
class  Visitor
 

Public Types

enum class  Type {
  NoType , Null , Boolean , Integer ,
  FloatingPoint , String , Array , Object
}
 Type of the store value, or None if there's no value stored.
 
enum class  Signedness { None , Signed , Unsigned }
 Type of an integer.
 
enum class  VisitResponse { Continue , Skip , Done }
 The response to let the visit call know what to do next. More...
 
enum class  VisitAction { Begin , Value , End }
 The action the visit call is taken. More...
 
enum class  Format { JsonPatch , JsonMergePatch }
 File formats supported to load settings from. More...
 
enum class  MergeSettingsReturnCode { Unset = 0 , Success = 1 , PartialSuccess , Failure = -1 }
 
using FixedValueString = AZ::StringFunc::Path::FixedString
 
using FilenameTags = Specializations
 
using NotifyCallback = AZStd::function< void(const NotifyEventArgs &notifierArgs)>
 
using NotifyEvent = AZ::Event< const NotifyEventArgs & >
 
using NotifyEventHandler = typename NotifyEvent::Handler
 
using PreMergeEventCallback = AZStd::function< void(const MergeEventArgs &)>
 
using PostMergeEventCallback = AZStd::function< void(const MergeEventArgs &)>
 
using PreMergeEvent = AZ::Event< const MergeEventArgs & >
 
using PostMergeEvent = AZ::Event< const MergeEventArgs & >
 
using PreMergeEventHandler = typename PreMergeEvent::Handler
 
using PostMergeEventHandler = typename PostMergeEvent::Handler
 
using VisitorCallback = AZStd::function< VisitResponse(const VisitArgs &, VisitAction action)>
 

Public Member Functions

 AZ_RTTI (AZ::SettingsRegistryInterface, "{D62619D8-0C0B-4D9F-9FE8-F8EBC330DC55}")
 
 AZ_DISABLE_COPY_MOVE (SettingsRegistryInterface)
 
virtual SettingsType GetType (AZStd::string_view path) const =0
 Returns the type of an entry in the Settings Registry or Type::None if there's no value or the path is invalid.
 
virtual bool Visit (Visitor &visitor, AZStd::string_view path) const =0
 
virtual bool Visit (const VisitorCallback &callback, AZStd::string_view path) const =0
 
virtual NotifyEventHandler RegisterNotifier (NotifyCallback callback)=0
 
virtual void RegisterNotifier (NotifyEventHandler &handler)=0
 
virtual PreMergeEventHandler RegisterPreMergeEvent (PreMergeEventCallback callback)=0
 
virtual void RegisterPreMergeEvent (PreMergeEventHandler &handler)=0
 
virtual PostMergeEventHandler RegisterPostMergeEvent (PostMergeEventCallback callback)=0
 
virtual void RegisterPostMergeEvent (PostMergeEventHandler &handler)=0
 
virtual bool Get (bool &result, AZStd::string_view path) const =0
 
virtual bool Get (s64 &result, AZStd::string_view path) const =0
 
virtual bool Get (u64 &result, AZStd::string_view path) const =0
 
virtual bool Get (double &result, AZStd::string_view path) const =0
 
virtual bool Get (AZStd::string &result, AZStd::string_view path) const =0
 
virtual bool Get (FixedValueString &result, AZStd::string_view path) const =0
 
virtual bool GetObject (void *result, AZ::Uuid resultTypeId, AZStd::string_view path) const =0
 
template<typename T >
bool GetObject (T &result, AZStd::string_view path) const
 
virtual bool Set (AZStd::string_view path, bool value)=0
 
virtual bool Set (AZStd::string_view path, s64 value)=0
 
virtual bool Set (AZStd::string_view path, u64 value)=0
 
virtual bool Set (AZStd::string_view path, double value)=0
 
virtual bool Set (AZStd::string_view path, AZStd::string_view value)=0
 
virtual bool Set (AZStd::string_view path, const char *value)=0
 
virtual bool SetObject (AZStd::string_view path, const void *value, AZ::Uuid valueTypeId)=0
 
template<typename T >
bool SetObject (AZStd::string_view path, const T &value)
 
virtual bool Remove (AZStd::string_view path)=0
 
virtual bool MergeCommandLineArgument (AZStd::string_view argument, AZStd::string_view anchorKey="", const CommandLineArgumentSettings &commandLineSettings={})=0
 
virtual MergeSettingsResult MergeSettings (AZStd::string_view data, Format format, AZStd::string_view anchorKey="")=0
 
virtual MergeSettingsResult MergeSettingsFile (AZStd::string_view path, Format format, AZStd::string_view anchorKey="", AZStd::vector< char > *scratchBuffer=nullptr)=0
 
virtual MergeSettingsResult MergeSettingsFolder (AZStd::string_view path, const Specializations &specializations, AZStd::string_view platform={}, AZStd::string_view anchorKey="", AZStd::vector< char > *scratchBuffer=nullptr)=0
 
virtual void SetNotifyForMergeOperations (bool notify)=0
 
virtual bool GetNotifyForMergeOperations () const =0
 
virtual void SetUseFileIO (bool useFileIo)=0
 

Static Public Attributes

static constexpr char Extension [] = "setreg"
 
static constexpr char PatchExtension [] = "setregpatch"
 
static constexpr char RegistryFolder [] = "Registry"
 
static constexpr char DevUserRegistryFolder [] = "user" AZ_CORRECT_FILESYSTEM_SEPARATOR_STRING "Registry"
 
static constexpr char PlatformFolder [] = "Platform"
 

Detailed Description

The Settings Registry is the central storage for global settings. Having application-wide settings stored in a central location allows different tools such as command lines, consoles, configuration files, etc. to work in a universal way. Paths in the functions for the Settings Registry follow the the JSON Pointer pattern (see https://tools.ietf.org/html/rfc6901) such as "/My/Object/Settings" or "/My/Array/0".

Member Typedef Documentation

◆ FixedValueString

Represents a fixed size non-allocating string type that can be used to query the settings registry using Get() If the value is longer than FixedValueString::max_size(), then either the heap allocating AZStd::string overload must be used or the Visit method must be used

Member Enumeration Documentation

◆ Format

File formats supported to load settings from.

Enumerator
JsonPatch 

Using the json patch format to merge JSON data into the Settings Registry.

JsonMergePatch 

Using the json merge patch format to merge JSON data into the Settings Registry.

◆ MergeSettingsReturnCode

List of possible return codes from MergeSettings/MergeSettingsFolder The unset value is always 0 Failure values should be < 0 and success values > 0

◆ VisitAction

The action the visit call is taken.

Enumerator
Begin 

Begins iterating over the elements of an object or the values in an array.

Value 

Reports a value.

End 

Ends the iteration over the elements of an object or the values in an array.

◆ VisitResponse

The response to let the visit call know what to do next.

Enumerator
Continue 

Continue visiting.

Skip 

Skip descending into value. This only applies to objects and arrays.

Done 

Stop traversing the Setting Registry.

Member Function Documentation

◆ Get() [1/4]

virtual bool AZ::SettingsRegistryInterface::Get ( AZStd::string result,
AZStd::string_view  path 
) const
pure virtual

Gets the string value at the provided path.

Parameters
resultThe target to write the result to.
pathThe path to the value.
Returns
Whether or not the value was retrieved. An invalid path or type-mismatch will return false;

Implemented in AZ::SettingsRegistryImpl.

◆ Get() [2/4]

virtual bool AZ::SettingsRegistryInterface::Get ( bool &  result,
AZStd::string_view  path 
) const
pure virtual

Gets the boolean value at the provided path.

Parameters
resultThe target to write the result to.
pathThe path to the value.
Returns
Whether or not the value was retrieved. An invalid path or type-mismatch will return false;

Implemented in AZ::SettingsRegistryImpl.

◆ Get() [3/4]

virtual bool AZ::SettingsRegistryInterface::Get ( double &  result,
AZStd::string_view  path 
) const
pure virtual

Gets the floating point value at the provided path.

Parameters
resultThe target to write the result to.
pathThe path to the value.
Returns
Whether or not the value was retrieved. An invalid path or type-mismatch will return false;

Implemented in AZ::SettingsRegistryImpl.

◆ Get() [4/4]

virtual bool AZ::SettingsRegistryInterface::Get ( s64 &  result,
AZStd::string_view  path 
) const
pure virtual

Gets the integer value at the provided path.

Parameters
resultThe target to write the result to.
pathThe path to the value.
Returns
Whether or not the value was retrieved. An invalid path or type-mismatch will return false;

Implemented in AZ::SettingsRegistryImpl.

◆ GetNotifyForMergeOperations()

virtual bool AZ::SettingsRegistryInterface::GetNotifyForMergeOperations ( ) const
pure virtual
Returns
returns true if merge operations signals the notification events

Implemented in AZ::SettingsRegistryImpl.

◆ GetObject() [1/2]

template<typename T >
bool AZ::SettingsRegistryInterface::GetObject ( T &  result,
AZStd::string_view  path 
) const
inline

Gets the json object value at the provided path serialized to the target struct/class. Classes retrieved through this call needs to be registered with the Serialize Context.

Parameters
resultThe target to write the result to.
pathThe path to the value.
Returns
Whether or not the value was stored. An invalid path will return false;

◆ GetObject() [2/2]

virtual bool AZ::SettingsRegistryInterface::GetObject ( void *  result,
AZ::Uuid  resultTypeId,
AZStd::string_view  path 
) const
pure virtual

Gets the object value at the provided path serialized to the target struct/class. Classes retrieved through this call needs to be registered with the Serialize Context. Prefer to use GetObject(T& result, AZStd::string_view path) over this one.

Parameters
resultThe target to write the result to.
resultTypeIdThe type id of the target that's being written to.
pathThe path to the value.
Returns
Whether or not the value was stored. An invalid path will return false;

Implemented in AZ::SettingsRegistryImpl.

◆ GetType()

virtual SettingsType AZ::SettingsRegistryInterface::GetType ( AZStd::string_view  path) const
pure virtual

Returns the type of an entry in the Settings Registry or Type::None if there's no value or the path is invalid.

Implemented in AZ::SettingsRegistryImpl.

◆ MergeCommandLineArgument()

virtual bool AZ::SettingsRegistryInterface::MergeCommandLineArgument ( AZStd::string_view  argument,
AZStd::string_view  anchorKey = "",
const CommandLineArgumentSettings commandLineSettings = {} 
)
pure virtual

Merges a single command line argument into the settings registry. Command line arguments take the form of <path>=

for instance: "/My/Path=My string value" Values are interpreted as follows:

  • "true" (case sensitive) -> boolean with true value
  • "false" (case sensitive) -> boolean with false value
  • all digits -> number
  • all digits and dot -> floating point number
  • Everything else is considered a string.
    Parameters
    argumentThe command line argument.
    anchorKeyThe key where the merged command line argument will be anchored under
    commandLineSettingsstructure which contains functors which determine what characters are delimiters
    Returns
    True if the command line argument could be parsed, otherwise false.

Implemented in AZ::SettingsRegistryImpl.

◆ MergeSettings()

virtual MergeSettingsResult AZ::SettingsRegistryInterface::MergeSettings ( AZStd::string_view  data,
Format  format,
AZStd::string_view  anchorKey = "" 
)
pure virtual

Merges the json data provided into the settings registry.

Parameters
dataThe json data stored in a string.
formatThe format of the provided data.
anchorKeyThe key where the merged json content will be anchored under.
Returns
MergeSettingsResult value that is convertible to bool(true) if the data was successfully merged. If the json string was not merged successfully, the MergeSettingsResult::GetMessages() function contains messages around why the operation has failed.

Implemented in AZ::SettingsRegistryImpl.

◆ MergeSettingsFile()

virtual MergeSettingsResult AZ::SettingsRegistryInterface::MergeSettingsFile ( AZStd::string_view  path,
Format  format,
AZStd::string_view  anchorKey = "",
AZStd::vector< char > *  scratchBuffer = nullptr 
)
pure virtual

Loads a settings file and merges it into the registry.

Parameters
pathThe path to the registry file.
formatThe format of the text data in the file at the provided path.
anchorKeyThe key where the content of the settings file will be anchored.
scratchBufferAn optional buffer that's used to load the file into. Use this when loading multiple patches to reduce the number of intermediate memory allocations.
Returns
MergeSettingsResult value that is convertible to bool(true) if the registry file was successfully merged. If the file is is not merged successfully the MergeSettingsResult messages structure will be populated with error messages of why the operation failed

Implemented in AZ::SettingsRegistryImpl.

◆ MergeSettingsFolder()

virtual MergeSettingsResult AZ::SettingsRegistryInterface::MergeSettingsFolder ( AZStd::string_view  path,
const Specializations specializations,
AZStd::string_view  platform = {},
AZStd::string_view  anchorKey = "",
AZStd::vector< char > *  scratchBuffer = nullptr 
)
pure virtual

Loads all settings files in a folder and merges them into the registry. With the specializations "a" and "b" and platform "c" the files would be loaded in the order:

  • file1.setreg
  • Platform/c/file1.setreg
  • file1.a.setreg
  • Platform/c/file.b.setreg
  • file1.a.b.setreg
  • file2.setreg
    Parameters
    pathThe path to the registry folder.
    specializationsThe specializations that will be used filter out registry files.
    platformAn optional name of a platform. Platform overloads are located at <path>/Platform/<platform>/ Files in a platform are applied in the same order as for the main folder but always after the same file in the main folder.
    anchorKeyThe registry path location where the settings will be anchored
    scratchBufferAn optional buffer that's used to load the file into. Use this when loading multiple patches to reduce the number of intermediate memory allocations.
    Returns
    MergeSettingsResult value that is convertible to bool(true) if the registry folder was successfully merged.

Implemented in AZ::SettingsRegistryImpl.

◆ RegisterNotifier() [1/2]

virtual NotifyEventHandler AZ::SettingsRegistryInterface::RegisterNotifier ( NotifyCallback  callback)
pure virtual

Register a callback that will be called whenever an entry gets a new/updated value.

@callback The function to call when an entry gets a new/updated value.

Returns
NotifyEventHandler instance which must persist to receive event signal

Implemented in AZ::SettingsRegistryImpl.

◆ RegisterNotifier() [2/2]

virtual void AZ::SettingsRegistryInterface::RegisterNotifier ( NotifyEventHandler &  handler)
pure virtual

Register a notify event handler with the NotifyEvent. The handler will be called whenever an entry gets a new/updated value.

Parameters
handlerThe handler to register with the NotifyEvent.

Implemented in AZ::SettingsRegistryImpl.

◆ RegisterPostMergeEvent() [1/2]

virtual PostMergeEventHandler AZ::SettingsRegistryInterface::RegisterPostMergeEvent ( PostMergeEventCallback  callback)
pure virtual

Register a function that will be called after a file is merged.

Parameters
callbackThe function to call after a file is merged.
Returns
PostMergeEventHandler instance which must persist to receive event signal

Implemented in AZ::SettingsRegistryImpl.

◆ RegisterPostMergeEvent() [2/2]

virtual void AZ::SettingsRegistryInterface::RegisterPostMergeEvent ( PostMergeEventHandler &  handler)
pure virtual

Register a post-merge hahndler with the PostMergeEvent. The handler will be called after a file is merged.

Parameters
handlerThe handler to register with the PostmergeEVent.

Implemented in AZ::SettingsRegistryImpl.

◆ RegisterPreMergeEvent() [1/2]

virtual PreMergeEventHandler AZ::SettingsRegistryInterface::RegisterPreMergeEvent ( PreMergeEventCallback  callback)
pure virtual

Register a function that will be called before a file is merged.

Parameters
callbackThe function to call before a file is merged.
Returns
PreMergeEventHandler instance which must persist to receive event signal

Implemented in AZ::SettingsRegistryImpl.

◆ RegisterPreMergeEvent() [2/2]

virtual void AZ::SettingsRegistryInterface::RegisterPreMergeEvent ( PreMergeEventHandler &  handler)
pure virtual

Register a pre-merge handler with the PreMergeEvent. The handler will be called before a file is merged.

Parameters
handlerThe hanlder to register with the PreMergeEvent.

Implemented in AZ::SettingsRegistryImpl.

◆ Remove()

virtual bool AZ::SettingsRegistryInterface::Remove ( AZStd::string_view  path)
pure virtual

Remove the value at the provided path

Parameters
pathThe path to a value that should be removed
Returns
Whether or not the path was found and removed. An invalid path will return false;

Implemented in AZ::SettingsRegistryImpl.

◆ Set() [1/5]

virtual bool AZ::SettingsRegistryInterface::Set ( AZStd::string_view  path,
AZStd::string_view  value 
)
pure virtual

Sets or replaces the string value at the provided path.

Parameters
pathThe path to the value.
valueThe new value to store.
Returns
Whether or not the value was stored. An invalid path will return false;

Implemented in AZ::SettingsRegistryImpl.

◆ Set() [2/5]

virtual bool AZ::SettingsRegistryInterface::Set ( AZStd::string_view  path,
bool  value 
)
pure virtual

Sets or replaces the boolean value at the provided path.

Parameters
pathThe path to the value.
valueThe new value to store.
Returns
Whether or not the value was stored. An invalid path will return false;

Implemented in AZ::SettingsRegistryImpl.

◆ Set() [3/5]

virtual bool AZ::SettingsRegistryInterface::Set ( AZStd::string_view  path,
const char *  value 
)
pure virtual

Sets or replaces the string value at the provided path. Note that this overload was added as the compiler considers boolean a more closer match than string_view.

Parameters
pathThe path to the value.
valueThe new value to store.
Returns
Whether or not the value was stored. An invalid path will return false;

Implemented in AZ::SettingsRegistryImpl.

◆ Set() [4/5]

virtual bool AZ::SettingsRegistryInterface::Set ( AZStd::string_view  path,
double  value 
)
pure virtual

Sets or replaces the floating point value at the provided path.

Parameters
pathThe path to the value.
valueThe new value to store.
Returns
Whether or not the value was stored. An invalid path will return false;

Implemented in AZ::SettingsRegistryImpl.

◆ Set() [5/5]

virtual bool AZ::SettingsRegistryInterface::Set ( AZStd::string_view  path,
s64  value 
)
pure virtual

Sets or replaces the integer value at the provided path.

Parameters
pathThe path to the value.
valueThe new value to store.
Returns
Whether or not the value was stored. An invalid path will return false;

Implemented in AZ::SettingsRegistryImpl.

◆ SetNotifyForMergeOperations()

virtual void AZ::SettingsRegistryInterface::SetNotifyForMergeOperations ( bool  notify)
pure virtual

Indicates whether the Merge functions should send notification events for individual operations using JSON Patch or JSON Merge Patch.

Parameters
notifyIf true, the patching operations are forwarded through the NotifyEvent

Implemented in AZ::SettingsRegistryImpl.

◆ SetObject() [1/2]

template<typename T >
bool AZ::SettingsRegistryInterface::SetObject ( AZStd::string_view  path,
const T &  value 
)
inline

Sets the value at the provided path to the serialized version of the provided struct/class. Classes used for this call need to be registered with the Serialize Context.

Parameters
pathThe path to the value.
valueThe new value to store.
Returns
Whether or not the value was stored. An invalid path will return false;

◆ SetObject() [2/2]

virtual bool AZ::SettingsRegistryInterface::SetObject ( AZStd::string_view  path,
const void *  value,
AZ::Uuid  valueTypeId 
)
pure virtual

Sets the value at the provided path to the serialized version of the provided struct/class. Classes used for this call need to be registered with the Serialize Context. Prefer to use SetObject(AZStd::string_view path, const T& result) over this one.

Parameters
pathThe path to the value.
valueThe new value to store.
valueTypeIdThe type id of the target that's being stored.
Returns
Whether or not the value was stored. An invalid path will return false;

Implemented in AZ::SettingsRegistryImpl.

◆ SetUseFileIO()

virtual void AZ::SettingsRegistryInterface::SetUseFileIO ( bool  useFileIo)
pure virtual

Stores option to indicate whether the FileIOBase instance should be used for file operations

Parameters
useFileIoIf true the FileIOBase instance will attempted to be used for FileIOBase operations before falling back to use SystemFile

Implemented in AZ::SettingsRegistryImpl.

◆ Visit() [1/2]

virtual bool AZ::SettingsRegistryInterface::Visit ( const VisitorCallback callback,
AZStd::string_view  path 
) const
pure virtual

Traverses over the entries in the Settings Registry. Use this version if only the names and/or types are needed.

Parameters
callbackA callback function that will repeatedly be called as entries are encountered.
pathAn offset at which traversal should start.
Returns
Whether or not entries could be visited.

Implemented in AZ::SettingsRegistryImpl.

◆ Visit() [2/2]

virtual bool AZ::SettingsRegistryInterface::Visit ( Visitor visitor,
AZStd::string_view  path 
) const
pure virtual

Traverses over the entries in the Settings Registry. Use this version to retrieve the values of entries as well.

Parameters
visitorAn instance of a class derived from Visitor that will repeatedly be called as entries are encountered.
pathAn offset at which traversal should start.
Returns
Whether or not entries could be visited.

Implemented in AZ::SettingsRegistryImpl.


The documentation for this class was generated from the following file: