From kde-core-devel  Sat Mar 31 20:21:23 2001
From: Waldo Bastian <bastian () kde ! org>
Date: Sat, 31 Mar 2001 20:21:23 +0000
To: kde-core-devel
Subject: Re: KDE independant API for using ioslaves
X-MARC-Message: https://marc.info/?l=kde-core-devel&m=98606968221027

On Saturday 31 March 2001 08:43, aleXXX wrote:
> On Saturday 31 March 2001 17:55, Stephan Kulow wrote:
> > aleXXX wrote:
> > > Hi,
> > >
> > > would it be possible to write a completely KDE independant C API for
> > > using KDE ioslaves ?
> > > Since I think that the ioslaves are one of the best things in KDE, it
> > > would be cool if non KDE apps could potentially use them too. And since
> > > all the data flows through a pipe I think it could be possible.
> > >
> > > Any opinions ?
> >
> > The slaves are only 50% of the story. What you should rather do is
> > writing a API above the _jobs_, but this will be an ugly one as you don't
> > have signal and slots there :)
> >
> > Greetings, Stephan
>
> I was thinking of a way to be able to create an ioslave, and to call the
> functions of this ioslave and to receive the data from the ioslave. The
> ioslave is created by klauncher AFAIK, which class does then the actual
> communication with the ioslaves ?

I think this is not too hard. You basically need to do:
  dcop klauncher klauncher 'requestSlave(QString,QString,QString)' \
	http www.kde.org /tmp/mysocket

or even:
   kdeinit_wrapper kio_http http /dev/null /tmp/mysocket

with "http" the type of slave you want and "www.kde.org" the host you want to 
use (that's optional I guess) and "/tmp/mysocket" a Unix domain socket.

Then your slave will connect to the socket that you specified and you can 
send it the commands listed in slaveinterface.h and you might get some 
informational messages back followed by either CMD_OK or CMD_ERROR.
error codes are listed in global.h

The format on the wire consists of 10 bytes header + payload. See 
Connection::read() The 10 bytes header is as follows:
0-5 : string representing length of payload in hex.
6: nul
7-8: string representing command in hex.
9: nul

The payload is formatted with Qt's << and >> operators. There is a white 
paper somewhere that documents this.

You can find the payload formatting for most slave commands in 
void SlaveBase::dispatch( int command, const QByteArray &data )               
  
Some special thinks you need to take care of:
* Before you use a host/port/user/passwd combination for the first time you 
have to issue a CMD_HOST
* Sometimes you have to respond to a command send by the slave. The ones that 
I am aware of are:
MSG_DATA_REQ: The slave wants data e.g. when doing a "CMD_PUT".
INF_MIMETYPE: The slave waits for a CMD_NONE before continueing.
MSG_NEED_SUBURL_DATA: Only used if you use sub-urls. (Dont :-)
INF_NEED_PASSWD: You need to send CMD_USERPASS.

A fundemantal problem however, is that the slave-interface is subject to 
change (expansion) and that we provide for backwards compatibility in the KIO 
framework, but not in the wire-protocol.

E.g. for KDE 2.2 slaves will be provided with their configuration via the 
wire-protocol instead of reading the config-files themselves. If your 
C-application is written for 2.1 it will fail to provide config info when 
running with 2.2.

Cheers,
Waldo
-- 
bastian@kde.org | SuSE Labs KDE Developer | bastian@suse.com