omni::structuredlog::IStructuredLogSettings

Defined in omni/structuredlog/IStructuredLogSettings.h

class IStructuredLogSettings : public omni::core::Generated<omni::structuredlog::IStructuredLogSettings_abi>

Structured log settings interface.

This allows a host app to modify some behavior of the structured log system for the process or to retrieve information about the current settings. These settings control features such as the event queue size, log rotation, event ID generation, the output log path, and the user ID. Most of the default settings should be sufficient for most apps with the exception of the user ID. For host apps that use at least one non-anonymized schema the only settings that must be set is the user ID.

This interface object can be acquired either by requesting it from the type factory or by casting an IStructuredLog object to this type.

Public Functions

inline bool loadPrivacySettingsFromFile(const char *filename, PrivacyLoadFlags flags)

Attempts to load the privacy settings from a specific file.

Note

This is not available when using structured logging in ‘standalone’ mode.

Note

This should only be used for testing purposes. This should never be called in a production app.

Parameters

• filename – [in] The name and path to the privacy settings file to load. This is expected to be a TOML formatted file. This may be nullptr or an empty string to reload the user default privacy settings.

• flags – [in] Flags to affect the behavior of this operation. This must be a combination of zero or more of the PrivacyLoadFlags flags.

Returns

true if the privacy settings are successfully loaded from the given file. Returns false if the named file could not be found or the ISettings interface is not available.

inline size_t getEventQueueSize() noexcept

Retrieves the current event queue size.

Thread Safety

This call is thread safe.

Returns

The current size of the event queue buffer in bytes. Note that once the first event message is sent, the event queue will be running and this will continue to return the ‘active’ size of the event queue regardless of any new size that is passed to omni::structuredlog::IStructuredLogSettings::setEventQueueSize(). Any new size will only be made active once the event queue is stopped with omni::structuredlog::IStructuredLogControl::stop(). The default size is 2MiB.

inline int64_t getLogSizeLimit() noexcept

Retrieves the current maximum log file size.

Thread Safety

This call is thread safe.

Returns

The current maximum log file size in bytes. This helps to control when log files get rotated out and started anew for the process. The number of old logs that are kept is controlled by the log retention count. The default size is 50MB.

inline size_t getLogRetentionCount() noexcept

Retrieves the current log retention count.

Thread Safety

This call is thread safe.

Returns

The maximum number of log files to retain when rotating log files. When a new log is rotated out, the oldest one that is beyond this count will be deleted. The default is 3.

inline omni::structuredlog::IdMode getEventIdMode() noexcept

Retrieves the current event identifier mode.

Thread Safety

This call is thread safe.

Returns

The current event identifier mode. The default is omni::structuredlog::IdMode::eFastSequential.

inline omni::structuredlog::IdType getEventIdType() noexcept

Retrieves the current event identifier type.

Thread Safety

This call is thread safe.

Returns

The current event identifier type. The default is omni::structuredlog::IdType::eUuid.

inline const char *getLogOutputPath() noexcept

Retrieves the current log output path.

Thread Safety

This call is thread safe to retrieve the path string. However, the string itself may become invalidated after return if the log output path is changed with a call to omni::structuredlog::IStructuredLogSettings::setLogOutputPath(). It is the host app’s responsibility to ensure the log output path is not being changed while this string is being used. The returned string generally should not be cached anywhere. It should be retrieved from here any time it is needed.

Returns

The path that log files will be written to. This defaults to the launcher app’s default log directory. The host app should override that if that location is not suitable.

inline const char *getLogDefaultName() noexcept

Retrieves the default log name if any has been set.

Thread Safety

This call itself is thread safe. However, the returned string is only valid until either the log path or the default log name changes. It is the caller’s responsibility to ensure the returned string is used safely.

Returns

The default log file name that will be used to output all events that are not explicitly marked with the omni::structuredlog::fEventFlagUseLocalLog flag. This name will include the log output path as set by omni::structuredlog::IStructuredLogSettings::getLogOutputPath().

Returns

nullptr if no default log name has been set with omni::structuredlog::IStructuredLogSettings::setLogDefaultName() or the default log name has been cleared.

inline const char *getLogPathForEvent(omni::structuredlog::EventId eventId) noexcept

Retrieves the log path that a given event will be written to.

Thread Safety

This call itself is thread safe. However, the returned string is only valid until either the log path or the default log name changes. It is the caller’s responsibility to ensure the returned string is used safely.

Parameters

eventId – [in] The ID of the event to retrieve the log path for. This must be the same ID used when the event was registered. This may also be omni::structuredlog::kDefaultLogPathEvent to retrieve the path for the default log.

Returns

The name and path of the log file that the requested event would go to if it were emitted with current settings.

Returns

the name and path of the default log file if kDefaultLogPathEvent is used for for the event ID.

Returns

nullptr if the given event ID is unknown or kDefaultLogPathEvent was used and no default log name has been set.

inline const char *getUserId() noexcept

Retrieves the current user ID.

Thread Safety

This call is thread safe to retrieve the user ID. However, the string itself may become invalidated after return if the user ID is changed with a call to to omni::structuredlog::IStructuredLogSettings::setUserId(). It is the host app’s responsibility to ensure the user ID is not being changed while this string is being used. The returned string generally should not be cached anywhere. It should be retrieved from here any time it is needed.

Returns

The current user ID. This may be a user name or user identification number. The specific format and content is left entirely up to the host app itself. By default, the user ID will either be the user ID listed in the privacy settings file if present, or a random number if the user ID setting is not present. When a random number is used for the user ID, it is useful for anonymizing user event messages.

inline omni::structuredlog::SessionId getSessionId() noexcept

Retrieves the current session ID.

Remark

This retrieves the session ID for the current structured log session. This ID is chosen when the structured log session starts and remains constant for its lifetime.

Returns

The identifier for the current session if the current privacy settings allow it.

inline void setEventQueueSize(size_t sizeInBytes) noexcept

Sets the new event queue buffer size.

Remark

This sets the new event queue buffer size. A larger buffer allows more events to be sent and processed simultaneously in an app. If the buffer ever fills up, events may be dropped if they cannot be processed fast enough. For host apps that infrequently send small events, some memory can be saved by reducing this buffer size. However, host apps that need to be able to send messages frequently, especially simultaneously from multiple threads, should use a larger buffer size to allow the event queue to keep up with the incoming event demand.

Remark

Once the event queue is running (ie: the first message has been sent), changing its size will cause a second queue to be created at the new size. The old queue will be flushed and the new queue will be made active. There will be a short period where two queues will be running simultaneously. Any new events that are queued during this period will be added to the new queue. There is no need to stop the old queue before changing the size, this will be handled automatically. Note that during one of these queue transitions there may be a short period where omni::structuredlog::getEventQueueSize() may return the new queue’s size even if the old queue is still active.

Thread Safety

This call is thread safe.

Note

Changing the queue size frequently will lead to stalls in the processing pipeline. Generally the queue size should be set once on startup of an app and left at that configured size for the process’ lifetime.

Parameters

sizeInBytes – [in] the new event queue buffer size in bytes to use. This will be silently clamped to an acceptable minimum size. The default is 2MiB.

Returns

No return value.

inline void setLogSizeLimit(int64_t limitInBytes) noexcept

Sets the log size limit.

Remark

This sets the log size limit. When a log reaches (approximately) this size, it will be rotated out and a new log file started. The number of old log files that are kept is controlled by the log retention count.

Thread Safety

This call is thread safe.

Parameters

limitInBytes – [in] The new log size limit in bytes. This controls the maximum size a log file can get up to before it is rotated out and a new log is started. This will be silently clamped to an acceptable minimum size. The default is 50MiB. The minimum size limit is 256KiB.

Returns

No return value.

inline void setLogRetentionCount(size_t count) noexcept

Sets the log retention count.

Thread Safety

This call is thread safe.

Parameters

count – [in] The maximum number of old log files to maintain. When a log file grows beyond the current size limit, it will be renamed and a new log opened with the original name. The oldest log file may be deleted if there are more logs than this count. The default is 3.

Returns

No return value.

inline void setEventIdMode(omni::structuredlog::IdMode mode, omni::structuredlog::IdType type) noexcept

Sets the current event identifier mode and type.

Thread Safety

This call is thread safe.

Parameters

• mode – [in] The new identifier mode to use. This will take effect on the next event that is sent. The default is IdMode::eFastSequential.

• type – [in] The new identifier type to use. This will take effect on the next event that is sent. The default is IdType::eUuid.

Returns

No return value.

inline void setLogOutputPath(const char *path) noexcept

Sets the new log output path.

Remark

This changes the log file location for the calling process. The log file locations for all registered schemas will be updated as well. If a schema has been set to keep its log file open, it will be closed at this point (if already open). The next event that is written to the log file will open a new log at the new location. The old log file (if any) will not be moved from the previous location.

Thread Safety

This call is thread safe. However, it is the caller’s responsibility to ensure that no other host thread is simultaneously operating on the log output path string returned from omni::structuredlog::IStructuredLogSettings::getLogOutputPath() and that nothing else has cached that returned string since it could become invalidated here.

Note

There is still a possible race condition with changing the log directory if events are pending for processing. If the log file had been opened to write out a message at the same time this is changing the log path, the change in log path will not take effect until the next event message is being processed.

Parameters

path – [in] The new log file path to use. This may not be an empty string. The default is the Launcher app’s expected log file path. This may be either a relative or absolute path. However, note that if this is relative, the location of the log files may change if the process’s current working directory ever changes. It is highly suggested that only absolute paths be used. This may also be omni::structuredlog::kDefaultLogPathName or nullptr to set the log output path back to its default location.

Returns

No return value.

inline void setLogDefaultName(const char *name) noexcept

Sets the new default log name to use for message output.

Remark

This sets the new default log file name. When set to a valid file name, all messages coming from events that do not use the omni::structuredlog::fEventFlagUseLocalLog flag will be written to the log file using this name in the current log output directory. When either this name or the log output directory changes, any open log files will be closed and reopened under the new name and path when the next event is written.

Note

When log rotation occurs, the rotation number is inserted before the file extension (e.g. filename.ext is rotated to filename.1.ext). If no extension is detected, the number is just appended to the file name. A file extension is detected with the following regex: \..{0,4}$.

Parameters

name – [in] The new default name to set for the message log file. This may be an empty string or nullptr to restore the default behavior of writing each new message to its own schema’s log file. This should just be the name of the file and not include any path components. This may also be one of the special values /dev/stdout or /dev/stderr to send the output to only the stdout or stderr streams. In this case, all events are output to these streams even if a given schema uses the fSchemaFlagUseLocalLog or event uses the fEventFlagUseLocalLog flag. Otherwise, if a filename is given and this name contains any path components (ie: a ‘/’), setting the default log name will fail. The log output path should be set using omni::structuredlog::IStructuredLogSettings::setLogOutputPath() instead. If this name does not have a file extension, a “.log” extension will be added. If the “.log” extension is not desired, this may be suppressed by ending the name in “.”. In this case, the final trailing “.” will be removed from the name. This name may also contain the token ‘${pid}’ that will be replaced by the current process ID.

Returns

No return value.

inline void setUserId(const char *userId) noexcept

Sets the user ID to use in messages.

Remark

This sets the user ID to be used in the ‘source’ property of all event messages going forward. This will not affect the user ID of any messages that are currently being processed at the time of this call. This will affect all pending messages that are not being immediately processed however. Only the host app should set this user ID. External plugins and extensions should never change the user ID.

Thread Safety

This call is thread safe. However, it is the caller’s responsibility to ensure that no other host thread is simultaneously operating on the user ID string returned from omni::structuredlog::IStructuredLogSettings::getUserId() and that nothing else has cached that returned string since it could become invalidated here.

Parameters

userId – [in] The user ID to use with all event messages going forward. This may not be nullptr or an empty string. The default is a random number.

Returns

No return value.

inline bool loadPrivacySettings() noexcept

Attempts to load the privacy settings file.

Remark

This will attempt to load the privacy settings file for the current user. Regardless of whether the file is successfully loaded, appropriate defaults will always be set for each of the expected privacy settings (as long as the ISettings interface is available).

Note

This expects that some other system has already found and attempted to load the plugin that implements the ISettings interface.

Returns

true if the privacy settings file was successfully loaded.

Returns

false if the privacy settings file could not be loaded. This failure may be caused by the file being missing, failing to open the file due to permissions, failing to allocate memory to read in the file, the file not being formatted correctly as a TOML file, or failing to merge the new values into the settings registry.

inline bool enableSchemasFromSettings() noexcept

Checks app settings to see if any schemas or events should be disabled or enabled.

Remark

This checks the settings registry to determine if any schemas or events should be disabled initially. The keys in the settings registry that will be looked at are under omni::structuredlog::kSchemasStateListSetting, omni::structuredlog::kEventsStateListSetting, omni::structuredlog::kEventsStateArraySetting, and omni::structuredlog::kSchemasStateArraySetting. Each of these parts of the settings registry expects the schema or event name to be specified in a different way. Once the settings have been loaded, they are cached internally and will be used as the initial state of any newly registered schemas or events. Any state changes to events or schemas after these settings are cached can still be done programmatically with omni::structuredlog::IStructuredLog::setEnabled().

Returns

true if the settings registry was successfully checked for enable or disable states. Returns false if the carb::settings::ISettings or carb::dictionary::IDictionary plugins have not been loaded yet.

inline void *cast(omni::core::TypeId id) noexcept

Returns a pointer to the interface defined by the given type id if this object implements the type id’s interface.

Objects can support multiple interfaces, even interfaces that are in different inheritance chains.

The returned object will have omni::core::IObject::acquire() called on it before it is returned, meaning it is up to the caller to call omni::core::IObject::release() on the returned pointer.

The returned pointer can be safely reinterpret_cast<> to the type id’s C++ class. For example, “omni.windowing.IWindow” can be cast to omni::windowing::IWindow.

Do not directly use this method, rather use a wrapper function like omni::core::cast() or omni::core::ObjectPtr::as().

Thread Safety

This method is thread safe.

inline void acquire() noexcept

Increments the object’s reference count.

Objects may have multiple reference counts (e.g. one per interface implemented). As such, it is important that you call omni::core::IObject::release() on the same pointer from which you called omni::core::IObject::acquire().

Do not directly use this method, rather use omni::core::ObjectPtr, which will manage calling omni::core::IObject::acquire() and omni::core::IObject::release() for you.

Thread Safety

This method is thread safe.

inline void release() noexcept

Decrements the objects reference count.

Most implementations will destroy the object if the reference count reaches 0 (though this is not a requirement).

Objects may have multiple reference counts (e.g. one per interface implemented). As such, it is important that you call omni::core::IObject::release() on the same pointer from which you called omni::core::IObject::acquire().

Do not directly use this method, rather use omni::core::ObjectPtr, which will manage calling omni::core::IObject::acquire() and omni::core::IObject::release() for you.

Thread Safety

This method is thread safe.

Protected Functions

virtual size_t getEventQueueSize_abi() noexcept = 0

Retrieves the current event queue size.

Thread Safety

This call is thread safe.

Returns

The current size of the event queue buffer in bytes. Note that once the first event message is sent, the event queue will be running and this will continue to return the ‘active’ size of the event queue regardless of any new size that is passed to omni::structuredlog::IStructuredLogSettings::setEventQueueSize(). Any new size will only be made active once the event queue is stopped with omni::structuredlog::IStructuredLogControl::stop(). The default size is 2MiB.

virtual int64_t getLogSizeLimit_abi() noexcept = 0

Retrieves the current maximum log file size.

Thread Safety

This call is thread safe.

Returns

The current maximum log file size in bytes. This helps to control when log files get rotated out and started anew for the process. The number of old logs that are kept is controlled by the log retention count. The default size is 50MB.

virtual size_t getLogRetentionCount_abi() noexcept = 0

Retrieves the current log retention count.

Thread Safety

This call is thread safe.

Returns

The maximum number of log files to retain when rotating log files. When a new log is rotated out, the oldest one that is beyond this count will be deleted. The default is 3.

virtual IdMode getEventIdMode_abi() noexcept = 0

Retrieves the current event identifier mode.

Thread Safety

This call is thread safe.

Returns

The current event identifier mode. The default is omni::structuredlog::IdMode::eFastSequential.

virtual IdType getEventIdType_abi() noexcept = 0

Retrieves the current event identifier type.

Thread Safety

This call is thread safe.

Returns

The current event identifier type. The default is omni::structuredlog::IdType::eUuid.

virtual const char *getLogOutputPath_abi() noexcept = 0

Retrieves the current log output path.

Thread Safety

This call is thread safe to retrieve the path string. However, the string itself may become invalidated after return if the log output path is changed with a call to omni::structuredlog::IStructuredLogSettings::setLogOutputPath(). It is the host app’s responsibility to ensure the log output path is not being changed while this string is being used. The returned string generally should not be cached anywhere. It should be retrieved from here any time it is needed.

Returns

The path that log files will be written to. This defaults to the launcher app’s default log directory. The host app should override that if that location is not suitable.

virtual const char *getLogDefaultName_abi() noexcept = 0

Retrieves the default log name if any has been set.

Thread Safety

This call itself is thread safe. However, the returned string is only valid until either the log path or the default log name changes. It is the caller’s responsibility to ensure the returned string is used safely.

Returns

The default log file name that will be used to output all events that are not explicitly marked with the omni::structuredlog::fEventFlagUseLocalLog flag. This name will include the log output path as set by omni::structuredlog::IStructuredLogSettings::getLogOutputPath().

Returns

nullptr if no default log name has been set with omni::structuredlog::IStructuredLogSettings::setLogDefaultName() or the default log name has been cleared.

virtual const char *getLogPathForEvent_abi(EventId eventId) noexcept = 0

Retrieves the log path that a given event will be written to.

Thread Safety

This call itself is thread safe. However, the returned string is only valid until either the log path or the default log name changes. It is the caller’s responsibility to ensure the returned string is used safely.

Parameters

eventId – [in] The ID of the event to retrieve the log path for. This must be the same ID used when the event was registered. This may also be omni::structuredlog::kDefaultLogPathEvent to retrieve the path for the default log.

Returns

The name and path of the log file that the requested event would go to if it were emitted with current settings.

Returns

the name and path of the default log file if kDefaultLogPathEvent is used for for the event ID.

Returns

nullptr if the given event ID is unknown or kDefaultLogPathEvent was used and no default log name has been set.

virtual const char *getUserId_abi() noexcept = 0

Retrieves the current user ID.

Thread Safety

This call is thread safe to retrieve the user ID. However, the string itself may become invalidated after return if the user ID is changed with a call to to omni::structuredlog::IStructuredLogSettings::setUserId(). It is the host app’s responsibility to ensure the user ID is not being changed while this string is being used. The returned string generally should not be cached anywhere. It should be retrieved from here any time it is needed.

Returns

The current user ID. This may be a user name or user identification number. The specific format and content is left entirely up to the host app itself. By default, the user ID will either be the user ID listed in the privacy settings file if present, or a random number if the user ID setting is not present. When a random number is used for the user ID, it is useful for anonymizing user event messages.

virtual SessionId getSessionId_abi() noexcept = 0

Retrieves the current session ID.

Remark

This retrieves the session ID for the current structured log session. This ID is chosen when the structured log session starts and remains constant for its lifetime.

Returns

The identifier for the current session if the current privacy settings allow it.

virtual void setEventQueueSize_abi(size_t sizeInBytes) noexcept = 0

Sets the new event queue buffer size.

Remark

This sets the new event queue buffer size. A larger buffer allows more events to be sent and processed simultaneously in an app. If the buffer ever fills up, events may be dropped if they cannot be processed fast enough. For host apps that infrequently send small events, some memory can be saved by reducing this buffer size. However, host apps that need to be able to send messages frequently, especially simultaneously from multiple threads, should use a larger buffer size to allow the event queue to keep up with the incoming event demand.

Remark

Once the event queue is running (ie: the first message has been sent), changing its size will cause a second queue to be created at the new size. The old queue will be flushed and the new queue will be made active. There will be a short period where two queues will be running simultaneously. Any new events that are queued during this period will be added to the new queue. There is no need to stop the old queue before changing the size, this will be handled automatically. Note that during one of these queue transitions there may be a short period where omni::structuredlog::getEventQueueSize() may return the new queue’s size even if the old queue is still active.

Thread Safety

This call is thread safe.

Note

Changing the queue size frequently will lead to stalls in the processing pipeline. Generally the queue size should be set once on startup of an app and left at that configured size for the process’ lifetime.

Parameters

sizeInBytes – [in] the new event queue buffer size in bytes to use. This will be silently clamped to an acceptable minimum size. The default is 2MiB.

Returns

No return value.

virtual void setLogSizeLimit_abi(int64_t limitInBytes) noexcept = 0

Sets the log size limit.

Remark

This sets the log size limit. When a log reaches (approximately) this size, it will be rotated out and a new log file started. The number of old log files that are kept is controlled by the log retention count.

Thread Safety

This call is thread safe.

Parameters

limitInBytes – [in] The new log size limit in bytes. This controls the maximum size a log file can get up to before it is rotated out and a new log is started. This will be silently clamped to an acceptable minimum size. The default is 50MiB. The minimum size limit is 256KiB.

Returns

No return value.

virtual void setLogRetentionCount_abi(size_t count) noexcept = 0

Sets the log retention count.

Thread Safety

This call is thread safe.

Parameters

count – [in] The maximum number of old log files to maintain. When a log file grows beyond the current size limit, it will be renamed and a new log opened with the original name. The oldest log file may be deleted if there are more logs than this count. The default is 3.

Returns

No return value.

virtual void setEventIdMode_abi(IdMode mode, IdType type) noexcept = 0

Sets the current event identifier mode and type.

Thread Safety

This call is thread safe.

Parameters

• mode – [in] The new identifier mode to use. This will take effect on the next event that is sent. The default is IdMode::eFastSequential.

• type – [in] The new identifier type to use. This will take effect on the next event that is sent. The default is IdType::eUuid.

Returns

No return value.

virtual void setLogOutputPath_abi(const char *path) noexcept = 0

Sets the new log output path.

Remark

This changes the log file location for the calling process. The log file locations for all registered schemas will be updated as well. If a schema has been set to keep its log file open, it will be closed at this point (if already open). The next event that is written to the log file will open a new log at the new location. The old log file (if any) will not be moved from the previous location.

Thread Safety

This call is thread safe. However, it is the caller’s responsibility to ensure that no other host thread is simultaneously operating on the log output path string returned from omni::structuredlog::IStructuredLogSettings::getLogOutputPath() and that nothing else has cached that returned string since it could become invalidated here.

Note

There is still a possible race condition with changing the log directory if events are pending for processing. If the log file had been opened to write out a message at the same time this is changing the log path, the change in log path will not take effect until the next event message is being processed.

Parameters

path – [in] The new log file path to use. This may not be an empty string. The default is the Launcher app’s expected log file path. This may be either a relative or absolute path. However, note that if this is relative, the location of the log files may change if the process’s current working directory ever changes. It is highly suggested that only absolute paths be used. This may also be omni::structuredlog::kDefaultLogPathName or nullptr to set the log output path back to its default location.

Returns

No return value.

virtual void setLogDefaultName_abi(const char *name) noexcept = 0

Sets the new default log name to use for message output.

Remark

This sets the new default log file name. When set to a valid file name, all messages coming from events that do not use the omni::structuredlog::fEventFlagUseLocalLog flag will be written to the log file using this name in the current log output directory. When either this name or the log output directory changes, any open log files will be closed and reopened under the new name and path when the next event is written.

Note

When log rotation occurs, the rotation number is inserted before the file extension (e.g. filename.ext is rotated to filename.1.ext). If no extension is detected, the number is just appended to the file name. A file extension is detected with the following regex: \..{0,4}$.

Parameters

name – [in] The new default name to set for the message log file. This may be an empty string or nullptr to restore the default behavior of writing each new message to its own schema’s log file. This should just be the name of the file and not include any path components. This may also be one of the special values /dev/stdout or /dev/stderr to send the output to only the stdout or stderr streams. In this case, all events are output to these streams even if a given schema uses the fSchemaFlagUseLocalLog or event uses the fEventFlagUseLocalLog flag. Otherwise, if a filename is given and this name contains any path components (ie: a ‘/’), setting the default log name will fail. The log output path should be set using omni::structuredlog::IStructuredLogSettings::setLogOutputPath() instead. If this name does not have a file extension, a “.log” extension will be added. If the “.log” extension is not desired, this may be suppressed by ending the name in “.”. In this case, the final trailing “.” will be removed from the name. This name may also contain the token ‘${pid}’ that will be replaced by the current process ID.

Returns

No return value.

virtual void setUserId_abi(const char *userId) noexcept = 0

Sets the user ID to use in messages.

Remark

This sets the user ID to be used in the ‘source’ property of all event messages going forward. This will not affect the user ID of any messages that are currently being processed at the time of this call. This will affect all pending messages that are not being immediately processed however. Only the host app should set this user ID. External plugins and extensions should never change the user ID.

Thread Safety

This call is thread safe. However, it is the caller’s responsibility to ensure that no other host thread is simultaneously operating on the user ID string returned from omni::structuredlog::IStructuredLogSettings::getUserId() and that nothing else has cached that returned string since it could become invalidated here.

Parameters

userId – [in] The user ID to use with all event messages going forward. This may not be nullptr or an empty string. The default is a random number.

Returns

No return value.

virtual bool loadPrivacySettings_abi() noexcept = 0

Attempts to load the privacy settings file.

Remark

This will attempt to load the privacy settings file for the current user. Regardless of whether the file is successfully loaded, appropriate defaults will always be set for each of the expected privacy settings (as long as the ISettings interface is available).

Note

This expects that some other system has already found and attempted to load the plugin that implements the ISettings interface.

Returns

true if the privacy settings file was successfully loaded.

Returns

false if the privacy settings file could not be loaded. This failure may be caused by the file being missing, failing to open the file due to permissions, failing to allocate memory to read in the file, the file not being formatted correctly as a TOML file, or failing to merge the new values into the settings registry.

virtual bool enableSchemasFromSettings_abi() noexcept = 0

Checks app settings to see if any schemas or events should be disabled or enabled.

Remark

This checks the settings registry to determine if any schemas or events should be disabled initially. The keys in the settings registry that will be looked at are under omni::structuredlog::kSchemasStateListSetting, omni::structuredlog::kEventsStateListSetting, omni::structuredlog::kEventsStateArraySetting, and omni::structuredlog::kSchemasStateArraySetting. Each of these parts of the settings registry expects the schema or event name to be specified in a different way. Once the settings have been loaded, they are cached internally and will be used as the initial state of any newly registered schemas or events. Any state changes to events or schemas after these settings are cached can still be done programmatically with omni::structuredlog::IStructuredLog::setEnabled().

Returns

true if the settings registry was successfully checked for enable or disable states. Returns false if the carb::settings::ISettings or carb::dictionary::IDictionary plugins have not been loaded yet.

virtual void *cast_abi(TypeId id) noexcept = 0

Returns a pointer to the interface defined by the given type id if this object implements the type id’s interface.

Objects can support multiple interfaces, even interfaces that are in different inheritance chains.

The returned object will have omni::core::IObject::acquire() called on it before it is returned, meaning it is up to the caller to call omni::core::IObject::release() on the returned pointer.

The returned pointer can be safely reinterpret_cast<> to the type id’s C++ class. For example, “omni.windowing.IWindow” can be cast to omni::windowing::IWindow.

Do not directly use this method, rather use a wrapper function like omni::core::cast() or omni::core::ObjectPtr::as().

Thread Safety

This method is thread safe.

virtual void acquire_abi() noexcept = 0

Increments the object’s reference count.

Objects may have multiple reference counts (e.g. one per interface implemented). As such, it is important that you call omni::core::IObject::release() on the same pointer from which you called omni::core::IObject::acquire().

Do not directly use this method, rather use omni::core::ObjectPtr, which will manage calling omni::core::IObject::acquire() and omni::core::IObject::release() for you.

Thread Safety

This method is thread safe.

virtual void release_abi() noexcept = 0

Decrements the objects reference count.

Most implementations will destroy the object if the reference count reaches 0 (though this is not a requirement).

Objects may have multiple reference counts (e.g. one per interface implemented). As such, it is important that you call omni::core::IObject::release() on the same pointer from which you called omni::core::IObject::acquire().

Do not directly use this method, rather use omni::core::ObjectPtr, which will manage calling omni::core::IObject::acquire() and omni::core::IObject::release() for you.

Thread Safety

This method is thread safe.