1
0
mirror of https://github.com/20kdc/OC-KittenOS.git synced 2024-11-01 08:10:58 +11:00
OC-KittenOS/repository/docs/us-perms
20kdc 0d9583fcff r8: Yet another release for a single feature request
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/".
2018-12-24 21:11:59 +00:00

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.