AZ::SettingsRegistryInterface Class Reference

#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

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

using AZ::SettingsRegistryInterface::FixedValueString = AZ::StringFunc::Path::FixedString

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

enum class AZ::SettingsRegistryInterface::Format

strong

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

enum class AZ::SettingsRegistryInterface::MergeSettingsReturnCode

strong

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

VisitAction

enum class AZ::SettingsRegistryInterface::VisitAction

strong

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

enum class AZ::SettingsRegistryInterface::VisitResponse

strong

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

result	The target to write the result to.
path	The 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

result	The target to write the result to.
path	The 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

result	The target to write the result to.
path	The 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

result	The target to write the result to.
path	The 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

result	The target to write the result to.
path	The 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

result	The target to write the result to.
resultTypeId	The type id of the target that's being written to.
path	The 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

  argument	The command line argument.
  anchorKey	The key where the merged command line argument will be anchored under
  commandLineSettings	structure 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

data	The json data stored in a string.
format	The format of the provided data.
anchorKey	The 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

path	The path to the registry file.
format	The format of the text data in the file at the provided path.
anchorKey	The key where the content of the settings file will be anchored.
scratchBuffer	An 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

  path	The path to the registry folder.
  specializations	The specializations that will be used filter out registry files.
  platform	An 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.
  anchorKey	The registry path location where the settings will be anchored
  scratchBuffer	An 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

handler

The 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

callback

The 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

handler

The 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

callback

The 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

handler

The 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

path	The 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

path	The path to the value.
value	The 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

path	The path to the value.
value	The 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

path	The path to the value.
value	The 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

path	The path to the value.
value	The 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

path	The path to the value.
value	The 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

notify

If 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

path	The path to the value.
value	The 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

path	The path to the value.
value	The new value to store.
valueTypeId	The 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

useFileIo

If 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

callback	A callback function that will repeatedly be called as entries are encountered.
path	An 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

visitor	An instance of a class derived from Visitor that will repeatedly be called as entries are encountered.
path	An 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:

• Code/Framework/AzCore/AzCore/Settings/SettingsRegistry.h