Qore Programming Language
1.7.0
|
provides thread-safe access to FTP servers through Qore data structures More...
#include <QoreFtpClient.h>
Inherited by QoreFtpClientClass.
Public Member Methods | |
DLLEXPORT | QoreFtpClient () |
creates the object with no connection parameters | |
DLLEXPORT | QoreFtpClient (const QoreString *url, ExceptionSink *xsink) |
creates the object and sets connection parameters based on the url passed More... | |
DLLEXPORT | ~QoreFtpClient () |
disconnects from the host if necessary and frees all memory associated with the object | |
DLLEXPORT int | connect (ExceptionSink *xsink) |
connects to the remote host and logs in More... | |
DLLEXPORT int | cwd (const char *dir, ExceptionSink *xsink) |
changes the working directory on the remote host More... | |
DLLEXPORT int | del (const char *file, ExceptionSink *xsink) |
deletes the given file on the remote server More... | |
DLLEXPORT int | disconnect () |
disconnects from the remote host if connected More... | |
DLLEXPORT int | get (const char *remotepath, const char *localname, ExceptionSink *xsink) |
gets a file from the remote server and saves it on the local filesystem More... | |
DLLEXPORT int | get (const char *remotepath, OutputStream *os, ExceptionSink *xsink) |
gets a file from the remote server and writes it to an OutputStream More... | |
DLLEXPORT BinaryNode * | getAsBinary (const char *remotepath, ExceptionSink *xsink) |
gets a file from the remote server and returns it as a binary node More... | |
DLLEXPORT QoreStringNode * | getAsString (const char *remotepath, ExceptionSink *xsink) |
gets a file from the remote server and returns it as a string More... | |
DLLEXPORT QoreStringNode * | getAsString (ExceptionSink *xsink, const char *remotepath, const QoreEncoding *encoding=QCS_DEFAULT) |
gets a file from the remote server and returns it as a string More... | |
DLLEXPORT QoreHashNode * | getControlPeerInfo (ExceptionSink *xsink, bool host_lookup) const |
returns peer information for a connected control socket More... | |
DLLEXPORT QoreHashNode * | getControlSocketInfo (ExceptionSink *xsink, bool host_lookup) const |
returns information for the current control socket; the socket must be open More... | |
DLLEXPORT QoreHashNode * | getDataPeerInfo (ExceptionSink *xsink, bool host_lookup) const |
returns peer information for a connected data socket More... | |
DLLEXPORT QoreHashNode * | getDataSocketInfo (ExceptionSink *xsink, bool host_lookup) const |
returns information for the current control socket; the socket must be open More... | |
DLLEXPORT const char * | getHostName () const |
returns the hostname connection parameter | |
DLLEXPORT const char * | getMode () const |
returns a string for the connection mode: "port", "pasv", "epsv", or "auto" if not connected and auto mode is set | |
DLLEXPORT int | getNetworkFamily () const |
returns the network family to use with new connections More... | |
DLLEXPORT const char * | getPassword () const |
returns the password connection parameter | |
DLLEXPORT int | getPort () const |
returns the port number connection parameter | |
DLLEXPORT const char * | getSSLCipherName () const |
returns the name of the SSL Cipher for the currently-connected control connection, or 0 if there is none More... | |
DLLEXPORT const char * | getSSLCipherVersion () const |
returns the version string of the SSL Cipher for the currently-connected control connection, or 0 if there is none More... | |
DLLLOCAL int | getTimeout () const |
returns the socket I/O timeout value as an integer in milliseconds More... | |
DLLEXPORT QoreStringNode * | getURL () const |
returns a URL string representing the current connection parameters, caller owns the reference count returned More... | |
DLLEXPORT const char * | getUserName () const |
returns the user name connection parameter | |
DLLEXPORT bool | isDataSecure () const |
returns the secure data connection parameter flag More... | |
DLLEXPORT bool | isSecure () const |
returns the secure connection parameter flag More... | |
DLLEXPORT QoreStringNode * | list (const char *path, bool long_list, ExceptionSink *xsink) |
returns a string listing the directory contents on the remote host (caller owns the reference count returned) More... | |
DLLEXPORT int | mkdir (const char *remotepath, ExceptionSink *xsink) |
creates a directory on the remote server More... | |
DLLEXPORT int | put (const char *localpath, const char *remotename, ExceptionSink *xsink) |
sends a file from the local filesystem to the remote server More... | |
DLLEXPORT int | put (InputStream *is, const char *remotename, ExceptionSink *xsink) |
sends the content of an InputStream to the remote server More... | |
DLLEXPORT int | putData (const void *data, size_t len, const char *remotename, ExceptionSink *xsink) |
sends a file data io the remote server More... | |
DLLEXPORT QoreStringNode * | pwd (ExceptionSink *xsink) |
returns the working directory on the remote host (caller owns the reference count returned) More... | |
DLLEXPORT int | rename (const char *from, const char *to, ExceptionSink *xsink) |
renames/moves a file on the remote server More... | |
DLLEXPORT int | rmdir (const char *remotepath, ExceptionSink *xsink) |
removes a directory on the remote server More... | |
QoreHashNode * | sendControlMessage (const char *cmd, const char *arg, ExceptionSink *xsink) |
Sends a message on the control port and returns a FtpResponseInfo hash or nullptr (if an exception is thrown) More... | |
DLLLOCAL void | setControlEventQueue (ExceptionSink *xsink, Queue *q, QoreValue arg, bool with_data) |
sets the event queue for the control socket | |
DLLLOCAL void | setDataEventQueue (ExceptionSink *xsink, Queue *q, QoreValue arg, bool with_data) |
sets the event queue for the data socket | |
DLLLOCAL void | setEventQueue (ExceptionSink *xsink, Queue *q, QoreValue arg, bool with_data) |
sets the same event queue for data and control sockets | |
DLLEXPORT void | setHostName (const char *h) |
sets the host name connection parameter | |
DLLEXPORT int | setInsecure () |
unsets the secure connection parameter flag (to use the FTP protocol) More... | |
DLLEXPORT int | setInsecureData () |
sets the secure data connection parameter flag More... | |
DLLEXPORT void | setModeAuto () |
sets the connection mode for the next connection to "auto" | |
DLLEXPORT void | setModeEPSV () |
sets the connection mode for the next connection to "EPSV" (extended passive mode) | |
DLLEXPORT void | setModePASV () |
sets the connection mode for the next connection to "PASV" (passive mode) | |
DLLEXPORT void | setModePORT () |
sets the connection mode for the next connection to "PORT" | |
DLLEXPORT void | setNetworkFamily (int family) |
sets the network family to use with new connections More... | |
DLLEXPORT void | setPassword (const char *p) |
sets the password connection parameter | |
DLLEXPORT void | setPort (int p) |
sets the port connection parameter | |
DLLEXPORT int | setSecure () |
sets the secure connection parameter flag (to use the FTPS protocol) More... | |
DLLLOCAL void | setTimeout (int timeout_ms) |
sets the socket I/O timeout value in milliseconds More... | |
DLLEXPORT void | setURL (const QoreString *url, ExceptionSink *xsink) |
sets the connection parameters from a URL More... | |
DLLEXPORT void | setUserName (const char *u) |
sets the user name connection parameter | |
DLLEXPORT long | verifyPeerCertificate () const |
returns the peer certificate verification code | |
Private Member Methods | |
DLLLOCAL | QoreFtpClient (const QoreFtpClient &) |
this function is not implemented; it is here as a private function in order to prohibit it from being used | |
DLLLOCAL QoreFtpClient & | operator= (const QoreFtpClient &) |
this function is not implemented; it is here as a private function in order to prohibit it from being used | |
Private Attributes | |
struct qore_ftp_private * | priv |
private implementation of the object | |
provides thread-safe access to FTP servers through Qore data structures
is "auto" mode, tries the following data modes in order:
references:
tested with:
DLLEXPORT QoreFtpClient::QoreFtpClient | ( | const QoreString * | url, |
ExceptionSink * | xsink | ||
) |
creates the object and sets connection parameters based on the url passed
a Qore-language exception will be raised if the URL is invalid (protocol is not "ftp" or "ftps") or the hostname is missing.
url | the URL string to use to set connection parameters |
xsink | if an error occurs, the Qore-language exception information will be added here |
DLLEXPORT int QoreFtpClient::connect | ( | ExceptionSink * | xsink | ) |
connects to the remote host and logs in
if there are any connection or authentication errors, Qore-language exceptions are raised
xsink | if an error occurs, the Qore-language exception information will be added here |
DLLEXPORT int QoreFtpClient::cwd | ( | const char * | dir, |
ExceptionSink * | xsink | ||
) |
changes the working directory on the remote host
if there are any errors (if no connection has been previously established, it's an error), Qore-language exceptions are raised.
dir | the directory to change to |
xsink | if an error occurs, the Qore-language exception information will be added here |
DLLEXPORT int QoreFtpClient::del | ( | const char * | file, |
ExceptionSink * | xsink | ||
) |
deletes the given file on the remote server
the connection must be already established before this function is called or an error will be raised.
file | the filename to delete |
xsink | if an error occurs, the Qore-language exception information will be added here |
DLLEXPORT int QoreFtpClient::disconnect | ( | ) |
disconnects from the remote host if connected
DLLEXPORT int QoreFtpClient::get | ( | const char * | remotepath, |
const char * | localname, | ||
ExceptionSink * | xsink | ||
) |
gets a file from the remote server and saves it on the local filesystem
the connection must be already established before this function is called or an error will be raised.
remotepath | the path of the file on the remote server |
localname | the local name of the file |
xsink | if an error occurs, the Qore-language exception information will be added here |
DLLEXPORT int QoreFtpClient::get | ( | const char * | remotepath, |
OutputStream * | os, | ||
ExceptionSink * | xsink | ||
) |
gets a file from the remote server and writes it to an OutputStream
the connection must be already established before this function is called or an error will be raised.
remotepath | the path of the file on the remote server |
os | the output stream |
xsink | if an error occurs, the Qore-language exception information will be added here |
DLLEXPORT BinaryNode* QoreFtpClient::getAsBinary | ( | const char * | remotepath, |
ExceptionSink * | xsink | ||
) |
gets a file from the remote server and returns it as a binary node
the connection must be already established before this function is called or an error will be raised.
remotepath | the path of the file on the remote server |
xsink | if an error occurs, the Qore-language exception information will be added here |
DLLEXPORT QoreStringNode* QoreFtpClient::getAsString | ( | const char * | remotepath, |
ExceptionSink * | xsink | ||
) |
gets a file from the remote server and returns it as a string
the connection must be already established before this function is called or an error will be raised.
remotepath | the path of the file on the remote server |
xsink | if an error occurs, the Qore-language exception information will be added here |
DLLEXPORT QoreStringNode* QoreFtpClient::getAsString | ( | ExceptionSink * | xsink, |
const char * | remotepath, | ||
const QoreEncoding * | encoding = QCS_DEFAULT |
||
) |
gets a file from the remote server and returns it as a string
the connection must be already established before this function is called or an error will be raised.
xsink | if an error occurs, the Qore-language exception information will be added here |
remotepath | the path of the file on the remote server |
encoding | the encoding to use for the output string |
DLLEXPORT QoreHashNode* QoreFtpClient::getControlPeerInfo | ( | ExceptionSink * | xsink, |
bool | host_lookup | ||
) | const |
returns peer information for a connected control socket
if the socket is not connected, a Qore-language exception is thrown
xsink | if an error occurs, the Qore-language exception information will be added here |
host_lookup | do a host lookup (if this is false the "hostname" and "hostname_desc" are not present in the response hash) |
hostname:
the hostname of the remote end (if known or appropriate for the socket type, only performed if host_lookup is true)hostname_desc:
a descriptive string for the remote hostname (including the socket type - ie "ipv6[host]", only performed if host_lookup is true)address:
the address of the remote end - for UNIX sockets this is the file pathaddress_desc:
a descriptive string for the remote addressport:
the port number if knownfamily:
the address family (ie AF_INET, AF_INET6, AF_UNIX, ...)familystr:
a string description of the address family ("ipv4", "ipv6", etc)DLLEXPORT QoreHashNode* QoreFtpClient::getControlSocketInfo | ( | ExceptionSink * | xsink, |
bool | host_lookup | ||
) | const |
returns information for the current control socket; the socket must be open
if the socket is not open, a Qore-language exception is thrown
xsink | if an error occurs, the Qore-language exception information will be added here |
host_lookup | do a host lookup (if this is false the "hostname" and "hostname_desc" are not present in the response hash) |
hostname:
the hostname for the local interface (if known or appropriate for the socket type)hostname_desc:
a descriptive string for the local hostname (including the socket type - ie "ipv6[host]")address:
the address of the local interface - for UNIX sockets this is the file pathaddress_desc:
a descriptive string for the local interfaceport:
the port number if knownfamily:
the address family (ie AF_INET, AF_INET6, AF_UNIX, ...)familystr:
a string description of the address family ("ipv4", "ipv6", etc)DLLEXPORT QoreHashNode* QoreFtpClient::getDataPeerInfo | ( | ExceptionSink * | xsink, |
bool | host_lookup | ||
) | const |
returns peer information for a connected data socket
if the socket is not connected, a Qore-language exception is thrown
xsink | if an error occurs, the Qore-language exception information will be added here |
host_lookup | do a host lookup (if this is false the "hostname" and "hostname_desc" are not present in the response hash) |
hostname:
the hostname of the remote end (if known or appropriate for the socket type, only performed if host_lookup is true)hostname_desc:
a descriptive string for the remote hostname (including the socket type - ie "ipv6[host]", only performed if host_lookup is true)address:
the address of the remote end - for UNIX sockets this is the file pathaddress_desc:
a descriptive string for the remote addressport:
the port number if knownfamily:
the address family (ie AF_INET, AF_INET6, AF_UNIX, ...)familystr:
a string description of the address family ("ipv4", "ipv6", etc)DLLEXPORT QoreHashNode* QoreFtpClient::getDataSocketInfo | ( | ExceptionSink * | xsink, |
bool | host_lookup | ||
) | const |
returns information for the current control socket; the socket must be open
if the socket is not open, a Qore-language exception is thrown
xsink | if an error occurs, the Qore-language exception information will be added here |
host_lookup | do a host lookup (if this is false the "hostname" and "hostname_desc" are not present in the response hash) |
hostname:
the hostname for the local interface (if known or appropriate for the socket type)hostname_desc:
a descriptive string for the local hostname (including the socket type - ie "ipv6[host]")address:
the address of the local interface - for UNIX sockets this is the file pathaddress_desc:
a descriptive string for the local interfaceport:
the port number if knownfamily:
the address family (ie AF_INET, AF_INET6, AF_UNIX, ...)familystr:
a string description of the address family ("ipv4", "ipv6", etc)DLLEXPORT int QoreFtpClient::getNetworkFamily | ( | ) | const |
returns the network family to use with new connections
DLLEXPORT const char* QoreFtpClient::getSSLCipherName | ( | ) | const |
returns the name of the SSL Cipher for the currently-connected control connection, or 0 if there is none
DLLEXPORT const char* QoreFtpClient::getSSLCipherVersion | ( | ) | const |
returns the version string of the SSL Cipher for the currently-connected control connection, or 0 if there is none
DLLLOCAL int QoreFtpClient::getTimeout | ( | ) | const |
returns the socket I/O timeout value as an integer in milliseconds
DLLEXPORT QoreStringNode* QoreFtpClient::getURL | ( | ) | const |
returns a URL string representing the current connection parameters, caller owns the reference count returned
this function always returns a value
DLLEXPORT bool QoreFtpClient::isDataSecure | ( | ) | const |
returns the secure data connection parameter flag
true indicates that the current data connection (if any) is encrypted, or that the next data connection can only be established with a secure connection
DLLEXPORT bool QoreFtpClient::isSecure | ( | ) | const |
returns the secure connection parameter flag
true indicates that current control connection (if any) is encrypted, or that the next control connection can only be established with a secure connection
DLLEXPORT QoreStringNode* QoreFtpClient::list | ( | const char * | path, |
bool | long_list, | ||
ExceptionSink * | xsink | ||
) |
returns a string listing the directory contents on the remote host (caller owns the reference count returned)
the connection must be already established before this function is called or an error will be raised.
path | the path to list |
long_list | if true then a "long list" is made |
xsink | if an error occurs, the Qore-language exception information will be added here |
DLLEXPORT int QoreFtpClient::mkdir | ( | const char * | remotepath, |
ExceptionSink * | xsink | ||
) |
creates a directory on the remote server
the connection must be already established before this function is called or an error will be raised.
remotepath | the path of the directory on the remote server |
xsink | if an error occurs, the Qore-language exception information will be added here |
DLLEXPORT int QoreFtpClient::put | ( | const char * | localpath, |
const char * | remotename, | ||
ExceptionSink * | xsink | ||
) |
sends a file from the local filesystem to the remote server
the connection must be already established before this function is called or an error will be raised.
localpath | the local path of the file to send |
remotename | the name of the file on the remote server |
xsink | if an error occurs, the Qore-language exception information will be added here |
DLLEXPORT int QoreFtpClient::put | ( | InputStream * | is, |
const char * | remotename, | ||
ExceptionSink * | xsink | ||
) |
sends the content of an InputStream to the remote server
the connection must be already established before this function is called or an error will be raised.
is | the input stream |
remotename | the name of the file on the remote server |
xsink | if an error occurs, the Qore-language exception information will be added here |
DLLEXPORT int QoreFtpClient::putData | ( | const void * | data, |
size_t | len, | ||
const char * | remotename, | ||
ExceptionSink * | xsink | ||
) |
sends a file data io the remote server
the connection must be already established before this function is called or an error will be raised.
data | the data to send |
len | the length of the data to send (if 0, a Qore-language exception will be raised) |
remotename | the name of the file on the remote server |
xsink | if an error occurs, the Qore-language exception information will be added here |
DLLEXPORT QoreStringNode* QoreFtpClient::pwd | ( | ExceptionSink * | xsink | ) |
returns the working directory on the remote host (caller owns the reference count returned)
the connection must be already established before this function is called or an error will be raised.
xsink | if an error occurs, the Qore-language exception information will be added here |
DLLEXPORT int QoreFtpClient::rename | ( | const char * | from, |
const char * | to, | ||
ExceptionSink * | xsink | ||
) |
renames/moves a file on the remote server
the connection must be already established before this function is called or an error will be raised.
from | the original file path on the remote server |
to | the new file path on the remote server |
xsink | if an error occurs, the Qore-language exception information will be added here |
DLLEXPORT int QoreFtpClient::rmdir | ( | const char * | remotepath, |
ExceptionSink * | xsink | ||
) |
removes a directory on the remote server
the connection must be already established before this function is called or an error will be raised.
remotepath | the path of the directory on the remote server |
xsink | if an error occurs, the Qore-language exception information will be added here |
QoreHashNode* QoreFtpClient::sendControlMessage | ( | const char * | cmd, |
const char * | arg, | ||
ExceptionSink * | xsink | ||
) |
Sends a message on the control port and returns a FtpResponseInfo hash or nullptr (if an exception is thrown)
cmd | the command to send |
arg | the argument for the command |
xsink | if an error occurs, the Qore-language exception information will be added here |
DLLEXPORT int QoreFtpClient::setInsecure | ( | ) |
unsets the secure connection parameter flag (to use the FTP protocol)
DLLEXPORT int QoreFtpClient::setInsecureData | ( | ) |
sets the secure data connection parameter flag
after calling QoreFtpClient::setSecure(), this function can be set to indicate that data connection should not be encrypted (while logins will be encrypted)
DLLEXPORT void QoreFtpClient::setNetworkFamily | ( | int | family | ) |
sets the network family to use with new connections
family | the network family to use with new connections |
DLLEXPORT int QoreFtpClient::setSecure | ( | ) |
sets the secure connection parameter flag (to use the FTPS protocol)
DLLLOCAL void QoreFtpClient::setTimeout | ( | int | timeout_ms | ) |
sets the socket I/O timeout value in milliseconds
DLLEXPORT void QoreFtpClient::setURL | ( | const QoreString * | url, |
ExceptionSink * | xsink | ||
) |
sets the connection parameters from a URL
a Qore-language exception will be raised if the URL is invalid (protocol is not "ftp" or "ftps") or the hostname is missing.
url | the URL string to use to set connection parameters |
xsink | if an error occurs, the Qore-language exception information will be added here |