############################################################################## # # Copyright (c) 1999 by # blaxxun interactive Inc, San Francisco, California, USA # All rights reserved # # MODULE NAME: $RCSfile: ftdoc.txt,v $ # REVISION: $Revision: 1.2 $ # DATE: $Date: 2000/03/29 04:22:22 $ # AUTHOR: $Author: peter $ # STATE: $State: Exp $ # # PROJECT: BSI # SYSTEM: server - server processes # SUBSYSTEM: ftserver - file transfer # # $Log: ftdoc.txt,v $ # Revision 1.2 2000/03/29 04:22:22 peter # added the server interface description # # Revision 1.1 1999/12/13 04:19:56 peter # Initial revision # # ############################################################################## # # FT - File Transfer Service # # ftdoc.txt - Documentation #Table of Contents:
The File Transfer Service allows to transfer files from one machine running blaxxun Contact to another machine. This is roughly how it works.
The sender creates a show document url and sends it to the receiver. The show document url is of the following form.
In either case the filename cannot contain the string "..", i.e. two dots in a row. This is to ensure that the transfer mechanism cannot be used to transfer arbitrary files from the sender's hard drive. The strings prefix and postfix are not interpreted by the transfer mechansim.
The cybersockets layer of blaxxun Contact on the sender machine parses the show document url. It creates an 9 byte fileid and an internal mapping between this file id and the filename in the url. The fileid consists of a 32 bit random integer and a prefix character specifiing the protocol used by the sending client. U for UDP, T for TCP and H for HTTP.
The cybersockets layer then changes the url to
The new show document url is sent to the receiver(s).
For test purposes urls of the form
On each receiver machine the url is handed over to the web browser in use. The web browser contacts the cgi script ftfetch and requests the document.
ftfetch contacts the ftserver specified in its configuration and requests the file from the server.
The ftserver serving the request fetches the file from the sending client Contact installation. It uses the parameter CID from the URL in order to find out the IP address and port number of the sending client from the idserver.
The cybersockets layer of the sending client uses its file id filename mapping in order to determine the name of the file to transfer.
ftfetch determines the mimetype of the file to send based on the extension of the file transfered and a mapping it takes from its configuration.
PROJECT: BSI
SYSTEM: server - server processes
SUBSYSTEM: ftserver - file transfer
COMPONENT: ftsocket - client interface for file transfer
DESCRIPTION:
The interface to be linked into cybersockets.
PROJECT: BSI
SYSTEM: server - server processes
SUBSYSTEM: ftserver - file transfer service
DESCRIPTION:
Include file for file transfer service
PROJECT: BSI
SYSTEM: server - server processes
SUBSYSTEM: ftserver - file transfer server
DESCRIPTION:
Base functions used by server and cgi script.
PROJECT: BSI
SYSTEM: server - server processes
SUBSYSTEM: ftserver - file transfer server
DESCRIPTION:
Event functions called. The functions given in this file are
the Event Functions of the API server ftserver.
PROJECT: server COMPONENT: ftserver - file transfer service DESCRIPTION: ftfetch - file transfer cgi program
PROJECT: server - COMMUNITY SERVER
SUBSYSTEM: ftserver - file transfer
COMPONENT: compress - transfer compression, decompression routines
DESCRIPTION:
Compression, decompression routines for network traffic
The client API of the file transfer service is called
from the cybersockets layer of blaxxun Contact.
The API functions are part of the WIN 32 library ivlib.lib.
This library has to be linked into blaxxun Contact.
3.1. Functions
contents
------------------------------------------------------------------------------
FUNCTION NAME: ftTransInit
DESCRIPTION:
Initialize a file transfer, parse and adopt the show document url
An url of the form
ftfetch?FIL=filename
is transfered to
ftfetch?FID=fileid&CID=clientid
where fileid is a 9 byte id for the file to be transfered
and clientid is the idserver client id of the sender as 8 byte string.
The first byte of the file id is
U if the sender uses UDP
T if the sender uses TCP
H if the sender uses HTTP.
The file has to reside in the directory "transfer".
The file is read into heap memory by this function.
File transfers time out after two minutes if the file
is not fetched by the ftserver and after 3 minutes
if the file is fetched.
RETURN VALUES:
int rc > 0: length of changed show document url to send
int rc == 0: just send the inbuf as is
int rc < 0: an error
------------------------------------------------------------------------------
*/
int ftTransInit(
int protocol, /* r: protocol used by client */
unsigned long sessionid, /* r: id of sender session */
const char * installdir, /* r: install directory of program */
const char * inbuf, /* r: show document url given by application */
size_t inbuflen, /* r: length of that url */
char * outbuf, /* w: buffer to write new url packet to */
size_t outbuflen /* r: length of that buffer */
)
------------------------------------------------------------------------------
FUNCTION NAME: ftTransPeriodic
DESCRIPTION:
Periodic handling of transfer service, clears buffer spaces of file
transfers that have timed out
RETURN VALUES:
void
------------------------------------------------------------------------------
*/
void ftTransPeriodic()
------------------------------------------------------------------------------
FUNCTION NAME: ftTransGetBuffer
DESCRIPTION:
Get a buffer from a transfer file at a specific offset.
This functions is called for each block fetch request sent
by the ftserver.
RETURN VALUES:
int rc > 0: length of the buffer filled
int rc == 0: the offset is out of range
------------------------------------------------------------------------------
*/
int ftTransGetBuffer(
unsigned long fid, /* r: file id of transfer file to read block for */
unsigned long offset, /* r: offset of block to read */
char * buffer /* w: buffer filled, must be FT_BUFFER_LENGTH bytes */
)
The CGI script is used by the receivers of the file transfer service in order to transfer the files to the receiver's web browser. ftfetch has to be installed into the csbin/community cgi directory of the Community Server installation.
------------------------------------------------------------------------------
FUNCTION NAME: main ftfetch
DESCRIPTION: The main of the ftfetch program.
The script has to be installed into csbin/community.
The scripts reads the variables g_FtServer and g_FtPort from
global.cfg in order to find out which ftserver to contact.
Example entries could be
g_FtServer localhost
g_FtPort 2020
The script reads the config file ./config/ftfetch.cfg in order
to determine the mimetypes of files transfered from their
extensions.
An example ftfetch.cfg file might be
# ftfetch.cfg
#
# extension to mimetype mapping
#
htm text/html
html text/html
exe application/octet-stream
class application/octet-stream
jpeg image/jpeg
jpg image/jpeg
jpe image/jpeg
gif image/gif
The script reads the CGI parameters FID and CID in order to
determine the ID of the file to fetch and the client id of
the client to fetch the file from.
The script uses raudp calls in order to fetch the blocks of the file
to transfer one by one from the ftserver.
The syntax of the raudp calls is:
raudp FT <FID> <CID> <OFF>
where
FID is the file id CGI parameter received
CID is the client id CGI parameter received
OFF is the offset of the block to fetch
Possible error conditions are.
- Timeout while contacting the ftserver
- Client id is unknown, the client to fetch the file from
has left the scene
- File id invalid, the client refuses to transfer the file
- Timeout while transfering the file
------------------------------------------------------------------------------
*/
int main( int argc, char *argv[] )
The ftserver is an API server that handles the raudp file block fetch requests from the cgi script ftfetch and requests the blocks of the file from the cybersockets layer of the sending client.
The ftserver has to be added to the idsever configuration file in order to be recognized by the idserver and to be able to determine the IP address and port number of a client given by its clientid. The ftserver subscribes the User New Log and the User Left event of the idserver.
The following should be added to etc/idserver.cfg
# The following enables the ftserver APISERVER localhost:2020
The ftserver buffers the file during the request, thus if multiple clients fetch the file, the file is only requested once from the sending client.
If the sending client uses UDP the ftserver fetches FT_BLOCKS_PER_FETCH
in each fetch request. If the client uses TCP or HTTP the ftserver
requests the entire file at once from the client.
5.1. UNIX Process - ftserver
contents
The UNIX process ftserver has the following command line interface.
ftserver -p port -i idhost:idport -BSIROOT rootdir [ -TRACE ]
-p port is the port the fterver listens on -i idhost:idport is the host and port number of the idserver the ftserver sould connect to -BSIROOT rootdir install directory of blaxxun Community Server -TRACE turns on trace mode
All parameters of ftserver are read from the Windows NT Registry.
The parameters are stored under LOCALMACHINE/SOFTWARE/blaxxuninteractive
The following values are stored there.
ftserverPort, see -p option above.
ftserverIdserverHostPort, see -i option above
InstallDirectory, see -BSIROOT option above.
ftserverTrace, if this option is set to on the -TRACE is activated.
6. Globals
contents
*/ /* * protocol specifiers used in the file id */ #define FT_PROTOCOL_UDP 'U' #define FT_PROTOCOL_TCP 'T' #define FT_PROTOCOL_HTTP 'H' /* * size of the blocks fetched */ #define FT_BUFFER_LENGTH 512 /* * number of blocks fetched at once in the UDP case */ #define FT_BLOCKS_PER_FETCH 6