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.
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.
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.
| 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_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.
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
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
FTPC_Reply/FTPc_ConnectionClosed before sending another command with a * in the same session.
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.
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 |
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 |
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.
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.
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
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%.