This guide describes how to use the FTPc Wimp Messages to do multitasking ftp transfers from your own programs. To illustrate their use, I've included an example ("FTPcDemo") with the distribution in BASIC which illustrates the use of the messages at the most basic level. It uses <A HREF="#FTPcBasLib">FTPcBasLib</A> which is inside !FTPc.
<H4>Concept</H4>
<P>
The basis of the system is that you send FTPc a command (FTPc_Command) and wait for a reply (FTPc_Reply or FTPc_ConnectionClosed) - this is the equivalent of a function call and generally you should wait for a reply before sending another command in the same session. Which command is sent to FTPc is detemined by the command code. You can, optionally, have FTPc display a status window to show the progress of the transfer, so there is no need for a wimp front end to your programs. All connections and sessions are automatically closed when your program ends or FTPc quits.
<H4>Sessions</H4>
<P>
All the commands are associated with a session. Before you can use the commands you must open a session. This will give you a handle for that session for use in the various commands. You can have as may sessions open as you like so it is possible to do several transfers simultaneously from the same program.
<H4>The FTPc wimp message block (mb)</H4>
<P><TABLE BORDER=2>
<TR><TD WIDTH=59>mb+0
<TD WIDTH=263>block size - set to 256
<TR><TD>mb+4
<TD>sender
<TR><TD>mb+8
<TD>my_ref
<TR><TD>mb+12
<TD>your_ref
<TR><TD>mb+16
<TD>action_code
<TR><TD>mb+20
<TD>command_code
<TR><TD>mb+24
<TD>session handle
<TR><TD>mb+36
<TD>depends on command
<TR><TD>mb+32
<TD>depends on command
<TR><TD>mb+36
<TD>up to 220 bytes of data
</TABLE>
<P>
When sending commands the string at mb+36 can end in any character <32. Replies end in 0x0 0xd so you can read them in C or BASIC.
<H4>FTPc Wimp Messages (Action_codes)</H4>
<P><TABLE BORDER=2>
<TR><TD WIDTH=160><B>FTPC_Command</B>
<TD WIDTH=57>&52440
<TD WIDTH=213>Send command to FTPc
<TR><TD><B>FTPC_Reply</B>
<TD>&52441
<TD>Reply by FTPc when command is complete. The your_ref field of the poll block is correctly set to the my_ref of the FTPC_Command.
<TR><TD><B>FTPC_ConnectionClosed</B>
<TD>&52442
<TD>Reply by FTPc if the connection is closed unexpectedly.<BR>
The your_ref field of the poll block is correctly set to the my_ref of the FTPC_Command.<BR>
This may be a reply to any command but means the session is still open. There is no valid data a mb+36
</TABLE>
<P>
All FTPc_Commands should be sent UserMessageRecorded then if the message you sent is returned to you at Wimp_Poll event User_Message_Acknowledge !FTPc is not running.
<P>
The <B>open_session</B> command code should be broadcast and the sender in the poll block reply used for the other command codes.
<P>
When FTPc receives FTPC_Command it will reply with FTPC_Reply unless the connection closes whilst processing the command in which case FTPc replies with FTPC_Connection_Closed. An invalid session handle also returns FTPC_Connection_Closed A session handle which 0 is always invalid.
<P>
As replies to commands may occur across wimp polls you need to check Message_TaskCloseDown for FTPc closing between the sending of the command and waiting for the reply.
Parameters to the commands are in the form of a single string at mb+36. If a parameter has spaces in it, it should be put in single or double inverted commas.
<P>
In the table below 'remote' means a name in a format suitable for use at the remote end of the connection ie you need to use '/' as a directory separator for unix type servers. 'local' means a RISC OS style name.
<P>
A command code of -1 is always invalid
<H5>FTP Status String</H5>
<P>
The ftp status string in an FTPc_Reply is the response from the server. It consists of 3 digits followed by a textural explanation. For a successful command the first digit is '2' and is generally all that you require to know. Recursive commands like remove_directory always return successfully unless the connection closes. For full details of these FTP status replies see RFC 0959
<P><TABLE BORDER=2>
<TR><TD WIDTH=162><B>Command<BR>
at mb+20</B>
<TD ALIGN=CENTER WIDTH=31>
<TD WIDTH=128><B>FTPC_Command<BR>
</B>
<TD WIDTH=136><B>FTPC_Reply</B>
<TR><TD><B>open_session*</B><BR>
Used to find the task handle of FTPc and whether not it is running.<BR>
The command fails if FTPc is older than the version entered at mb+28<BR>
The minimum FTPc version should be 120
<TD ALIGN=CENTER>0
<TD><B>mb+28:</B> minimum FTPc version *100<BR>
<B>mb+36:</B> <session name>
<TD><B>mb+4:</B> contains the task handle of FTPc <BR>
<B>mb+24:</B> session handle<BR>
<B>mb+28: </B>is the FTPc version number * 100<BR>
<B>mb+36:</B> ftp status string
<TR><TD><B>close_session*</B><BR>
Closes session and the connection if it is open
<TD ALIGN=CENTER>1
<TD><B>mb+24:</B> session handle
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> ftp status string as returned by server<BR>
Quitting your program also closes the session
<TR><TD><B>connect*</B><BR>
Opens an ftp connection in the session if a connection is already open it is closed first
<TD ALIGN=CENTER>2
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> <ftp url><BR>
eg ftp://ftp.demon.co.uk
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> ftp status string as returned by server
<TR><TD><B>disconnect*</B><BR>
Disconnects an open ftp connection
<TD ALIGN=CENTER>3
<TD><B>mb+24:</B> session handle
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> ftp status string
<TR><TD><B>abort</B><BR>
aborts the command in progress and closes the connection but leaves the session open.<BR>
Makes the command in progress receive a FTPC_ConnectionClosed reply.
<TD ALIGN=CENTER>4
<TD><B>mb+24:</B> session handle
<TD>not replied to
<TR><TD><B>get_status</B><BR>
Get information about the status of the command in progress.
<TD ALIGN=CENTER>5
<TD><B>mb+24:</B> session handle
<TD><B>mb+24:</B> session handle<BR>
<B>mb+28:</B> flags<BR>
<B>bit 0:</B> connected(1),<BR>
<B>bit 1:</B>busy(1),idle(0)<BR>
<B>mb+32:</B> bytes transfered (if a busy doing a transfer command).<BR>
<B>mb+36:</B> ftp status string. Text after the status number is the text shown in the status window.
<TR><TD><B>list_dir*</B><BR>
Load a Directory in a format filtered by FTPc
<TD ALIGN=CENTER>6
<TD><B>mb+24:</B> session handle<BR>
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> ftp status string as returned by server
<TR><TD><B>list_dir_raw*</B><BR>
Load a Directory in the format supplied by the server
<TD ALIGN=CENTER>7
<TD><B>mb+24:</B> session handle<BR>
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> ftp status string as returned by server
<TR><TD><B>set_dir_to_first_line</B><BR>
makes <B>get_next_dir_line</B> <BR>
read the first line in the loaded directory - only needed if you want to read a directory a second time
<TD ALIGN=CENTER>8
<TD><B>mb+24:</B> session handle
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> ftp status string as returned by server
<TR><TD><B>get_next_dir_line</B> <BR>
read the next line in the loaded directory
<TD ALIGN=CENTER>9
<TD><B>mb+24:</B> session handle
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> ftp status string. If successful line is after the first 4 chars of the status message
<TR><TD><B>set_list_options*</B><BR>
Sets option flags to add to the list command
<TD ALIGN=CENTER>10
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> <option flags>
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> ftp status string
<TR><TD><B>change_directory*</B><BR>
Change the remote directory
<TD ALIGN=CENTER>11
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> <remote path>
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> ftp status string as returned by server
<TR><TD><B>change_directory_up*</B><BR>
changes remote directory to its parent directory
<TD ALIGN=CENTER>12
<TD><B>mb+24:</B> session handle
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> ftp status string as returned by server
<TR><TD><B>download_file*</B><BR>
download remote file to local file
<TD ALIGN=CENTER>13
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> <remote> <local>
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> ftp status string as returned by server
<TR><TD><B>upload_file*</B><BR>
upload local file to remote file
<TD ALIGN=CENTER>14
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> <local> <remote>
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> ftp status string as returned by server
<TR><TD><B>remove_file*</B><BR>
removes remote file
<TD ALIGN=CENTER>15
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> <remote file>
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> ftp status string as returned by server
<B>mb+36:</B> ftp status string as returned by server
<TR><TD><B>site*</B><BR>
send a site command
<TD ALIGN=CENTER>17
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> <parameter string>
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> ftp status string as returned by server
<TR><TD><B>new_directory*</B><BR>
Create a new directory
<TD ALIGN=CENTER>18
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> <remote path>
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> ftp status string as returned by server
<TR><TD><B>remove_directory*</B><BR>
Remove a directory (including contents)
<TD ALIGN=CENTER>19
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> <remote directory>
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> ftp status string as returned by server
<TR><TD><B>download_file_leaf*</B><BR>
Downloads a file to 'local directory' converting its name to a RISC OS filename
<TD ALIGN=CENTER>20
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> <remote file> <local directory>
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> ftp status string as returned by server
<TR><TD><B>upload_file_leaf*</B><BR>
Uploads a file from 'local directory' converting its name to a remote filename
<TD ALIGN=CENTER>21
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> <local file> <local directory>
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> ftp status string as returned by server
<TR><TD><B>download_dir_leaf*</B><BR>
Download directory to 'local directory' converting its name to a RISC OS filename
<TD ALIGN=CENTER>22
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> <remote dir> <local directory>
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> ftp status string as returned by server
<TR><TD><B>upload_dir_leaf*</B><BR>
Upload directory to server converting its leaf name to a remote file name
<TD ALIGN=CENTER>23
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36: </B><local directory>
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> ftp status string as returned by server
<TR><TD><B>upload_newer_time*</B><BR>
Files are only uploaded if they are newer than this time
<TD ALIGN=CENTER>24
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> 5 byte UTC time
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> ftp status string
<TR><TD><B>upload_newer_than_file*</B><BR>
Files are only uploaded if they are newer than the files stamp. If the file doesn't exist all files are uploaded.<B><BR>
</B>
<TD ALIGN=CENTER>25
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> <file name>
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> ftp status string
<TR><TD><B>remove_dir_contents*</B><BR>
Remove all the contents of the current remote directory<BR>
USE WITH CARE
<TD ALIGN=CENTER>26
<TD><B>mb+24:</B> session handle
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> ftp status string
<TR><TD><B>download_dir_contents*</B><BR>
Download the contents of the local directory to the current remote directory
<TD ALIGN=CENTER>27
<TD><B>mb+36: </B><local directory>
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> ftp status string
<TR><TD><B>upload_dir_contents*</B><BR>
Upload the contents of the local directory to the current remote directory
<TD ALIGN=CENTER>28
<TD><B>mb+36: </B><local directory>
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> ftp status string
<TR><TD><B>remove_empty_directory*</B><BR>
Remove an empty directory
<TD ALIGN=CENTER>29
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> <remote directory>
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> ftp status string as returned by server
<TR><TD><B>show_status</B><BR>
Show the status window<BR>
If it is open when a program ends it will stay open.
<TD ALIGN=CENTER>256
<TD><B>mb+24:</B> session handle
<TD>not replied to
<TR><TD><B>hide status</B><BR>
Hide the status window
<TD ALIGN=CENTER>257
<TD><B>mb+24:</B> session handle
<TD>not replied to
<TR><TD><B>set_client_status</B><BR>
Enter text into the status dialogue box
<TD ALIGN=CENTER>258
<TD><B>mb+24:</B> session handle<BR>
<B>mb+36:</B> <text>
<TD>not replied to
</TABLE>
<P>
<B>Notes</B>
<UL>
<LI>Each command with a * should wait for a <CODE>FTPC_Reply/FTPc_ConnectionClosed</CODE> before sending another command with a * in the same session.
<LI>Command codes ending in 'leaf' converts the file/directroy name on transfer
</UL>
<H4>Listing Directories</H4>
<P>
There are two directory formats available from FTPc, raw (<B>list_dir_raw</B>) and filtered (<B>list_dir</B>). The raw format is the format as supplied by the server and can vary from server to server. The filtered format is a basic directory format which is filtered by FTPc and should be more universal - if the FTPc viewer window shows it this listing will work.
<H5>Filtered format</H5>
<P>
<TT>200 D 1234 filename</TT>
<P><TABLE BORDER=2>
<TR><TD WIDTH=132><B>field</B>
<TD WIDTH=88><B>position</B>
<TD WIDTH=137><B>Comments</B>
<TR><TD><B>Ftp status code</B>
<TD>0
<TD>
<TR><TD><B>Filer object type</B>
<TD>4
<TD>D - directory<BR>
F - file<BR>
L - Link
<TR><TD><B>File size</B><BR>
<TD>6
<TD>This may not be accurate. eg Vax directory displays give the number of blocks allocated
<TR><TD><B>Filename</B>
<TD>18
<TD>filename ending in 0x00 0xd
</TABLE>
<H5>Raw format</H5>
<P>
<CODE>200 drwxrwxrwx 1 root root 2048 Oct 23 10:04 incoming</CODE><BR>
<B>Typical unix type server output</B>
<P>
You can't rely on this format as it's server dependant. Not all lines may contain a file names, servers can add extra informational lines at the beginning and end of the listing.
<P><TABLE BORDER=2>
<TR><TD WIDTH=132><B>field</B>
<TD WIDTH=88><B>position</B>
<TD WIDTH=137><B>comments</B>
<TR><TD><B>Ftp status code</B>
<TD>0
<TD>
<TR><TD><B>Directory line </B>as supplied by the server
<TD>4
<TD>line ending in 0x00 0xd
</TABLE>
<H5>List Options</H5>
<P>
You can modify the listing output with <B>list_options</B>. These are likely to be server dependant and so is best avoided if portability is required.
<H4>Status Window</H4>
<P>
Each session can have a status window. It is opened with <B>show_status</B> and hidden with <B>hide_status. </B>You can add your own status message with <B>set_client_status</B>. None of these commands expect replies and can be called at any time.
<P>
<P>
Even if you don't open a status window in your program the user can open it from the <A HREF="#Sessions_Menu">sessions menu</A>. You can also close a connection or quit the client from the status window menu (Wimp_MQuit sent to client).
<P>
If the window is open when your program exits it stays open until explicitly hidden. You can read the status log or open a directory viewer to the connection from this window.
The <I>sessions</I> menu (off the iconbar menu) has an entry for every active session a client has with FTPc. Selecting a session opens its status window. The format of the entry is
<P>
client_task_name - session_name
<H4><A NAME="FTPcBasLib">FTPcBasLib</A></H4>
<P>
The FTPc BASIC library is simplifies the use of the commands from your own BASIC programs. It enables you to BASIC like a script file. See library for more details.
<P>
A typical program may be
<PRE> <B> LIBRARY "<FTPc$dir>.FTPcBasLib"</B>
REM PROCftpc_init starts the task and loads FTPc if it isn't
already loaded
<B>PROCftpc_init("Upload Website")</B>
REM if you were using the library from another application you should use
All commands which require replies are FN's the others PROC's. The string supplied to these functions are as described for <A HREF="#Command_codes">command codes</A> above.
<P>
All PROC's/FN's and global variables in the library start with ftpc_. When a FN/PROC is complete you can read the Wimp_Poll block at ftpc_pb%.