mirror of
https://github.com/20kdc/OC-KittenOS.git
synced 2024-12-28 11:58:07 +11:00
0d9583fcff
This isn't getting pushed until AmandaC's tested it. I'm not sure this is such a good idea, anyway ; if it's for load/save workflow improvements, wouldn't it be better to have a file access method that allows for file re-opening? That said, there's a limit to *that* before you just have to say, "Just use /data/".
318 lines
8.0 KiB
Plaintext
318 lines
8.0 KiB
Plaintext
This is a list of the different
|
|
additional permissions in KittenOS
|
|
NEO as distributed, and their
|
|
purposes.
|
|
|
|
Installable service documentation is
|
|
provided with the respective -doc
|
|
packages, and goes under the rs-*
|
|
namespace.
|
|
|
|
For programs with the prefixes "svc-"
|
|
or "app-", they can register their
|
|
services using "r.svc.mysvcname"
|
|
(for the program "svc-mysvcname"),
|
|
or "r.app.myappname" (for the
|
|
program "app-myappname") - this
|
|
MAY have any postfix matching the
|
|
pattern "/[a-z0-9/%.]*$", or none
|
|
at all.
|
|
|
|
Examples:
|
|
|
|
r.app.nucleus:
|
|
Registers x.app.nucleus from
|
|
app-nucleus
|
|
|
|
r.svc.nucleus/ABCD:
|
|
Registers x.svc.nucleus/ABCD from
|
|
svc-nucleus
|
|
|
|
For how this registration works,
|
|
and how to access the resulting
|
|
service, please see the kn-perms
|
|
document.
|
|
|
|
APIs registered in this manner are
|
|
accessible to all programs by
|
|
default. However, local security
|
|
policy may be altered by the user,
|
|
and part of x.neo.pub.base's API is
|
|
to allow locking any of your public
|
|
APIs. (The user can override this
|
|
mechanism if they so wish, and this
|
|
will cause a silent failure of the
|
|
lockPerm function.)
|
|
|
|
As for the system APIs...
|
|
|
|
-- x.neo.pub.base @ sys-icecap --
|
|
|
|
Gaining access to this API creates
|
|
this application's data directory,
|
|
wherever that is.
|
|
|
|
Paths for the IO parts of this API
|
|
must start with "/", and must follow
|
|
the standard KittenOS NEO path
|
|
safety rules in the kernel.
|
|
|
|
showFileDialogAsync(mode, dfn):
|
|
Shows a filedialog with a given
|
|
filemode, or nil for "none".
|
|
Returns a new, empty table as a
|
|
"tag", and emits a "filedialog"
|
|
event on completion.
|
|
dfn meanwhile adds an 'Implied'
|
|
button for reasonable default file
|
|
names.
|
|
|
|
myApi: A string such as "svc.abc"
|
|
for the program svc-abc, used for
|
|
automatically finding the correct
|
|
API name to register for your app.
|
|
|
|
lockPerm(perm): Changes the default
|
|
permission setting for anything the
|
|
process should have permission to
|
|
define according to the matchesSvc
|
|
function, so that the user must be
|
|
asked before a program can access
|
|
the permission.
|
|
This function should be called
|
|
*before* you register your API, not
|
|
after, in case your service was
|
|
automatically started.
|
|
|
|
NOTE: LIST REQUIRES "/" AT THE END
|
|
AND START, WHILE THE REST CANNOT
|
|
HAVE IT AT THE END BUT MUST AT THE
|
|
START, BECAUSE THE ROOT IS "/".
|
|
There's logic here, specifically to
|
|
stop you trying to do nonsense like
|
|
deleting your own data directory...
|
|
|
|
list(path): After ensuring that the
|
|
path has a "/" at the end, lists
|
|
the contents of a directory
|
|
accessible to the application.
|
|
Returns a table containing
|
|
file/directory names, with "/"
|
|
postfixes for directories. If this
|
|
contains the invalid names "." or
|
|
"..", please report as a bug at
|
|
once, this shouldn't happen.
|
|
|
|
Everything after here ensures that
|
|
there is a "/" at the start and no
|
|
"/" at the end
|
|
|
|
makeDirectory(path): Creates the
|
|
directory with the given path.
|
|
Returns whatever the component call
|
|
did.
|
|
|
|
rename(pathA, pathB): Renames or
|
|
moves a file or directory around.
|
|
Returns whatever the component call
|
|
did.
|
|
|
|
open(path, mode): Opens a file with
|
|
a given mode (see ul-fwrap for the
|
|
list of modes).
|
|
Returns the file object,
|
|
|
|
remove(path): Removes a file.
|
|
|
|
stat(path): "I got lazy, so I took 3
|
|
API functions and combined them as
|
|
one API function!" - 20kdc
|
|
Returns {
|
|
isDirectory
|
|
size
|
|
lastModified
|
|
}
|
|
|
|
spaceUsed, spaceTotal, isReadOnly:
|
|
The filesystem proxy functions.
|
|
|
|
Events:
|
|
api, "filedialog", tag, res
|
|
|
|
-- x.neo.pub.session @ <a shell> --
|
|
|
|
This API must be implemented by any
|
|
program that the user wants to use
|
|
as a shell.
|
|
|
|
A shell should set up a Saving Throw
|
|
with sys-glacier in case of errors.
|
|
|
|
endSession(backToInit): Stops the
|
|
current session, and optionally
|
|
starts up sys-init.
|
|
endSession(false) is for switching
|
|
to a new shell.
|
|
endSession(true) is for logging out
|
|
of the session.
|
|
|
|
getMonitors(): Returns an ipairs-
|
|
form list of screen addresses for
|
|
use in disclaimMonitor and the
|
|
subsequent screens.claim call.
|
|
|
|
disclaimMonitor(address):
|
|
Disclaims a monitor. Returns true
|
|
on success. The monitor may be
|
|
reclaimed if something causes the
|
|
shell to be notified of the
|
|
monitor's existence (such as a
|
|
monitor rescan in Glacier).
|
|
|
|
No events are given. Deregistration
|
|
is equivalent to stating that you
|
|
are no longer in control of the
|
|
session, and that something else is.
|
|
|
|
-- x.neo.pub.window @ sys-everest --
|
|
|
|
This API is the reference definition
|
|
of how the windowing system works in
|
|
KittenOS NEO.
|
|
|
|
As this is kind of a book by itself,
|
|
further details are in us-evrst.
|
|
|
|
-- x.neo.sys.manage @ sys-glacier --
|
|
|
|
This API manages settings, shutdown,
|
|
and the "Saving Throw" mechanism.
|
|
|
|
Obviously, it's kind of dangerous.
|
|
|
|
Regarding settings, see us-setti for
|
|
details.
|
|
|
|
listSettings(): Returns an ipairs
|
|
form list of the setting names on
|
|
the system.
|
|
getSetting(name): Returns the string
|
|
contents of a setting.
|
|
delSetting(name): Deletes a setting.
|
|
Some settings are undeletable, and
|
|
will become "" if 'deleted'.
|
|
Any default settings will replace
|
|
deleted settings on reboot.
|
|
setSetting(name, val): Sets a
|
|
setting to a given string value.
|
|
registerForShutdownEvent():
|
|
Accepts the responsibility of
|
|
handling shutdown events, and
|
|
causes them to be sent to the
|
|
calling process.
|
|
registerSavingThrow(st):
|
|
Sets up a callback to be called
|
|
post-mortem if the calling process
|
|
died in an unusual manner.
|
|
shutdown(reboot):
|
|
Shuts down the system carefully.
|
|
|
|
Events:
|
|
api, "set_setting", name, val
|
|
A setting has been set.
|
|
The value may be nil, in case of
|
|
a deleted setting.
|
|
|
|
api, "shutdown", reboot, accept()
|
|
A shutdown is in progress. Call the
|
|
accept function once you are OK to
|
|
shutdown.
|
|
|
|
-- x.neo.sys.screens @ sys-glacier --
|
|
|
|
This API manages screens, and sends
|
|
events when screens are available,
|
|
or screens you have are lost.
|
|
|
|
You should pcall around all GPU use
|
|
in case of sudden GPU loss.
|
|
|
|
getMonitorByKeyboard(kb): Gets a
|
|
monitor address by the keyboard.
|
|
This may include monitors you have
|
|
no claim to.
|
|
To speed things up, the last result
|
|
is cached (because getKeyboards is
|
|
extremely slow for some reason)
|
|
getClaimable(): Returns an ipairs-
|
|
form list of monitor addresses.
|
|
claim(address): Attempts to claim
|
|
a monitor. If successful, returns
|
|
a GPU-binding callback (which must
|
|
be called whenever you want to use
|
|
the GPU), and the monitor proxy.
|
|
The GPU binding callback returns
|
|
two things: The GPU (which may be
|
|
rebound upon the call) and an
|
|
indicator that the GPU may have
|
|
been altered.
|
|
disclaim(address): Disclaims the
|
|
monitor given by the address.
|
|
|
|
Events:
|
|
|
|
api, "available", address: Indicates
|
|
that a monitor can be claimed.
|
|
|
|
api, "lost", address: Indicates that
|
|
a monitor has been lost.
|
|
|
|
-- x.neo.pub.globals @ sys-glacier --
|
|
|
|
This API is a "lite" version of some
|
|
other APIs that is not a security
|
|
issue to give to any program that
|
|
asks for it.
|
|
|
|
getKnownMonitors(): Returns ipairs
|
|
form table of the format:
|
|
{address, claimed, settings...}
|
|
where settings is w,h,d,t
|
|
The settings returned are always
|
|
compatible with the settings you
|
|
can give to changeMonitorSetup.
|
|
changeMonitorSetup(ma, w, h, d, t):
|
|
Changes the configured setup of a
|
|
monitor. Try not to abuse this, or
|
|
I'll make it silently fail and
|
|
change it to a more restricted API
|
|
that you can't abuse as much.
|
|
forceRescan(): Forces a rescan.
|
|
Again, don't abuse this.
|
|
getSetting(name): Returns a setting
|
|
prefixed with "pub." implicitly.
|
|
delSetting(name): Deletes a setting
|
|
prefixed with "pub." implicitly.
|
|
Attempting to delete an undeletable
|
|
setting will only set the value
|
|
to "".
|
|
setSetting(name, val): Sets a
|
|
setting prefixed with "pub."
|
|
implicitly.
|
|
|
|
Events:
|
|
|
|
api, "set_setting", name, val
|
|
|
|
NOTE: name is prefixed, as it
|
|
includes the screen settings.
|
|
This gets sent even if you have
|
|
the main settings permission, just
|
|
in case of unexpected oddities.
|
|
|
|
-- This is released into
|
|
the public domain.
|
|
-- No warranty is provided,
|
|
implied or otherwise.
|
|
|