home *** CD-ROM | disk | FTP | other *** search
/ Acorn User 10 / AU_CD10.iso / Updates / FTPc / ProgramMan next >
Text File  |  2000-03-12  |  18KB  |  440 lines
  1. <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
  2. <HTML>
  3. <!-- Generated by TechWriter Professional 5.06 (02-Jul-99) -->
  4. <HEAD><TITLE>!FTPc Programming Manual</TITLE></HEAD>
  5. <BODY TEXT="#000000" BGCOLOR="#F0F0E0">
  6. <H1 ALIGN=CENTER>Programming Manual</H1>
  7. <P>
  8. 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.
  9. <H4>Concept</H4>
  10. <P>
  11. 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.
  12. <H4>Sessions</H4>
  13. <P>
  14. 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.
  15. <H4>The FTPc wimp message block (mb)</H4>
  16. <P><TABLE BORDER=2>
  17. <TR><TD WIDTH=59>mb+0
  18. <TD WIDTH=263>block size - set to 256
  19. <TR><TD>mb+4
  20. <TD>sender
  21. <TR><TD>mb+8
  22. <TD>my_ref
  23. <TR><TD>mb+12
  24. <TD>your_ref
  25. <TR><TD>mb+16
  26. <TD>action_code
  27. <TR><TD>mb+20
  28. <TD>command_code
  29. <TR><TD>mb+24
  30. <TD>session handle 
  31. <TR><TD>mb+36
  32. <TD>depends on command
  33. <TR><TD>mb+32
  34. <TD>depends on command
  35. <TR><TD>mb+36
  36. <TD>up to 220 bytes of data
  37. </TABLE>
  38. <P>
  39. 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.
  40. <H4>FTPc Wimp Messages (Action_codes)</H4>
  41. <P><TABLE BORDER=2>
  42. <TR><TD WIDTH=160><B>FTPC_Command</B>
  43. <TD WIDTH=57>&52440
  44. <TD WIDTH=213>Send command to FTPc
  45. <TR><TD><B>FTPC_Reply</B>
  46. <TD>&52441
  47. <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.
  48. <TR><TD><B>FTPC_ConnectionClosed</B>
  49. <TD>&52442
  50. <TD>Reply by FTPc if the connection is closed unexpectedly.<BR>
  51. The your_ref field of the poll block is correctly set to the my_ref of the FTPC_Command.<BR>
  52. This may be a reply to any command but means the session is still open. There is no valid data a mb+36
  53. </TABLE>
  54. <P>
  55. 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.
  56.  
  57. <P>
  58. The <B>open_session</B> command code should be broadcast and the sender in the poll block reply used for the other command codes.
  59.  
  60. <P>
  61. 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.
  62.  
  63. <P>
  64. 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.
  65. <H4><A NAME="Command_codes">Command codes</A></H4>
  66. <P>
  67. 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.
  68. <P>
  69. 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.
  70.  
  71. <P>
  72. A command code of -1 is always invalid
  73.  
  74. <H5>FTP Status String</H5>
  75. <P>
  76. 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
  77. <P><TABLE BORDER=2>
  78. <TR><TD WIDTH=162><B>Command<BR>
  79. at mb+20</B>
  80. <TD ALIGN=CENTER WIDTH=31>
  81. <TD WIDTH=128><B>FTPC_Command<BR>
  82. </B>
  83. <TD WIDTH=136><B>FTPC_Reply</B>
  84. <TR><TD><B>open_session*</B><BR>
  85. Used to find the task handle of FTPc and whether not it is running.<BR>
  86. The command fails if FTPc is older than the version entered at mb+28<BR>
  87. The minimum FTPc version should be 120
  88. <TD ALIGN=CENTER>0
  89. <TD><B>mb+28:</B> minimum  FTPc version *100<BR>
  90. <B>mb+36:</B> <session name>
  91. <TD><B>mb+4:</B> contains the task handle of FTPc <BR>
  92. <B>mb+24:</B> session handle<BR>
  93. <B>mb+28: </B>is the FTPc version number * 100<BR>
  94. <B>mb+36:</B> ftp status string
  95. <TR><TD><B>close_session*</B><BR>
  96. Closes session and the connection if it is open
  97. <TD ALIGN=CENTER>1
  98. <TD><B>mb+24:</B> session handle
  99. <TD><B>mb+24:</B> session handle<BR>
  100. <B>mb+36:</B> ftp status string as returned by server<BR>
  101. Quitting your program also closes the session
  102. <TR><TD><B>connect*</B><BR>
  103. Opens an ftp connection in the session if a connection is already open it is closed first
  104. <TD ALIGN=CENTER>2
  105. <TD><B>mb+24:</B> session handle<BR>
  106. <B>mb+36:</B> <ftp url><BR>
  107. eg ftp://ftp.demon.co.uk
  108. <TD><B>mb+24:</B> session handle<BR>
  109. <B>mb+36:</B> ftp status string as returned by server
  110. <TR><TD><B>disconnect*</B><BR>
  111. Disconnects an open ftp connection
  112. <TD ALIGN=CENTER>3
  113. <TD><B>mb+24:</B> session handle
  114. <TD><B>mb+24:</B> session handle<BR>
  115. <B>mb+36:</B> ftp status string 
  116. <TR><TD><B>abort</B><BR>
  117. aborts the command in progress and closes the connection but leaves the session open.<BR>
  118. Makes the command in progress receive a FTPC_ConnectionClosed reply.
  119. <TD ALIGN=CENTER>4
  120. <TD><B>mb+24:</B> session handle
  121. <TD>not replied to
  122. <TR><TD><B>get_status</B><BR>
  123. Get information about the status of the command in progress.
  124. <TD ALIGN=CENTER>5
  125. <TD><B>mb+24:</B> session handle
  126. <TD><B>mb+24:</B> session handle<BR>
  127. <B>mb+28:</B> flags<BR>
  128. <B>bit 0:</B> connected(1),<BR>
  129. <B>bit 1:</B>busy(1),idle(0)<BR>
  130. <B>mb+32:</B> bytes transfered (if a busy doing a transfer command).<BR>
  131. <B>mb+36:</B> ftp status string. Text after the status number is the text shown in the status window.
  132. <TR><TD><B>list_dir*</B><BR>
  133. Load a Directory in a format filtered by FTPc
  134. <TD ALIGN=CENTER>6
  135. <TD><B>mb+24:</B> session handle<BR>
  136.  
  137. <TD><B>mb+24:</B> session handle<BR>
  138. <B>mb+36:</B> ftp status string as returned by server
  139. <TR><TD><B>list_dir_raw*</B><BR>
  140. Load a Directory in the format supplied by the server
  141. <TD ALIGN=CENTER>7
  142. <TD><B>mb+24:</B> session handle<BR>
  143.  
  144. <TD><B>mb+24:</B> session handle<BR>
  145. <B>mb+36:</B> ftp status string as returned by server
  146. <TR><TD><B>set_dir_to_first_line</B><BR>
  147. makes <B>get_next_dir_line</B> <BR>
  148. read the first line in the loaded directory - only needed if you want to read a directory a second time
  149. <TD ALIGN=CENTER>8
  150. <TD><B>mb+24:</B> session handle
  151. <TD><B>mb+24:</B> session handle<BR>
  152. <B>mb+36:</B> ftp status string as returned by server
  153. <TR><TD><B>get_next_dir_line</B> <BR>
  154. read the next line in the loaded directory
  155. <TD ALIGN=CENTER>9
  156. <TD><B>mb+24:</B> session handle
  157. <TD><B>mb+24:</B> session handle<BR>
  158. <B>mb+36:</B> ftp status string. If successful line is after the first 4 chars of the status message
  159. <TR><TD><B>set_list_options*</B><BR>
  160. Sets option flags to add to the list command
  161. <TD ALIGN=CENTER>10
  162. <TD><B>mb+24:</B> session handle<BR>
  163. <B>mb+36:</B> <option flags>
  164. <TD><B>mb+24:</B> session handle<BR>
  165. <B>mb+36:</B> ftp status string
  166. <TR><TD><B>change_directory*</B><BR>
  167. Change the remote directory
  168. <TD ALIGN=CENTER>11
  169. <TD><B>mb+24:</B> session handle<BR>
  170. <B>mb+36:</B> <remote path>
  171. <TD><B>mb+24:</B> session handle<BR>
  172. <B>mb+36:</B> ftp status string as returned by server
  173. <TR><TD><B>change_directory_up*</B><BR>
  174. changes remote directory to its parent directory
  175. <TD ALIGN=CENTER>12
  176. <TD><B>mb+24:</B> session handle
  177. <TD><B>mb+24:</B> session handle<BR>
  178. <B>mb+36:</B> ftp status string as returned by server
  179. <TR><TD><B>download_file*</B><BR>
  180. download remote file to local file
  181. <TD ALIGN=CENTER>13
  182. <TD><B>mb+24:</B> session handle<BR>
  183. <B>mb+36:</B> <remote> <local>
  184. <TD><B>mb+24:</B> session handle<BR>
  185. <B>mb+36:</B> ftp status string as returned by server
  186. <TR><TD><B>upload_file*</B><BR>
  187. upload local file to remote file
  188. <TD ALIGN=CENTER>14
  189. <TD><B>mb+24:</B> session handle<BR>
  190. <B>mb+36:</B> <local> <remote>
  191. <TD><B>mb+24:</B> session handle<BR>
  192. <B>mb+36:</B> ftp status string as returned by server
  193. <TR><TD><B>remove_file*</B><BR>
  194. removes remote file
  195. <TD ALIGN=CENTER>15
  196. <TD><B>mb+24:</B> session handle<BR>
  197. <B>mb+36:</B> <remote file>
  198. <TD><B>mb+24:</B> session handle<BR>
  199. <B>mb+36:</B> ftp status string as returned by server
  200. <TR><TD><B>rename*</B><BR>
  201. renames remote file or directory
  202. <TD ALIGN=CENTER>16
  203. <TD><B>mb+24:</B> session handle<BR>
  204. <B>mb+36:</B> <from remote file | dir> <to remote file | dir>
  205. <TD><B>mb+24:</B> session handle<BR>
  206. <B>mb+36:</B> ftp status string as returned by server
  207. <TR><TD><B>site*</B><BR>
  208. send a site command
  209. <TD ALIGN=CENTER>17
  210. <TD><B>mb+24:</B> session handle<BR>
  211. <B>mb+36:</B> <parameter string>
  212. <TD><B>mb+24:</B> session handle<BR>
  213. <B>mb+36:</B> ftp status string as returned by server
  214. <TR><TD><B>new_directory*</B><BR>
  215. Create a new directory
  216. <TD ALIGN=CENTER>18
  217. <TD><B>mb+24:</B> session handle<BR>
  218. <B>mb+36:</B> <remote path>
  219. <TD><B>mb+24:</B> session handle<BR>
  220. <B>mb+36:</B> ftp status string as returned by server
  221. <TR><TD><B>remove_directory*</B><BR>
  222. Remove a directory (including contents)
  223. <TD ALIGN=CENTER>19
  224. <TD><B>mb+24:</B> session handle<BR>
  225. <B>mb+36:</B> <remote directory>
  226. <TD><B>mb+24:</B> session handle<BR>
  227. <B>mb+36:</B> ftp status string as returned by server
  228. <TR><TD><B>download_file_leaf*</B><BR>
  229. Downloads a file to 'local directory'   converting its name to a RISC OS filename
  230. <TD ALIGN=CENTER>20
  231. <TD><B>mb+24:</B> session handle<BR>
  232. <B>mb+36:</B> <remote file> <local directory>
  233. <TD><B>mb+24:</B> session handle<BR>
  234. <B>mb+36:</B> ftp status string as returned by server
  235. <TR><TD><B>upload_file_leaf*</B><BR>
  236. Uploads a file from 'local directory' converting its name to a  remote filename 
  237. <TD ALIGN=CENTER>21
  238. <TD><B>mb+24:</B> session handle<BR>
  239. <B>mb+36:</B> <local file> <local directory>
  240. <TD><B>mb+24:</B> session handle<BR>
  241. <B>mb+36:</B> ftp status string as returned by server
  242. <TR><TD><B>download_dir_leaf*</B><BR>
  243. Download directory to 'local directory'   converting its name to a RISC OS filename
  244. <TD ALIGN=CENTER>22
  245. <TD><B>mb+24:</B> session handle<BR>
  246. <B>mb+36:</B> <remote dir> <local directory>
  247. <TD><B>mb+24:</B> session handle<BR>
  248. <B>mb+36:</B> ftp status string as returned by server
  249. <TR><TD><B>upload_dir_leaf*</B><BR>
  250. Upload directory to server converting its leaf name to a remote file name
  251. <TD ALIGN=CENTER>23
  252. <TD><B>mb+24:</B> session handle<BR>
  253. <B>mb+36: </B><local directory>
  254. <TD><B>mb+24:</B> session handle<BR>
  255. <B>mb+36:</B> ftp status string as returned by server
  256. <TR><TD><B>upload_newer_time*</B><BR>
  257. Files are only uploaded if they are newer than this time
  258. <TD ALIGN=CENTER>24
  259. <TD><B>mb+24:</B> session handle<BR>
  260. <B>mb+36:</B> 5 byte UTC time
  261. <TD><B>mb+24:</B> session handle<BR>
  262. <B>mb+36:</B> ftp status string
  263. <TR><TD><B>upload_newer_than_file*</B><BR>
  264. Files are only uploaded if they are newer than the files stamp. If the file doesn't exist all files are uploaded.<B><BR>
  265. </B>
  266. <TD ALIGN=CENTER>25
  267. <TD><B>mb+24:</B> session handle<BR>
  268. <B>mb+36:</B> <file name>
  269. <TD><B>mb+24:</B> session handle<BR>
  270. <B>mb+36:</B> ftp status string
  271. <TR><TD><B>remove_dir_contents*</B><BR>
  272. Remove all the contents of the current remote directory<BR>
  273. USE WITH CARE
  274. <TD ALIGN=CENTER>26
  275. <TD><B>mb+24:</B> session handle
  276. <TD><B>mb+24:</B> session handle<BR>
  277. <B>mb+36:</B> ftp status string
  278. <TR><TD><B>download_dir_contents*</B><BR>
  279. Download the contents of the local directory to the current remote directory
  280. <TD ALIGN=CENTER>27
  281. <TD><B>mb+36: </B><local directory>
  282. <TD><B>mb+24:</B> session handle<BR>
  283. <B>mb+36:</B> ftp status string
  284. <TR><TD><B>upload_dir_contents*</B><BR>
  285. Upload the contents of the local directory to the current remote directory
  286. <TD ALIGN=CENTER>28
  287. <TD><B>mb+36: </B><local directory>
  288. <TD><B>mb+24:</B> session handle<BR>
  289. <B>mb+36:</B> ftp status string
  290. <TR><TD><B>remove_empty_directory*</B><BR>
  291. Remove an empty directory
  292. <TD ALIGN=CENTER>29
  293. <TD><B>mb+24:</B> session handle<BR>
  294. <B>mb+36:</B> <remote directory>
  295. <TD><B>mb+24:</B> session handle<BR>
  296. <B>mb+36:</B> ftp status string as returned by server
  297. <TR><TD><B>show_status</B><BR>
  298. Show the status window<BR>
  299. If it is open when a program ends it will stay open.
  300. <TD ALIGN=CENTER>256
  301. <TD><B>mb+24:</B> session handle
  302. <TD>not replied to
  303. <TR><TD><B>hide status</B><BR>
  304. Hide the status window
  305. <TD ALIGN=CENTER>257
  306. <TD><B>mb+24:</B> session handle
  307. <TD>not replied to
  308. <TR><TD><B>set_client_status</B><BR>
  309. Enter text into the status dialogue box
  310. <TD ALIGN=CENTER>258
  311. <TD><B>mb+24:</B> session handle<BR>
  312. <B>mb+36:</B> <text>
  313. <TD>not replied to
  314. </TABLE>
  315. <P>
  316. <B>Notes</B>
  317. <UL>
  318. <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.
  319. <LI>Command codes ending in 'leaf' converts the file/directroy name on transfer
  320. </UL>
  321. <H4>Listing Directories</H4>
  322. <P>
  323. 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.
  324.  
  325. <H5>Filtered format</H5>
  326.  
  327. <P>
  328. <TT>200 D 1234        filename</TT>
  329.  
  330. <P><TABLE BORDER=2>
  331. <TR><TD WIDTH=132><B>field</B>
  332. <TD WIDTH=88><B>position</B>
  333. <TD WIDTH=137><B>Comments</B>
  334. <TR><TD><B>Ftp status code</B>
  335. <TD>0
  336. <TD>
  337. <TR><TD><B>Filer object type</B>
  338. <TD>4
  339. <TD>D - directory<BR>
  340. F - file<BR>
  341. L - Link
  342. <TR><TD><B>File size</B><BR>
  343.  
  344. <TD>6
  345. <TD>This may not be accurate. eg Vax directory displays give the number of blocks allocated
  346. <TR><TD><B>Filename</B>
  347. <TD>18
  348. <TD>filename ending in 0x00 0xd
  349. </TABLE>
  350. <H5>Raw format</H5>
  351. <P>
  352. <CODE>200 drwxrwxrwx   1 root     root         2048 Oct 23 10:04 incoming</CODE><BR>
  353. <B>Typical unix type server output</B>
  354. <P>
  355. 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.
  356. <P><TABLE BORDER=2>
  357. <TR><TD WIDTH=132><B>field</B>
  358. <TD WIDTH=88><B>position</B>
  359. <TD WIDTH=137><B>comments</B>
  360. <TR><TD><B>Ftp status code</B>
  361. <TD>0
  362. <TD>
  363. <TR><TD><B>Directory line </B>as supplied by the server
  364. <TD>4
  365. <TD>line ending in 0x00 0xd
  366. </TABLE>
  367. <H5>List Options</H5>
  368. <P>
  369. 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.
  370. <H4>Status Window</H4>
  371. <P>
  372. 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.
  373. <P>
  374.  
  375. <P>
  376. 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).
  377.  
  378. <P>
  379. 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.
  380. <H4><A NAME="Sessions_Menu">Sessions Menu</A></H4>
  381. <P>
  382. 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
  383.  
  384. <P>
  385. client_task_name - session_name
  386.  
  387. <H4><A NAME="FTPcBasLib">FTPcBasLib</A></H4>
  388. <P>
  389. 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.
  390.  
  391. <P>
  392. A typical program may be
  393.  
  394. <PRE>  <B> LIBRARY "<FTPc$dir>.FTPcBasLib"</B>
  395.  
  396. REM PROCftpc_init starts the task and loads FTPc if it isn't
  397.     already loaded
  398.  
  399.    <B>PROCftpc_init("Upload Website")</B>
  400.  
  401. REM if you were using the library from another application you should use
  402.  
  403. <B>    PROCftpc_application_init(poll_block%,"FNmypoll")</B>
  404.  
  405. REM where poll_block% is the poll block used by your polling
  406.  routine and "FNmypoll" is the name of a function of the form DEF
  407.  FNpoll which returns the Wimp_Polls reason code and fills in the
  408.  poll block passed to PROCftpc_application_init.
  409.    
  410. REM open session if FTPc is a version > 120 and give it a name.
  411.  The session handle is returned in the first parameter - S%
  412.  
  413.    <B>PROCerr(FNftpc_open_session(S%,120,"My Program"))</B>
  414.  
  415. REM connect to your web site
  416.    <B>PROCerr(FNftpc_connect(S%,"ftp://user:password@uploads.webspace.freeserve.net/path")</B>
  417.  
  418. REM upload the contents of $.from_directory into path
  419.    <B>PROCerr(FNftpc_upload_dir_contents(S%,"$.from_directory")</B>
  420.    <B>END</B>
  421.  
  422.    <B>DEF PROCerr(status%)</B>
  423. <B>   CASE error% OF</B>
  424. <B>     WHEN  2: ENDPROC : REM success</B>
  425. <B>     WHEN -1: ERROR 0,"'Connection closed'"</B>
  426. <B>     WHEN -2: ERROR 0,"'FTP not Loaded'"</B>
  427. <B>     WHEN -3: ERROR 0,"'Task Quit'"</B>
  428. <B>     OTHERWISE: ERROR 1,"Failed: "+$(ftpc_pb+ftpc_pb_data%)</B>
  429. <B>   ENDCASE</B>
  430. <B></B>
  431. </PRE>
  432. <P>
  433. 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.
  434.  
  435. <P>
  436. 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%.
  437.  
  438. </BODY>
  439. </HTML>
  440.