SFTP is a protocol that allows a byte stream to be transferred efficiently from point A to point B, using optimizations such as streaming for large files and piggybacking for small files. These optimizations are completely transparent to the programmer. The byte stream to be transferred can be a file in the file system or a file in virtual memory. A file in VM at one end need not be transferred into a file in VM at the other end; any combination is possible. An SFTP transfer can take place from either an RPC2 server to an RPC2 client or the other way around. However the request for the transfer is always initiated by the client. To avoid confusion, we will refer to the sending entity source and the receiving entity sink.
The average user of SFTP need not be aware of the details of SFTP related to acknowledgements, flow control etc. All he needs to specify are the details of the file transfer such as the name of the file, the transmission direction etc. These are specified by the user in a data structure called a Side Effect Descriptor. The side effect descriptor (shown in Appendix <@@ref>se.hXXX is used both at the client and the server ends to describe the details of the byte stream transfer. The side effect descriptor is not transmitted: each side provides its own local version.
The most relevant of the side effect descriptors fields are given below.
This describes the type of side effect used. Currently the only side effect that has been implemented is the SFTP file transfer side effect.
This is a union containing descriptor definitions for each type of side effect. The Tag field serves as the discriminant of the union. Currently, there is only one member of the union, corresponding to SFTP.
specifies if the transfer is from the server to the client (SERVERTOCLIENT) or from the client to the server (CLIENTTOSERVER).
specifies the initial position from where a file should be read from, or written to. This is useful, for instance, when bytes are appended to a file.
specifies the maximum number of data bytes to be sent or received. A value of -1 implies a limit of infinity. The RPC call fails if an attempt is made to transfer more bytes.
is an output parameter. On completion of the file transfer, it specifies the number of bytes actually transferred.
indicates whether the file to be transferred is specified by its name, its inode number, or by its VM address.
is a union type, discriminated by the previous Tag field, that specifies the local identity of the file to be transferred. Note that there is no information of the remote identity of the file.
An example of an RPC subsystem which uses SFTP is given in the following section. In describing the use of SFTP, we will refer to this example and outline the steps used. The client-server code using SFTP is very similar to that of an RPC which does not use SFTP. Hence , we will only describe the additional steps needed when making an RPC which uses SFTP.
The fields of the SFTP_Initializer specify parameters of the SFTP file transfer protocol, and include items such as the window size, packet size etc. These can be set by the user, or can be set to default values by calling the SFTP_SetDefaults primitive. The SFTP_Initializer is then activated using the SFTP_Activate primitive. Note that the SFTP package should be activated before the RPC2 package is initialized.