OC-KittenOS/repository/docs/us-perms

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.