Interface Specification for KOS Receiver

Overview

The KOS interface provides mechanisms for submitting a KP for execution, registering a KOS plugin, and sending a UNIX signal to a running KP.

Imported Interfaces

The following interfaces are imported:

KPRepr

Constants

The following constants are defined by this interface:

AlphaFormat

A String constant, with the value "Alpha System Submission Format"

Type Definitions

The following non-OBJECT types are defined by this interface:

String

An alias for ilu.CString

BinaryString

An alias for SEQUENCE OF BYTE

SBH

An alias for String, representing an ILU String Binding Handle.

KPID

An alias for String, representing the Kernel Process Identifier.

KOSAddress

An alias for String, representing the name of a kernel.

SubmissionType

An alias for String, representing the type of KP submission format being used.

Exceptions

The following exceptions are defined by this interface:

EncodingError

Raised when there is an error in the MIME-data packaging of a KP.

MetadataError

Raised when there is an error in the metadata content or there is missing metadata.

AuthorizationError

Raised when an access attempt is made on a KOS resource that the caller is not authorized to make.

ResourceError

Raised when a resource requirement declared in metadata cannot be met, or if there are errors in determining authorization of KOS resources.

CommunicationError

Raised when the KOS can not support the requested connection. This could be due to a transport error occurring during communication.

NotFound

Raised when the designated item is not found.

Receiver Objects

Receives KP submissions and plugin registration requests. These objects have the following methods:

SubmitKP (type : SubmissionType, repr : BinaryString) : KPID

Submit a KP in a representation defined by the type parameter. Currently the only allowed type is KOS.AlphaFormat, which indicates that type is a marshalled KPRepr.Representation object.

Before submission is allowed, the callers identity is checked to determine authorization. Proper authorization may be specified in config/access.conf in the <Limit SUBMIT> access group.

This method returns the KP identifier for the submitted KP, and can raise EncodingError, MetadataError, AuthorizationError, and ResourceError.

SubmitRepr (repr : KPRepr.Representation) : KPID

Submit a KP as defined in repr. With this routine, repr is an un-marshalled KPRepr.Representation object and so can be submitted without the overhead of unmarshal, for example when cloning a KP on the local KOS.

Before submission is allowed, the callers identity is checked to determine authorization and a check is made to insure that the reporting id is not a duplicate. Proper authorization may be specified in config/access.conf in the <Limit SUBMIT> access group.

This method returns the KP identifier for the submitted KP, and can raise MetadataError, AuthorizationError, and ResourceError.

KillKP (id : KPID, signal : INTEGER, password : String)

Send a UNIX signal to a KP. The password is valid if it is not the empty string.

Before the signal is delivered, the callers identity is checked to determine appropriate authorization. This authorization may be specified in config/access.conf in the <Limit KPKILL> access group.

This method can raise AuthorizationError (when a "bad" password (ha!) is used, or the caller has invalid permissions as specified in config/access.conf. It can also raise ResourceError if no KP for the specified id was found.

RegisterPlugin (pid : INTEGER) : SBH

Allocate a PluginEntry for a KOS plugin process. This assumes plugin entries are created by the kernel before it is launched. Returns the ILU String Binding Handle of the PluginEntry object.