Upgrading to API v2.0 series
Follow the compatibility notes when upgrading your mods to API v2.0 series
When upgrading your modification from the target of the later version of Nitrocid KS that declares itself to be from the API v2.0, you must make necessary changes to be able to use your mod in a Nitrocid KS version which you use to test your mod. These changes will be listed starting from 0.0.20 to the last version in this API revision.
The following changes were listed sequentially as development went on.
From 0.0.18 to 0.0.20
This version was released to make groundbreaking additions and improvements.
v0.0.20.x seriesUnified help system to support every shell
The help system used to provide functions for each shell all showing a help entry for a provided command. They were separated for each shell because they queried commands.
They're now unified to one help function. As a result, all above functions were removed.
You can use the ShowHelp()
function to utilize the feature. The below method signatures show their usage in your mods.
Improved naming of injected commands
The kernel argument parser used to host these two variables; the first one was the argument commands input, and the second one was the argument command array. However, the argument parser was re-written, so they were replaced with an array.
The kernel arguments were later removed, leaving only the command-line arguments. We suggest you to cease using this function.
Prefixed the FTP shell variables with "Ftp"
These variables were used by the FTP client, each having their own use.
The
connected
variable used to be an indicator of when the FTP client was connected or not.The
initialized
variable used to be an indicator of when the FTP client initialized its logging function and other things.The
currDirect
variable used to tell the FTP client where is the local directory.The
currentRemoteDir
variable used to tell the FTP client where is the remote directory.The
user
variable hosted the connected usernameThe private
password
variable hosted the password of the usernameThe private
strcmd
variable was used to tell the FTP client what is the command
Each of these variables were given the Ftp
prefix.
The variables were moved to FtpShellCommon
module.
Relocated Client(S)FTP
to their Shell.vb
files
Client(S)FTP
to their Shell.vb
filesThese variables were used to host the FTP and SFTP clients to perform operations related to the client. However, they're moved to their shell code.
These variables are still accessible, though they're now properties. To get the actual client from NetworkConnection
, you need to cast the ConnectionInstance
of the two below properties to their respective types: FtpClient
, SftpClient
.
Reworked on how to create notifications
The notification system was created to manage notifications. Each notification have their own class outlined in the second line, created by the NotifyCreate()
function. Because of a rework, the function was made obsolete and the Notification class was moved to its own file.
The below notification constructor can be used to create a new notification.
Made getting kernel paths more secure
An array, paths
, used to store all the kernel paths, but it was implemented insecurely, so we decided to replace it with the GetKernelPath()
and GetOtherPath()
functions.
In the current version, only the GetKernelPath()
function can be used.
Debug now uses the DebugLevel
enumerator
DebugLevel
enumeratorThe debugging functions used to take a debugging level using characters, but it has been changed to the DebugLevel
enumerator to limit the characters which can be used.
The debugger still uses the debug error level using the enumeration mentioned above. Updated versions of the kernel can use these debug writers with the enumerator, by referring to the method signatures of these.
Rewritten the command handler
These two functions were implemented separately for FTP and SFTP shells, because at the time of the development, the main shell command executor wasn't ready to support shells other than the main UESH shell.
These threads were used to handle shell execution.
The two command executors mentioned above were removed and the command threads were moved to ShellStartThreads as a result of recent improvements related to the command handler.
The command executors can be invoked by using the GetLine()
method for your own shells implemented in your mods.
Moved platform detection methods to PlatformDetector
These functions were used to detect the platform configuration. For easier access, we've moved these methods to PlatformDetector.
You can still access these functions, though they're now moved to KernelPlatform
.
Split ICustomSaver
to separate codefile
ICustomSaver
to separate codefileThis interface was made to support the custom screensavers. It has been split from the master class to the separate interface that grants easier access.
You can still use this interface, though it's renamed to IScreensaver
.
Renamed variables in public API
These variables were used for different purposes. They've been renamed to the following:
defSaverName
->DefSaverName
CSvrdb
->CustomSavers
finalSaver
->FinalSaver
ScrnSvrdb
->Screensavers
colorTemplates
->ColorTemplates
setRootPasswd
->SetRootPassword
RootPasswd
->RootPassword
maintenance
->Maintenance
argsOnBoot
->ArgsOnBoot
clsOnLogin
->ClearOnLogin
showMOTD
->ShowMOTD
simHelp
->SimHelp
slotProbe
->SlotProbe
CornerTD
->CornerTimeDate
instanceChecked
->InstanceChecked
HName
->HostName
currentLang
->CurrentLanguage
dbgWriter
->DebugWriter
dbgStackTraces
->DebugStackTraces
ftpsite
->FtpSite
ftpexit
->FtpExit
dbgConns
->DebugConnections
sftpsite
->SFTPSite
sftpexit
->SFTPExit
DRetries
->DownloadRetries
URetries
->UploadRetries
modcmnds
->ModCommands
Some of these flags were remade to properties in the latest kernel API, and some of them were removed.
Made some cleanups regarding MOTD parser
The first two stream variables were used by ReadMOTDFromFile
and SetMOTD
respectively. These variables were removed and the reader function was renamed to ReadMOTD
.
The ReadMotd()
function was still available, but it has been separated to ReadMal
and this function. Their method signatures are found below.
Split GetConnectionInfo
GetConnectionInfo
This function used to host both the connection info constructor and the prompt for the SSH client. It has been split to two functions: GetConnectionInfo
and PromptConnectionInfo
to add the AuthMethods
argument in the former function.
These functions can be used to construct SSH connection information.
Changed how mail listing works
This function used to construct a string containing a list of messages according to the page number. It used StringBuilder
to build such a string. However, this has proven to be unreliable, so we decided to change how it works by directly printing the list to the console.
This function is still available. They can be used with these method signatures.
Changed how reading contents API works
This function used to directly print the file contents to the console. As we were trying to refine the API, this function was changed to contain an array of strings containing file lines. This caused PrintContents
to be made, printing the contents to the console using ReadContents
.
Their method signatures are shown below.
Removed NotifyCreate()
NotifyCreate()
This function was used to call the constructor of the Notification class and set the necessary variables to the new instance. It later was found out to be a syntactic sugar, so we removed it as the new constructor came.
You can still create notifications using the constructor that its method signature is printed below.
Split the theme-related tools from ColorTools
ColorTools
These theme-related functions were found at the ColorTools
module, but they could have been separated from the main topic, so we decided to make an entirely new class dedicated to the theme tools.
As a result, colorTemplates
was renamed to Themes and the theme overload for SetColors
was renamed to SetColorsTheme
.
In the current API revision, you can apply your theme using the following functions:
Implemented help helpers for commands and arguments
The commands used to use the hard-coded extra help to provide additional information about the command usage. However, we needed to make this more extensible, so we decided to implement the help helpers. You need to change how you call the constructor to support the help helpers.
To implement the help helpers, the constructor of the CommandInfo
class has been changed to hold the base command, which already holds a command interface containing the overridable HelpHelper()
method.
Enumerized the reasons for the three events
These events used to hold the reason string. Since it could be anything, we've decided to make an enumeration out of it based on the error type.
The event system has been heavily redesigned in the latest API so that you can use the event enumeration with parameters.
EventType.LoginError
(Username, Reason)EventType.ThemeSetError
(Theme, Reason)EventType.ColorSetError
(Reason)
Split the custom screensaver code
The custom screensaver code were located alongside the screensaver management code. They're relocated to the new location based on the type:
CompileCustom
andGenSaver
functions were moved toCustomSaverCompiler
The remaining six functions were moved to
CustomSaverTools
The custom screensaver compilation functions were remade as we've migrated to DLL-only modding and screensaver code.
Moved few variables regarding mods
These variables were used to manage your mods. However, the following changes occurred:
All mod definitions, like
ModDefs
, were moved toHelpSystem
.Scripts dictionary was moved to
ModManager
IScript
was moved fromModParser
to its individual file
The variables were remade so they're now secure. The IScript
interface is essential for your mods.
Cleaned some flags up
These variables were accidentally exposed to the public API, so we decided to make them internally available so mods can't assign values to them.
Unified the overloads for writing functions
The W()
function, their C
and C16
siblings, and their sister functions (such as WriteSlowlyC()
, etc.) were made to separate the overloads for color level support. However, they've been unified to one master function containing overloads for each color level.
Also, these functions had their one-letter functions changed to Write so that the one-letter function names were no longer confusing, though we had to choose that because the codebase was using Visual Basic that imported the Microsoft.VisualBasic.FileSystem
module that contained the Write function. Their documentation are still available below:
These caused many problems to the point that we needed to edit many source files to try to bypass the FileSystem
module.
Your mods might break if any of them uses the console writing functions from KS, so change all the W()
instances to Write()
and remove any "C
" or "C16
" suffixes.
When writing such functions, you'll discover that the arguments parsing is stricter than the previous, due to how we've implemented the message argument. Make explicit casts to get the same behavior as the previous versions.
Actually removed AliasType
AliasType
This enumeration used to host all the shell types, but it was later found out that ShellCommandType
came earlier, and it was basically a carbon-copy of the enumeration, so we decided to remove it.
We advice you to cease using this function.
Reworked on the fetch kernel update API
This function used to return a list of kernel updates, but it was later found out that securing it with a class that holds the kernel update information was better, so we changed the return type of the function to KernelUpdate.
The FetchKernelUpdates
is still available as a usable method that mods can use by referring to the method signature below:
Removed the RGB class
This class used to hold the red, green, and blue variables, but it was later found out that the Color
class provides the same functionality, so we decided to remove the class.
The Color
class is available in the Terminaux library that Nitrocid KS uses.
Increased security of the "scripts" variable
This variable used to store the mod information for each loaded mod. It was found that mods can access this variable and perform illegal operations, so we decided to internalize it.
If you really want to list the mods using this dictionary, consider using the function for it. Its method signature is shown below:
[G|S]etConfig*
functions and subs are now obsolete
[G|S]etConfig*
functions and subs are now obsoleteThese functions were exclusively used by the settings applications to set and get the configuration values. They were derivatives of the already existing SetValue
, GetValue
, and GetPropertyValueInVariable
functions with slight changes, so we removed the two above functions to avoid code duplicates.
The three functions still exist, but relocated in the FieldManager
and PropertyManager
classes.
Made IShell
and shell stacks to handle shells
IShell
and shell stacks to handle shellsAs part of the shell rewrite, we decided to make IShell
and shell stacks to handle the shells. This caused us to remove all InitializeShell()
functions shown above to reduce confusion.
To implement your shell in your mod, use the IShell
interface.
Cleaned up GetLine()
so strcommand is first
GetLine()
so strcommand is firstGetLine()
was used to parse the given command input. However, it needed cleanup because ArgsMode
was only used for one purpose, and it felt so unnecessary that it shouldn't have been implemented in the first place, so we decided to remove it.
GetLine
has been massively changed so that it actually gets the input and executes a given command in your shell. You can use this function in your shell to listen for commands. The method signatures show the ways of how you can use this routine.
Renamed ShellCommandType
to ShellType
ShellCommandType
to ShellType
This enumeration was used to indicate the shell type to perform the operation related to shell. The enumeration was used for shell purposes other than the commands, so we decided to rename it to ShellType for easier writing.
For built-in shells, you can use the ShellType
enumeration in functions that take it. However, when defining custom shells, be sure to register your shell with ShellTypeManager
using the RegisterShell()
function to tell KS that there is a new shell coming. Custom shells can't be used with the ShellType
enumeration.
Moved all the GetLine()
functions for all shells to the master GetLine()
GetLine()
functions for all shells to the master GetLine()
All the GetLine()
functions were moved to the master GetLine as it has witnessed functional and cosmetic improvements. It now supports different shells.
GetLine()
has been massively changed so that it actually gets the input and executes a given command in your shell. You can use this function in your shell to listen for commands. The method signatures show the ways of how you can use this routine.
Moved GetTerminalEmulator()
to ConsoleExtensions
GetTerminalEmulator()
to ConsoleExtensions
This function was used to check the sanity of the terminal emulator for Linux systems. It was later found out that it could have been relocated to ConsoleExtensions
for easier calling.
KernelPlatform
now hosts this function, but the method signature is the same.
Split the exceptions to separate codefiles
These exceptions used to be hosted on the Exceptions masterclass, but they were separated for easier access.
The kernel exception system had a massive rewrite to the point where every single kernel exception was given an enumeration value and their own message. You can throw these exceptions using the KernelException
masterclass.
Renamed new line field to NewLine
from vbNewLine
NewLine
from vbNewLine
vbNewLine
sounded like it came from Visual Basic 6.0 (not .NET), a COM-based Windows-only language which we'll never support, and because of the below namespace changes that causes Microsoft.VisualBasic
namespace to break things related to vbNewLine
, we decided to change it to just NewLine
.
Namespaced the entire codebase
To further organize the codebase, we decided to namespace each one of them based on the folders in the source code. This way, we'd have the following namespaces:
KS.Arguments
KS.Arguments.ArgumentBase
KS.Arguments.CommandLineArguments
KS.Arguments.KernelArguments
KS.Arguments.PreBootCommandLineArguments
KS.ConsoleBase
KS.ConsoleBase.Themes
KS.ConsoleBase.Themes.Studio
KS.Files
KS.Hardware
KS.Kernel
KS.Kernel.Exceptions
KS.Languages
KS.Login
KS.ManPages
KS.Misc
KS.Misc.Beautifiers
KS.Misc.Calendar
KS.Misc.Calendar.Events
KS.Misc.Calendar.Reminders
KS.Misc.Configuration
KS.Misc.Encryption
KS.Misc.Execution
KS.Misc.Forecast
KS.Misc.Games
KS.Misc.JsonShell
KS.Misc.JsonShell.Commands
KS.Misc.Notifiers
KS.Misc.Platform
KS.Misc.Probers
KS.Misc.Reflection
KS.Misc.Screensaver
KS.Misc.Screensaver.Customized
KS.Misc.Screensaver.Displays
KS.Misc.Splash
KS.Misc.Splash.Splashes
KS.Misc.TextEdit
KS.Misc.TextEdit.Commands
KS.Misc.Threading
KS.Misc.Timers
KS.Misc.Writers
KS.Misc.Writers.ConsoleWriters
KS.Misc.Writers.DebugWriters
KS.Misc.Writers.FancyWriters
KS.Misc.Writers.FancyWriters.Tools
KS.Misc.Writers.MiscWriters
KS.Misc.ZipFile
KS.Misc.ZipFile.Commands
KS.Modifications
KS.Network
KS.Network.FTP
KS.Network.FTP.Commands
KS.Network.FTP.Filesystem
KS.Network.FTP.Transfer
KS.Network.HTTP
KS.Network.HTTP.Commands
KS.Network.Mail
KS.Network.Mail.Commands
KS.Network.Mail.Directory
KS.Network.Mail.PGP
KS.Network.Mail.Transfer
KS.Network.RemoteDebug
KS.Network.RemoteDebug.Commands
KS.Network.RemoteDebug.Interface
KS.Network.RPC
KS.Network.RSS
KS.Network.RSS.Commands
KS.Network.RSS.Instance
KS.Network.SFTP
KS.Network.SFTP.Commands
KS.Network.SFTP.Filesystem
KS.Network.SFTP.Transfer
KS.Network.SSH
KS.Scripting
KS.Scripting.Interaction
KS.Shell
KS.Shell.Commands
KS.Shell.ShellBase
KS.Shell.Shells
KS.TestShell
KS.TestShell.Commands
KS.TimeDate
New namespaces get created and/or changed each major release of the kernel, so the list above is only relevant at the time the change was committed. The API reference will always display all the available namespaces.
Removed built-in string evaluators
The built-in string evaluators were used for the calculator functionality in the kernel, but it was later found out that it was too slow and insecure. We decided to remove these evaluators as a result.
We advice you to cease using this function.
From 0.0.20 to 0.0.21
This version was a minor update to 0.0.20.0.
v0.0.21.x seriesConsolidated the obsolete functions
These obsolete functions were used by the settings app to do the following:
FindSetting(String, Boolean)
was used to return the found settings, but the boolean variable indicates if the app is going to use the screensaver settings metadata.SetConfigValueField(String, Object)
was used to be a wrapper to theSetValue(String, Object)
functionGetConfigValueField(String)
was used to be a wrapper to theGetValue(String)
functionGetConfigPropertyValueInVariableField(String, String)
was used to be a wrapper to theGetPropertyValueInVariable(String, String)
function
They're removed as a result of the migration of these functions.
FindSetting()
was moved to ConfigTools
, and it was improved. You can see the method signature below.
From 0.0.21 to 0.0.22
This version was a great update to the API v2.0 series, because it added Android support to KS!
v0.0.22.x seriesSeparated properties code to PropertyManager
PropertyManager
These functions were used to get the property values and properties themselves. However, it was found that they're located on FieldManager
and we felt that it was a bit misleading, so we decided to move them to their own dedicated class, PropertyManager
.
These functions have been renamed to shorter names and used cached expressions to slightly improve performance. You can find their method signatures.
Events and reminders format
Events and reminders file formats have been changed from binary file to XML files as BinarySerializer
was being deprecated because of it being vulnerable to attacks as describes in the below documentation link:
Deprecation of IScript.PerformCmd()
IScript.PerformCmd()
As we implemented the fully-fledged CommandBase.Execute()
function which does the same thing as IScript.PerformCmd()
, we've deprecated the function in the interface to take advantage of the CommandBase.Execute()
routine.
BaseCommand.Execute()
can be overridden in the below method signature:
Removed ReadLineLong()
ReadLineLong()
This function was implemented to take advantage of the long input support in the built-in .NET console reader. As ReadLine.Reboot was used, this function has been removed.
Long inputs are supported by the Input.ReadLine
function that has several method signatures shown below:
From 0.0.22 to 0.0.23
This version was the last version from the API v2.0 series.
v0.0.23.x seriesDeprecation of ICustomSaver
ICustomSaver
As we've implemented BaseScreensaver
to better handle screensavers, we decided to deprecate ICustomSaver
in favor of the new screensaver model. This would merge all kernel threads of individual screensavers to one master screensaver thread.
All new screensavers should use the BaseScreensaver
class. All existing screensavers should migrate from ICustomSaver
to BaseScreensaver
.
Last updated