RtfwSetSubsystemConfiguration

RtfwSetSubsystemConfiguration modifies the core RTX64 Subsystem configuration parameters. See structure RTFW_SUBSYSTEM_CONFIGURATION. Other subsystem configuration parameters can be modified using other functions in this library.

Syntax

bool RtfwSetSubsystemConfiguration(
    const RTFW_SUBSYSTEM_CONFIGURATION * pSubsystemConfiguration,
    DWORD * pWarning
);

Parameters

pSubsystemConfiguration

A pointer to a RTFW_SUBSYSTEM_CONFIGURATION structure containing members related to the core Subsystem configuration. The Size member must be set to sizeof(RTFW_SUBSYSTEM_CONFIGURATION), otherwise this function fails and sets the last error value to RT_ERROR_STRUCTURE_TOO_SMALL.

pWarning

A pointer to a value that is set to a non-zero warning code if a warning results from a successful call to this API. If this API fails, this value is undefined.

When the Subsystem is not running when this function succeeds, and the values of member TickInterval (in structure RTFW_NETWORK_CONFIGURATION) or member WatchdogTimeout (in structure RTFW_WATCHDOG_CONFIGURATION) were modified as described in structure RTFW_SUBSYSTEM_CONFIGURATION, warning code RT_WARNING_TIMER_VALUES_ROUNDED is returned.

See preprocessor macros RT_WARNING_... in header file RtErrorCodes.h for other possible warning codes.

Return Value

The function returns true if it succeeds. Otherwise, it returns false and sets the last error value.

Possible error codes:

Error Code	Meaning
ERROR_ACCESS_DENIED	The caller did not have Administrator privileges when this API was used to modify the value of member StartMode in structure RTFW_SUBSYSTEM_CONFIGURATION
RT_ERROR_DEFAULTTIMEQUANTUM_INVALID	DefaultTimeQuantum is not the value RTFW_DISABLE_TIME_QUANTUM and is not an integer multiple of member HALTimerPeriod.
RT_ERROR_HALTIMER_INVALID	Either the HAL timer period is out of range or the default time quantum is not a multiple of the HAL timer period.
RT_ERROR_RESTART_SUBSYSTEM	The Subsystem was running when this function succeeded. RtfwRestartRequired will report that the RTX64 Subsystem must be restarted. NOTE: The RTX64 Subsystem must be restarted for the changes to take effect.
RT_ERROR_STRUCTURE_TOO_SMALL	The Size member of a structure is too small.
RT_WARNING_TIMER_VALUES_ROUNDED	Returned when the Subsystem is not running when this function succeeds, and the values of member TickInterval in structure RTFW_NETWORK_CONFIGURATION) or member WatchdogTimeout in structure RTFW_WATCHDOG_CONFIGURATION were modified as described in structure RTFW_SUBSYSTEM_CONFIGURATION

Remarks

RtfwSetSubsystemConfiguration must be run with Administrator privileges. The function will fail otherwise.

The following is the best practice for using Native Library Get/Set APIs that take structures as arguments:

Call the Get function.
Modify the value(s) you want to change.
Call the corresponding Set function.

The values passed in by the Set function will be saved (persistent).

A new Default Time Quantum must be less than or equal to UINT32_MAX (0xFFFFFFFF), which is the maximum valid Default Time Quantum value.

Requirements

Minimum Required Version	RTX64 3.4
Header	RtfwAPI.h
Library	RtfwAPI.lib