next_inactive up previous


HostProcControl: Programming Guide
DocumentId:GradSoft-PR-e-22.08.2000-1.0b


Contents

Project mission

HostProcControl is a CORBA service, which provides API for remote managing of an operating system. Using HostProcControl, you can create CORBA-objects able to give:

  1. an access to host file system at the rate of:
    1. reading and writing of files;
    2. deleting of files;
    3. checking of files status;
  2. an access to processes at the host at the rate of:
    1. receiving of the list of process running;
    2. reading parameters of a single process specified;
    3. starting processes; and
    4. killing ones.
You can use HostProcControl with several ORB realizations such as TAO, omniORB and ORBacus for UNIX and with ORBacus only for Windows NT (see Administration Guide in the file AdministrationGuide_eng.pdf for more details). The package is written on C++ and being distributed in the form of source code.

General rules to use

An overall using procedure

There are three types of HostProcControl CORBA-object:

  1. HostControlHome;
  2. HostControl;
  3. FileReader;
  4. FileWriter.
The first is created automatically when server starts, the rest are created via it:
  1. HostControl: being created via HostControlHome;
  2. FileWriter and FileReader: being created via HostControl.
Thus, an overall procedure of using HostProcControl functionality consists of following steps:
  1. ORB initialization, obtaining of HostControlHome initial object reference;
  2. Getting instance of HostControlHome;
  3. Creating instance of HostControl;
  4. Using HostControl; creating, using, and deleting FileReader and FileWriter;
  5. Deleting HostControl.
An order of obtaining of initial object reference depends on manner of its representation; the last is described in Administration Guide.

Brief object characterization

  1. HostControlHome:

  2. HostControl:

  3. FileReader:

  4. FileWriter:


Access permissions control

All HostProcControl functionality is accessible via object named HostControl. Checking if client access permitted is carried out before the creation of this object. To create HostControl object, client invokes HostControlHome's getHostControl method with two parameters considering to be a complex "client ID" consisting of user name and user password. HostControlHome receives ID and seeks the same in user list. User list is the file at the host being edited by service administrator and being composed of strings like following: 

John : Johnson
A.E.Belyaev:265-60-43
<another_name>:<another_password>
Access permits if ID corresponding has been found, and not permits otherwise.


Lifetime of objects

The common rule reads as follows: client must not remember to destroy each object created by itself. Nevertheless, you can command to object such as HostControl, FileReader and FileWriter to destroy itself in the case having not been used during some timeout fixed. For this pupose every object has a set_timeout method being invoked with timeout value for the object (in seconds) as a parameter. There are next features of timeout control system now:

  1. calling set_timeout(0) means return to default infinite-timeout state, i.e. "zero equal to infinity" in present context;
  2. next acts are considered to be "using" of the object:
    1. creating object;
    2. calling any object's methods excluding methods close() and destroy();
  3. HostControl parent object can not be automatically destructed while at least one of its daughter object exists;
  4. destruction of HostControl's daughter object fullfils in fact by parent object and conforms to evident using of HostControl.

Objects characterization

HostControlHome

Overview

This HostControlHome object is created automatically when server starts. This is a "root" object of the service. Depending on server options used, an access to this object may be obtained via three (different) vays (see Administration Guide for details):

The goal of the object is to check access permissions and to create HostControl object if check-up has been succesfull (see subsection Access permissions control for more details 2.3).

Interface 

     interface HostControlHome
     {
         HostControl
             getHostControl(in string name, in string password)
                 raises(LoginIncorrect);
     };


Description of the method getHostControl

  1. Functioning: This method getHostControl checks presence of record composed from name and password values (regarding as "client ID") in user list connected with the server 2.3. If check-out is successful, an example of HostControl object is created. If "client ID" is not recorded in the user list, then LoginIncorrect exception is thrown 4.1. If check-out is impossible (user list not found or can not be opend), then AccessControlFailure exception is thrown 4.2

  2. Parameters:
    1. name - represents a user name
    2. password - represents a user password

  3. Return: HostControl object

Example

Let we have corbaloc style IOR passed into our client application via option such a following: 
   -ORBInitRef HostControlService=corbaloc::127.0.0.1:1025/HostControlService
Using next code presented we get accesss to HostControlHome and try to create HostControl object: 
   /* variables needed */
   Object_var          obj;
   HostControl_var     hostControl;
   HostControlHome_var hostControlHome;

   /* ORB initialization using options from the command line */
   myORB = ORB_init(argc,argv); 

      /* getting access to HostControlHome */
      obj = myORB->resolve_initial_references( "HostControlService" );
      hostControlHome = HostControlHome::_narrow(obj);

   /* getting client ID */
   char name[]="name";
   char password[]="password";

   try {
      /* trying to create HostControl */
      hostControl = hostControlHome->getHostControl(name,password);

   } catch ( const LoginIncorrect& ex ) {
     /* error message may be present here */
     goto quit;
   } 
   /* using of HostControl may be present here */

   /* deleting of HostControl */
   hostControl->destroy();

quit: 
   myORB->destroy();

HostControl

Overview

This HostControl object is the most powerfull object of the service. It's held the next functionality:

  1. process control at the rate of:
    1. obtaining list of processes exist;
    2. reading parameters of single process specified;
    3. starting processes;
    4. killing processes;
  2. deleting files, reading status of the files;
  3. creating daughter objects FileReader and FileWriter to access to file contents.

Interface 

  interface HostControl
  {
    ProcInfoSeq getProcsInfo() raises(HostError);
    ProcInfo getProcInfoByPid(in unsigned long pid) raises(HostError);

    unsigned long bornProcByName(in string name,in StringSeq args) raises(HostError);
    void killProcByName(in short signal, in string name) raises(HostError);
    void killProcByPid(in short signal, in unsigned long pid) raises(HostError);

    FileReader createFileReader(in string path) raises(HostError);
    FileWriter createFileWriter(in string path,in WriteMode mode) raises(HostError);

    boolean statFile(in string path, in char arg) raises(HostError);
    void rmFile(in string path) raises(HostError);

    void set_timeout(in unsigned long timeout);
    void destroy();
  };

Description of the methods

A. Methods to process control

B. Methods to control of the host file system: C. Methods to support:

Examples

Let us assume "hostControlHome" is object variable obtained as stated above and "<learner>:<test>" is string in user list;

  1. next code outtypes the list of processes working at the host: 
       HostControl_var hostControl;
   ProcInfoSeq_var procseq;

   /* create HostControl object */
   try {
      hostControl = hostControlHome->getHostControl("learner","test");
   } catch ( const LoginIncorrect& ex ) {
      /* error message: ... */
      goto quit;
   }
     /* obtain the process list */
     procseq = hostControl->getProcsInfo();

   /* outtype process list */
   for(int i = 0; i< procseq->length() ;  i++) {
       cout << procseq[i].pid  << "  ";
       cout << procseq[i].name << "  ";
       cout << procseq[i].ppid << endl;
   }

   /* destroy the object */
   hostControl->destroy();

quit:
   .....

  2. next code check if the fusty file "garbage.txt" exist and then removes it: 

       HostControl_var hostControl;

   /* create HostControl object */
   try {
      hostControl = hostControlHome->getHostControl("learner","test");
   } catch ( const LoginIncorrect& ex ) {
      /* error message: ... */
      goto quit;
   }

   if ( hostControl->statFile("garbage.txt",'f') ) {
      hostControl->rmFile("garbage.txt")
   }
 
   /* destruction of the object */
   hostControl->destroy();

quit:
   .....

FileReader

This object FileReader provides access to byte sequence type data stored in remote file being opend at the time of creating of the object by means of HostControl::createFileReader 3.2.3.

Interface 

  interface FileReader
  {
    OctSeq
        read(in unsigned long nbytes, out unsigned long actual_nbytes)
             raises(HostError);

    boolean eof() raises(HostError);

    void set_timeout(in unsigned long timeout );

    void close() raises(HostError);
  };

Description of methods

Example

Let us assume that "hostControl" is object variable obtained as stated above; next code copies remote file demo.txt into standard output: 

   /* create FileRedader object */
   FileReader_var freader = hostControl->createFileRedader("demo.txt");

   OctSeq_var data = new OctSeq;
   const int buffer_size = 10000;
   data -> length( buffer_size );

   char buff[buffer_size+1];
   int readed;
   do {
          /* read the portion of data from the file */
          data = filereader->read( buffer_size, readed );

      /* send data into standard output */
      memcpy(buff,data->get_buffer(),readed);
      buff[readed+1]='\0';
      cout << buff;
   } while ( readed==buffer_size ); // repeat while not eof reached 

   /* close file and destroy FileReader object */
   freader->close();

FileWriter

This object FileWriter wrtes byte sequence type data into remote file being opend at the time of creating of the object by means of HostControl::createFileWriter 3.2.3.

Interface 

  interface FileWriter
  {
    void     write(in unsigned long nbytes, in OctSeq bytes) raises(HostError);

    void     set_timeout(in unsigned long timeout);

    void     close() raises(HostError);  \
  };

Description of methods

Example

Let us assume that "hostControl" is object variable obtained as stated above; next code copies file demo.txt from client to host: 

   /* create FileWriter object*/
   FileWriter_var filewriter = hostControl->createFileWriter( "demo.txt", UAKG_enRewrite ); 
   /* create file to read */
   FILE* file = fopen("demo.txt","rb"); 

   const int buffer_size = 10000;
   OctSeq_var buf = new OctSeq; 
   buf -> length( buffer_size );

   int  readed;
   while ( !feof( file ) ) {
       /* read data from the local file */
       readed = fread(buf->data(),1,buffer_size,file);

       /* write data to the remote file */
       filewriter->write(readed,buf);

       if ( ferror( file )) {
           break;
       }
   }
   /* close files and destroy FileWriter object */
   fclose( file );
   filewriter->close();

Description of exceptions may being thrown


InvalidLogin

This InvalidLogin exception arises when creating HostControl object in the case client invoking getHostControl is not registered in the user list (see description of HostControlHome::getHostControl method for details 3.1.3);


AccessControlFailure

This AccessControlFailure exception arises when creating HostControl object in the case access rights control is found to be impossible (for example, user list is not found) (see description of HostControlHome::getHostControl 3.1.3 too);

InvalidModeArgument

This InvalidModeArgument exception arises when invoking HostControl::statFile method for inadmissible value of second parameter "arg" (see description of HostControl::statFile method for details 3.2.3).

HostError

This is the general-duty exception arising in the case of system error at the host mashine occurs.

Model client application

This model client application demonstrates an order of access to HostProcControl functionality using corbaloc url. Specific rules to adapting of the server see in ORB documentation. 

using namespace CORBA;
static ORB_var myORB ;

#define NAME_LEN 20
#define PASSWD_LEN 20

int main(int argc,char** argv)
{
   char name[20],password[20];
   myORB = ORB_init(argc,argv); 
   Object_var  obj;
   int retval=1;
   try {
     obj=myORB->string_to_object(
         "corbaloc::x.internal.company.com:1000/HostControlService");
   } catch ( const SystemException& ex ) {
     cerr << argv[0] << ": Can\'t resolve HostControlService reference" << endl;
     goto quit;
   }
   if ( is_nil(obj)  ) {
     cerr << "Object is NULL" << endl;
     goto quit;
   }
   HostControlHome_var   hstCntrHome = HostControlHome::_narrow(obj);
   if ( is_nil(HstCntrHome) ) {
     cout << "Can\'t  narrow object " << endl;
     goto quit;
   }
   cout << "Enter name :" << flush ;
   cin.get_line(name,NAME_LEN);
   cout << "Enter password :" << flush;
   cin.get_line(password,PASSWD_LEN);
   HostControl_var hostControl ;
   try {
      hostControl = HstCntrHome->getHostControl(name,password);
   } catch (const SystemException&  ex ) {
      cerr << "System Exception" << endl;
      goto quit;
   } catch (const IncorrectLogin&  ex ) {
      cerr << "Login incorrect" << endl;
      goto quit;
   } 
   cout << "login succesfull" << endl;
   retval=0;
   //
   // do you work here.
   //
   hostControl->destroy();
quit:
   myORB->destroy();
   return retval;
}

Support

The package HostProcControl is created and supported by GradSoft company, the home page of GradSoft is http://www.gradsoft.com.ua/. The current release number of the project is HostProcControl-1.0.

History of changes

16.03.2001
- current revision;
22.02.2001
- first public revision.

next_inactive up previous
GradSoft