File: api.html

package info (click to toggle)
cl-ftp 1.3.3-2
  • links: PTS
  • area: main
  • in suites: jessie, jessie-kfreebsd, lenny, squeeze, wheezy
  • size: 92 kB
  • ctags: 65
  • sloc: lisp: 520; makefile: 48; sh: 32
file content (8 lines) | stat: -rw-r--r-- 9,034 bytes parent folder | download | duplicates (4)
1
2
3
4
5
6
7
8
<?xml version="1.0" encoding="iso-8859-1" standalone="yes"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>CL-FTP API</title></head><body><h1>Overview</h1><p>CL-FTP is a library which provides FTP client functionality to a Common Lisp program.  CL-FTP uses the ACL-COMPAT package for network sockets and the SPLIT-SEQUENCE package for some parsing needs.</p><h1>License</h1><p>This software, and documentation, is (c) 2002 Matthew Danish.  Redistribution and modification is permitted under a MIT-style license.  See the LICENSE file for more details.</p><h1>Programmers Interface</h1><ul><li><p><i>Class </i><b>ftp-connection</b><i> derived from </i>() -- <br /><i>Initargs:</i><br /><ul><li><tt>:HOSTNAME</tt> -- The remote hostname -- <i>Default: </i>Not specified</li><li><tt>:PORT</tt> -- The remote port -- <i>Default: </i>21</li><li><tt>:USERNAME</tt> -- The login username -- <i>Default: </i>"anonymous"</li><li><tt>:PASSWORD</tt> -- The login password -- <i>Default: </i>"cl-ftp@cclan.net"</li><li><tt>:PASSIVE-FTP-P</tt> -- Use passive FTP if non-nil -- <i>Default: </i>NIL</li><li><tt>:SESSION-STREAM</tt> -- Send FTP session output to this stream, if non-nil -- <i>Default: </i>NIL</li><li><tt>:CODE-CUT-OFF-P</tt> -- When non-nil, cut-off FTP codes in logging output -- <i>Default: </i>T</li></ul>Represents an FTP connection and associated state.  The INITIALIZE-INSTANCE :AFTER method takes care of connection and login, if possible.</p></li><li><p><i>Function </i><b>ftp-hostname</b> <tt>(connection-variable)</tt><br />The remote hostname</p><p><i>Function </i><b>ftp-port</b> <tt>(connection-variable)</tt><br />The remote port</p><p><i>Function </i><b>ftp-username</b> <tt>(connection-variable)</tt><br />The login username</p><p><i>Function </i><b>ftp-password</b> <tt>(connection-variable)</tt><br />The login password</p><p><i>Function </i><b>ftp-session-stream</b> <tt>(connection-variable)</tt><br />The session stream for the FTP connection</p><p><i>Function </i><b>passive-ftp-p</b> <tt>(connection-variable)</tt><br />Non-nil iff given FTP connection is to use passive FTP for data transfers</p><p><i>Function </i><b>(setf passive-ftp-p)</b> <tt>(value connection-variable)</tt><br />Value should be non-nil to use passive FTP for data transfers with the given FTP connection</p><p><i>Function </i><b>code-cut-off-p</b> <tt>(connection-variable)</tt><br />Non-nil iff FTP codes are to be cut-off when logging</p><p><i>Function </i><b>(setf code-cut-off-p)</b> <tt>(value connection-variable)</tt><br />Alter value of code-cut-off-p</p></li><li><p><i>Condition </i><b>ftp-error</b><i> derived from </i>() -- <br /><i>Slots:</i><br /><ul><li><tt>ftp-error-code</tt> -- Code associated with message -- <i> Default: </i>Not specified</li><li><tt>error-message</tt> -- FTP server's error message -- <i> Default: </i>Not specified</li></ul></p></li><li><p><i>Condition </i><b>invalid-code</b><i> derived from </i>(ftp-error) -- <br /><i>Slots:</i><br /><ul><li><tt>expected</tt> -- Expected code -- <i> Default: </i>Not specified</li><li><tt>received</tt> -- Received code -- <i> Default: </i>Not specified</li></ul></p></li><li><p><i>Condition </i><b>transient-negative-completion</b><i> derived from </i>(ftp-error) -- <br /><i>Slots:</i><br /><ul></ul>Signalled when a transient error is received from the FTP server.  This means that the input was fine, but something else went wrong.  Feel free to resend.</p></li><li><p><i>Condition </i><b>permanent-negative-completion</b><i> derived from </i>(ftp-error) -- <br /><i>Slots:</i><br /><ul></ul>Signalled when a permanent error is received from the FTP server.  This means that the input was not acceptable and should not be re-sent.</p></li><li><p><i>Function </i><b>connect-to-server</b> <tt>(connection-variable)</tt><br />Attempts to connect to the server using the information provided by connection-variable.  If connection-variable represents an existing connection, then that connection will be closed and a new one established.</p></li><li><p><i>Function </i><b>close-connection</b> <tt>(connection-variable)</tt><br />Closes the given FTP connection</p></li><li><p><i>Macro </i><b>with-ftp-connection</b> <tt>
((connection-variable &key hostname port username password passive-ftp-p
  session-stream (if-failed error))
 &body body)</tt><br />Opens and ensures proper close of an FTP connection.  Binds connection-variable to the FTP-CONNECTION object in the scope of body.  Arguments are similar to that of the initargs for the class FTP-CONNECTION.</p></li><li><p><i>Macro </i><b>with-transfer-socket</b> <tt>
((transfer-socket connection-variable command-string &key rest (type binary)) &body
 body)</tt><br />Opens a data transfer socket in the scope of body, using the given FTP connection and executing the given FTP command-string.  If :REST is specified, then the FTP "REST" command will be sent with the value of the argument.  :TYPE may be :BINARY or :ASCII.  Closes the transfer-socket upon dynamic exit of body.</p></li><li><p><i>Function </i><b>call-with-transfer-socket</b> <tt>(connection-variable command-string function &key rest (type binary))</tt><br />Similar to WITH-TRANSFER-SOCKET, except that function is a function which accepts a single argument; namely the transfer-socket</p></li><li><p><i>Function </i><b>retrieve-file</b> <tt>(connection-variable remote local &key (type binary) rest)</tt><br />Retrieves a file given a remote filename, and a local filename or stream.  :TYPE is either :ASCII or :BINARY, and :REST specifies an integer amount to seek into the file before retrieving it.</p></li><li><p><i>Function </i><b>store-file</b> <tt>(connection-variable local remote &key (type binary))</tt><br />Stores a file given a local filename or stream and a remote filename.  :TYPE is either :ASCII or :BINARY.</p></li><li><p><i>Function </i><b>receive-response</b> <tt>(connection-variable &key (block nil))</tt><br />Receives a response from the FTP server.  Returns a list of strings as the first value and the response code as the second.  If :BLOCK is T, then will block until response received.  Otherwise return NIL if nothing is available currently.</p></li><li><p><i>Function </i><b>data-to-string</b> <tt>(data-list)</tt><br />Converts a list of strings, such as that produced by receive-response, to one string with newlines after each formerly-list-element.</p></li><li><p><i>Function </i><b>data-ready-p</b> <tt>(connection-variable)</tt><br />Non-nil iff data is waiting to be read from the control connection.</p></li><li><p><i>Function </i><b>send-list-command</b> <tt>(connection-variable output &optional (pathname .))</tt><br />Sends the FTP LIST command.  If OUTPUT is NIL, returns a string.  If OUTPUT is T, prints to *standard-output*.  Otherwise, it treats OUTPUT as the output stream.</p></li><li><p><i>Function </i><b>send-nlst-command</b> <tt>(connection-variable output &optional (pathname .))</tt><br />Sends the FTP NLST command.  If OUTPUT is NIL, returns a string.  If OUTPUT is T, prints to *standard-output*.  Otherwise, it treats OUTPUT as the output stream.</p></li><li><p><i>Function </i><b>retrieve-filename-list</b> <tt>(connection-variable &optional (pathname .))</tt><br />Retrieves a list of filenames for the given pathname.</p></li><li><p><i>Function </i><b>retrieve-file-info-list</b> <tt>(connection-variable &optional (pathname .))</tt><br />Retrieves a list of the form (type name) where type is :DIRECTORY or :FILE and name is a filename in the given directory named by pathname.  Note: this is implemented by attempting CWDs, and may break if the FTP server does strange things.</p></li><li><p><i>Function </i><b>send-size-command</b> <tt>(connection-variable remote-filename)</tt><br />Sends the FTP SIZE command on the given remote-filename.  Returns an integer size.  Signals error if no such file.</p></li><li><p><i>Function </i><b>send-cwd-command</b> <tt>(connection-variable remote-directory)</tt><br />Sends the FTP CWD command, to change to the given remote-directory.  If remote-directory is "..", CDUP is sent instead.  Signals error if not possible.</p></li><li><p><i>Function </i><b>send-cdup-command</b> <tt>(connection-variable)</tt><br />Sends the FTP CDUP command.</p></li><li><p><i>Function </i><b>send-pwd-command</b> <tt>(connection-variable)</tt><br />Sends the FTP PWD command and returns the current working directory as a string.</p></li><li><p><i>Function </i><b>send-mkd-command</b> <tt>(connection-variable remote-directory)</tt><br />Sends the FTP MKD command to make a remote directory.  Returns directory name as string.  Signals error if not possible.</p></li></ul><h1>Examples</h1><p><tt>(with-ftp-connection (conn :hostname "foo") (retrieve-file conn "bar" "baz"))</tt></p><p>Further examples should be included with your copy of this software.  See simple-client.lisp for a simple FTP client written with CL-FTP.</p></body></html>