IProcessService Interface Reference


Description

IProcessService is the interface to the Process Service in the KreaTV TV Application Platform. The Process Service is internal to the platform and not intended for use by applications.

import "IProcessService.idl";

List of all members.

Public Member Functions

void SetEnv (in string name, in string value) raises (TToiInvalidArgumentException, TToiPermissionDeniedException)
void UnsetEnv (in string name) raises (TToiInvalidArgumentException, TToiPermissionDeniedException)
void CreateProcess (in string args, in TEnvironmentList env, in TPrivileges privileges, in string observerAddress, out long pid) raises (TToiInvalidArgumentException, TToiPermissionDeniedException, TToiNotEnoughResourcesException)
void ExitProcess (in long pid, in long signal, in long timeout) raises (TToiInvalidArgumentException, TToiPermissionDeniedException)
void DestroyProcess (in long pid) raises (TToiInvalidArgumentException, TToiPermissionDeniedException)
void OnIpAddressChanged ()
void PeekDeviceLog (out string outputFileName)

Public Types

enum  TPrivileges { PRIVILEGES_PLATFORM, PRIVILEGES_APPLICATION }
typedef sequence< string > TEnvironmentList

Member Enumeration Documentation

The TPrivileges datatype enumerates the security classes used when spawning new processes.

Enumerator:
PRIVILEGES_PLATFORM 

Processes with platform privileges may use the Process Service to create new processes with either platform or application priviliges.

PRIVILEGES_APPLICATION 

Processes with application privileges may not use the Process Service to create new processes.


Member Function Documentation

void IProcessService::CreateProcess ( in string  args,
in TEnvironmentList  env,
in TPrivileges  privileges,
in string  observerAddress,
out long  pid 
) raises (TToiInvalidArgumentException, TToiPermissionDeniedException, TToiNotEnoughResourcesException)

Create a new process. The function is syncronous, i.e., the process has been started when it returns. This however is no guarantee that the process does actually exist. It may still be loading, or perhaps it could not load at all for some reason. When the process exits the client is guaranteed to be notified about that event by a call to IProcessObserver::ProcessExit().

Parameters:
args The argument string passed to the process. The first token must be the name and path of the process executable. The rest are additional command line arguments in normal shell syntax.
env An array of environment strings on the form "name=value" which gets appended to the environment of the caller to form the environment for the created process.
privileges A constant indicating the privileges of the new process.
observerAddress The address to the IProcessObserver interface on which events regarding this process will be reported.
Return values:
pid The process identifier for the newly spawned process. This is the identifier to pass to KillProcess() when the caller wants the process dead.
Exceptions:
TToiPermissionDeniedException A permission denied exception will be raised if the caller lacks the privileges to start a new process with the priviliges specified in the call.
TToiInvalidArgumentException An invalid argument exception will be raised if args are not given in valid shell syntax, env does not follow the "name=value" format, priviliges is an unknown constant, or observerAddress does not identify a valid IProcessObserver interface.
TToiNotEnoughResourcesException A not enough resources exception will be raised if there are no users left in the range of allowed Process Service users, or if the system could not create a new process for some reason.
See also:
IProcessObserver
void IProcessService::DestroyProcess ( in long  pid  )  raises (TToiInvalidArgumentException, TToiPermissionDeniedException)

Deallocate all resources associated with a process. The caller must have received an IProcessObserver::OnProcessExit() message for the process before it is allowed to call this function. Deallocating resources includes deleting all files left behind by the process and its children, if any. On success, the Process Service has discarded all references to the process when this function returns.

Parameters:
pid The ID of the process to destroy.
Exceptions:
TToiPermissionDeniedException A permission denied exception will be raised if the process was not originally created by the caller, or if the process has not yet exit.
TToiInvalidArgumentException An invalid argument exception will be raised if pid does not identify a process previously created with CreateProcess().
See also:
IProcessObserver
void IProcessService::ExitProcess ( in long  pid,
in long  signal,
in long  timeout 
) raises (TToiInvalidArgumentException, TToiPermissionDeniedException)

Exit a process, which means killing it if necessary, including child processes spawned by this processes. This function is asyncronous, i.e. it returns immediately. When the process has eventually exit, an IProcessObserver::OnProcessExit() message will be generated, regardless of the process exit as a result of a call to this function or it exit for any other reason. Only processes explicitly created through a CreateProcess() call may be killed using ExitProcess().

Parameters:
pid The ID of the process to exit.
signal Try first killing the process with this signal.
timeout The time in milliseconds the Process Service will wait for the process to exit nicely after the first signal has been sent. If this timeout expires the process will be killed with SIGKILL.
Exceptions:
TToiPermissionDeniedException A permission denied exception will be raised if the process was not originally created by the caller.
TToiInvalidArgumentException An invalid argument exception will be raised if pid does not identify a process previously created with CreateProcess(), or signal is not a valid signal.
See also:
IProcessObserver
void IProcessService::OnIpAddressChanged (  ) 

This methid is called from the information service when the ip address of the box changes.

void IProcessService::PeekDeviceLog ( out string  outputFileName  ) 

Get content of log managed by process service.

void IProcessService::SetEnv ( in string  name,
in string  value 
) raises (TToiInvalidArgumentException, TToiPermissionDeniedException)

Set an environment variable in the Process Service environment of the caller. This environment is used only for initializing the real environment of new processes created for the caller by the Process Service. This function does not affect the actual operating system environment of the calling process.

Exceptions:
TToiPermissionDeniedException A permission denied exception will be raised if the caller lacks the privileges to start new processes.
TToiInvalidArgumentException An invalid argument exception will be raised if name contains an equal character.
void IProcessService::UnsetEnv ( in string  name  )  raises (TToiInvalidArgumentException, TToiPermissionDeniedException)

Remove an environment variable from the Process Service environment of the caller. This environment is used only for initializing the real environment of new processes created for the caller by the Process Service. This function does not affect the actual operating system environment of the calling process.

Exceptions:
TToiPermissionDeniedException A permission denied exception will be raised if the caller lacks the privileges to start new processes.
TToiInvalidArgumentException An invalid argument exception will be raised if name contains an equal character.