Programming Manual

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 FTPcBasLib which is inside !FTPc.

Concept

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.

Sessions

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.

The FTPc wimp message block (mb)

mb+0 block size - set to 256
mb+4 sender
mb+8 my_ref
mb+12 your_ref
mb+16 action_code
mb+20 command_code
mb+24 session handle
mb+36 depends on command
mb+32 depends on command
mb+36 up to 220 bytes of data

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.

FTPc Wimp Messages (Action_codes)

FTPC_Command &52440 Send command to FTPc
FTPC_Reply &52441 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.
FTPC_ConnectionClosed &52442 Reply by FTPc if the connection is closed unexpectedly.
The your_ref field of the poll block is correctly set to the my_ref of the FTPC_Command.
This may be a reply to any command but means the session is still open. There is no valid data a mb+36

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.

The open_session command code should be broadcast and the sender in the poll block reply used for the other command codes.

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.

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.

Command codes

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.

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.

A command code of -1 is always invalid

FTP Status String

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

Command
at mb+20
FTPC_Command
FTPC_Reply
open_session*
Used to find the task handle of FTPc and whether not it is running.
The command fails if FTPc is older than the version entered at mb+28
The minimum FTPc version should be 120
0 mb+28: minimum FTPc version *100
mb+36: <session name>
mb+4: contains the task handle of FTPc
mb+24: session handle
mb+28: is the FTPc version number * 100
mb+36: ftp status string
close_session*
Closes session and the connection if it is open
1 mb+24: session handle mb+24: session handle
mb+36: ftp status string as returned by server
Quitting your program also closes the session
connect*
Opens an ftp connection in the session if a connection is already open it is closed first
2 mb+24: session handle
mb+36: <ftp url>
eg ftp://ftp.demon.co.uk
mb+24: session handle
mb+36: ftp status string as returned by server
disconnect*
Disconnects an open ftp connection
3 mb+24: session handle mb+24: session handle
mb+36: ftp status string
abort
aborts the command in progress and closes the connection but leaves the session open.
Makes the command in progress receive a FTPC_ConnectionClosed reply.
4 mb+24: session handle not replied to
get_status
Get information about the status of the command in progress.
5 mb+24: session handle mb+24: session handle
mb+28: flags
bit 0: connected(1),
bit 1:busy(1),idle(0)
mb+32: bytes transfered (if a busy doing a transfer command).
mb+36: ftp status string. Text after the status number is the text shown in the status window.
list_dir*
Load a Directory in a format filtered by FTPc
6 mb+24: session handle
mb+24: session handle
mb+36: ftp status string as returned by server
list_dir_raw*
Load a Directory in the format supplied by the server
7 mb+24: session handle
mb+24: session handle
mb+36: ftp status string as returned by server
set_dir_to_first_line
makes get_next_dir_line
read the first line in the loaded directory - only needed if you want to read a directory a second time
8 mb+24: session handle mb+24: session handle
mb+36: ftp status string as returned by server
get_next_dir_line
read the next line in the loaded directory
9 mb+24: session handle mb+24: session handle
mb+36: ftp status string. If successful line is after the first 4 chars of the status message
set_list_options*
Sets option flags to add to the list command
10 mb+24: session handle
mb+36: <option flags>
mb+24: session handle
mb+36: ftp status string
change_directory*
Change the remote directory
11 mb+24: session handle
mb+36: <remote path>
mb+24: session handle
mb+36: ftp status string as returned by server
change_directory_up*
changes remote directory to its parent directory
12 mb+24: session handle mb+24: session handle
mb+36: ftp status string as returned by server
download_file*
download remote file to local file
13 mb+24: session handle
mb+36: <remote> <local>
mb+24: session handle
mb+36: ftp status string as returned by server
upload_file*
upload local file to remote file
14 mb+24: session handle
mb+36: <local> <remote>
mb+24: session handle
mb+36: ftp status string as returned by server
remove_file*
removes remote file
15 mb+24: session handle
mb+36: <remote file>
mb+24: session handle
mb+36: ftp status string as returned by server
rename*
renames remote file or directory
16 mb+24: session handle
mb+36: <from remote file | dir> <to remote file | dir>
mb+24: session handle
mb+36: ftp status string as returned by server
site*
send a site command
17 mb+24: session handle
mb+36: <parameter string>
mb+24: session handle
mb+36: ftp status string as returned by server
new_directory*
Create a new directory
18 mb+24: session handle
mb+36: <remote path>
mb+24: session handle
mb+36: ftp status string as returned by server
remove_directory*
Remove a directory (including contents)
19 mb+24: session handle
mb+36: <remote directory>
mb+24: session handle
mb+36: ftp status string as returned by server
download_file_leaf*
Downloads a file to 'local directory' converting its name to a RISC OS filename
20 mb+24: session handle
mb+36: <remote file> <local directory>
mb+24: session handle
mb+36: ftp status string as returned by server
upload_file_leaf*
Uploads a file from 'local directory' converting its name to a remote filename
21 mb+24: session handle
mb+36: <local file> <local directory>
mb+24: session handle
mb+36: ftp status string as returned by server
download_dir_leaf*
Download directory to 'local directory' converting its name to a RISC OS filename
22 mb+24: session handle
mb+36: <remote dir> <local directory>
mb+24: session handle
mb+36: ftp status string as returned by server
upload_dir_leaf*
Upload directory to server converting its leaf name to a remote file name
23 mb+24: session handle
mb+36: <local directory>
mb+24: session handle
mb+36: ftp status string as returned by server
upload_newer_time*
Files are only uploaded if they are newer than this time
24 mb+24: session handle
mb+36: 5 byte UTC time
mb+24: session handle
mb+36: ftp status string
upload_newer_than_file*
Files are only uploaded if they are newer than the files stamp. If the file doesn't exist all files are uploaded.
25 mb+24: session handle
mb+36: <file name>
mb+24: session handle
mb+36: ftp status string
remove_dir_contents*
Remove all the contents of the current remote directory
USE WITH CARE
26 mb+24: session handle mb+24: session handle
mb+36: ftp status string
download_dir_contents*
Download the contents of the local directory to the current remote directory
27 mb+36: <local directory> mb+24: session handle
mb+36: ftp status string
upload_dir_contents*
Upload the contents of the local directory to the current remote directory
28 mb+36: <local directory> mb+24: session handle
mb+36: ftp status string
remove_empty_directory*
Remove an empty directory
29 mb+24: session handle
mb+36: <remote directory>
mb+24: session handle
mb+36: ftp status string as returned by server
resume_transfer*
Resumes a transfer - only works if supported by the server
30 mb+24: session handle
mb+36: <remote file> <local file>
mb+24: session handle
mb+36: ftp status string as returned by server
show_status
Show the status window
If it is open when a program ends it will stay open.
256 mb+24: session handle not replied to
hide status
Hide the status window
257 mb+24: session handle not replied to
set_client_status
Enter text into the status dialogue box
258 mb+24: session handle
mb+36: <text>
not replied to
save_status_log*
Save te statis log to a file
259 mb+24: session handle
mb+36: <file_name>
mb+24: session handle
mb+36: ftp status string. 200 success 550 fail

Notes

Listing Directories

There are two directory formats available from FTPc, raw (list_dir_raw) and filtered (list_dir). 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.

Filtered format

200 D 1234 filename

field position Comments
Ftp status code 0
Filer object type 4 D - directory
F - file
L - Link
File size
6 This may not be accurate. eg Vax directory displays give the number of blocks allocated
Filename 18 filename ending in 0x00 0xd

Raw format

200 drwxrwxrwx 1 root root 2048 Oct 23 10:04 incoming
Typical unix type server output

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.

field position comments
Ftp status code 0
Directory line as supplied by the server 4 line ending in 0x00 0xd

List Options

You can modify the listing output with list_options. These are likely to be server dependant and so is best avoided if portability is required.

Status Window

Each session can have a status window. It is opened with show_status and hidden with hide_status. You can add your own status message with set_client_status. None of these commands expect replies and can be called at any time.

Even if you don't open a status window in your program the user can open it from the sessions menu. You can also close a connection or quit the client from the status window menu (Wimp_MQuit sent to client).

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.

Sessions Menu

The sessions 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

client_task_name - session_name

FTPcBasLib

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.

A typical program may be

   LIBRARY "<FTPc$dir>.FTPcBasLib"

REM PROCftpc_init starts the task and loads FTPc if it isn't
    already loaded

   PROCftpc_init("Upload Website")

REM if you were using the library from another application you should use

	PROCftpc_application_init(poll_block%,"FNmypoll")

REM where poll_block% is the poll block used by your polling
 routine and "FNmypoll" is the name of a function of the form DEF
 FNpoll which returns the Wimp_Polls reason code and fills in the
 poll block passed to PROCftpc_application_init.
   
REM open session if FTPc is a version > 120 and give it a name.
 The session handle is returned in the first parameter - S%

   PROCerr(FNftpc_open_session(S%,120,"My Program"))

REM connect to your web site
   PROCerr(FNftpc_connect(S%,"ftp://user:password@uploads.webspace.freeserve.net/path")

REM upload the contents of $.from_directory into path
   PROCerr(FNftpc_upload_dir_contents(S%,"$.from_directory")
   END

   DEF PROCerr(status%)
   CASE error% OF
     WHEN  2: ENDPROC : REM success
     WHEN -1: ERROR 0,"'Connection closed'"
     WHEN -2: ERROR 0,"'FTP not Loaded'"
     WHEN -3: ERROR 0,"'Task Quit'"
     OTHERWISE: ERROR 1,"Failed: "+$(ftpc_pb+ftpc_pb_data%)
   ENDCASE

All commands which require replies are FN's the others PROC's. The string supplied to these functions are as described for command codes above.

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%.