Qorus Integration Engine®  4.0.3.p2_git
OMQ::AbstractFtpHandler Class Reference

this class is used to customize and control the behavior of Qorus FTP servers attached to services More...

Public Member Methods

 constructor (*string v_root, bool v_bin=False, HttpServer::AbstractAuthenticator v_auth=new DefaultQorusRBACAuthenticator())
 creates the object with the given arguments More...
 
 addListener (int port)
 adds a listener from a port number; listener will start up on all interfaces on the given port More...
 
 addListener (string bind)
 adds a listener from a bind string in the format: "address:port" (ex: "192.168.20.1:8011") More...
 
 addListeners (list l)
 adds a list of listeners; each element should be either a bind string in the format: "address:port" (ex: "192.168.20.1:8011") or an integer port, meaning to bind on all interfaces on that port More...
 
*string authReceiveFile (string cwd, string orig, reference< string > path)
 this method is run when the server receives a "STOR" command from the client but before the server opens the data channel to receive the file; return no value if the server should accept the file, otherwise return a string that will be passed back to the client with a 500 error code rejecting the "STOR" request More...
 
 fileDataReceived (string path, data data)
 this method is called when the server has received a file and no root directory is set More...
 
 fileReceived (string path)
 this method is called when the server has received a file More...
 
*string authSendFile (string cwd, string orig, reference path)
 this method is run when the server receives a "RETR" command from the client but before the server opens the data channel to receive the file; return no value if the server should accept the file, otherwise return a string that will be passed back to the client with a 500 error code rejecting the request More...
 
data sendFile (string path)
 this method is called when the server should send a file More...
 
*string size (string v_cwd, string v_orig, string v_path, reference< int > v_size)
 this method is called when the "SIZE" command is received More...
 
*string modifiedTime (string v_cwd, string v_orig, string v_path, reference< date > v_date)
 this method is called when the "MDTM" command is received More...
 
 fileSent (string path)
 this method is called when the server has sent a file More...
 
*string authChangeDir (string v_cwd, string v_orig, reference< string > v_path)
 this method is run when the server receives a "CWD" command from the client but before the server updates the current working directory; return no value if the server should accept the change directory request, otherwise return a string that will be passed back to the client with a 550 error code rejecting the "CWD" request More...
 
*string authRename (string v_cwd, string v_orig, reference< string > v_path)
 this method is run when the server receives a "RNFR" command from the client; return no value if the server should accept the request, otherwise return a string that will be passed back to the client with a 550 error code rejecting the "RNFR" request More...
 
*string rename (string v_cwd, string v_orig_to, string v_from, string v_to)
 this method is run when the server receives a "RNTO" command from the client; return no value if the server should accept the request (and thie method has already effected the rename of the file), otherwise return a string that will be passed back to the client with a 550 error code rejecting the request More...
 
*string list (string v_cwd, *string v_path, reference< string > v_output)
 this method is run when the server receives a "LIST" command from the client; return no value and set the v_output reference if the server should accept the request, otherwise return a string that will be passed back to the client with a 550 error code rejecting the request More...
 
*string nlst (string v_cwd, *string v_path, reference< string > v_output)
 this method is run when the server receives a "NLST" command from the client; return no value and set the v_output reference if the server should accept the request, otherwise return a string that will be passed back to the client with a 550 error code rejecting the request More...
 
*string machineListFile (string v_cwd, *string v_orig, string v_path, reference< string > v_output)
 this method is run when the server receives a "LIST" command from the client; return no value and set the v_output reference if the server should accept the request, otherwise return a string that will be passed back to the client with a 550 error code rejecting the request More...
 
*string machineListDir (string v_cwd, *string v_orig, string v_path, reference v_output, reference< bool > v_isdir)
 this method is run when the server receives a "LIST" command from the client; return no value and set the v_output reference if the server should accept the request, otherwise return a string that will be passed back to the client with a 550 error code rejecting the request More...
 
string getTargetPath (string v_path)
 returns the real path on the filesystem for the given virtual path
 
*string makeDir (string v_cwd, string v_orig, string v_path)
 this method is run when the server receives a "MKD" command from the client; return no value if the server should accept the request, otherwise return a string that will be passed back to the client with a 550 error code rejecting the request More...
 
*string removeDir (string v_cwd, string v_orig, string v_path)
 this method is run when the server receives a "RMD" command from the client; return no value if the server should accept the request, otherwise return a string that will be passed back to the client with a 550 error code rejecting the request More...
 
*string deleteFile (string v_cwd, string v_orig, string v_path)
 this method is run when the server receives a "DELE" command from the client; return no value if the server should accept the request, otherwise return a string that will be passed back to the client with a 550 error code rejecting the request More...
 

Public Attributes

*string root
 the root directory for file-based FTP servers; if no value is set, then the file data will be passed to the fileDataReceived() method instead
 
bool bin
 if False (the default), then files are received as strings, if True, then as binary objects; this only affects how file data is passed to the fileDataReceived() method
 
list< auto > listeners = ()
 list of listener info; do not write to this list directly, use AbstractFtpHandler::addListener() instead (the internal format may change)
 
HttpServer::AbstractAuthenticator auth
 authentication object
 

Detailed Description

this class is used to customize and control the behavior of Qorus FTP servers attached to services

Member Function Documentation

◆ addListener() [1/2]

OMQ::AbstractFtpHandler::addListener ( int  port)

adds a listener from a port number; listener will start up on all interfaces on the given port

Parameters
portthe port number to listen on; the listener will start up on all interfaces on the given port

◆ addListener() [2/2]

OMQ::AbstractFtpHandler::addListener ( string  bind)

adds a listener from a bind string in the format: "address:port" (ex: "192.168.20.1:8011")

Parameters
bindthe address:port string to bind the listener to

◆ addListeners()

OMQ::AbstractFtpHandler::addListeners ( list  l)

adds a list of listeners; each element should be either a bind string in the format: "address:port" (ex: "192.168.20.1:8011") or an integer port, meaning to bind on all interfaces on that port

Parameters
llist of listeners; each element should be either a bind string in the format: "address:port" (ex: "192.168.20.1:8011") or an integer port, meaning to bind on all interfaces on that port

◆ authChangeDir()

*string OMQ::AbstractFtpHandler::authChangeDir ( string  v_cwd,
string  v_orig,
reference< string v_path 
)

this method is run when the server receives a "CWD" command from the client but before the server updates the current working directory; return no value if the server should accept the change directory request, otherwise return a string that will be passed back to the client with a 550 error code rejecting the "CWD" request

Parameters
v_cwdthe current working directory
v_origthe original literal argument passed by the client
v_patha reference to a string giving the normalized version of the directory name sent by the client (normalized means that it is a complete path from "/" without any references to ".." or "."); the actual directory name can be changed by this method by modifying the value of the reference (and returning NOTHING to authorize the change directory command)
Returns
no value if the server will accept the change directory request, otherwise return a string that will be passed back to the client with a 550 error code rejecting the request; note that the default is to return no value and therefore accept the request
Example:
*string MyFtpHandler::authChangeDir(string v_cwd, string v_orig, reference v_path) {
log(LL_INFO, "cwd: %n orig: %n path: %n", v_cwd, v_orig, v_path);
*string v_err = AbstractFtpHandler::authChangeDir(v_cwd, v_orig, v_path);
if (exists v_err)
log(LL_INFO, "denying CWD: %s", v_err);
else
log(LL_INFO, "authorizing CWD %s -> %s", v_cwd, v_path);
return v_err;
}

◆ authReceiveFile()

*string OMQ::AbstractFtpHandler::authReceiveFile ( string  cwd,
string  orig,
reference< string path 
)

this method is run when the server receives a "STOR" command from the client but before the server opens the data channel to receive the file; return no value if the server should accept the file, otherwise return a string that will be passed back to the client with a 500 error code rejecting the "STOR" request

Parameters
cwdthe current working directory
origthe original literal argument passed by the client
patha reference to a string giving the normalized path for the file that the client would like to send to the server; the actual file name can be changed by this method by modifying the value of the reference (and returning NOTHING to authorize the receipt of the file)
Returns
no value if the server will accept the file, otherwise return a string that will be passed back to the client with a 500 error code rejecting the "STOR" request; note that the default is to return no value and therefore accept the file from the client
Example:
*string MyFtpHandler::authReceiveFile(string cwd, string orig, reference path) {
log(LL_INFO, "authorizing receipt of file %s -> %s", path, path + ".tmp");
path += ".tmp";
}

◆ authRename()

*string OMQ::AbstractFtpHandler::authRename ( string  v_cwd,
string  v_orig,
reference< string v_path 
)

this method is run when the server receives a "RNFR" command from the client; return no value if the server should accept the request, otherwise return a string that will be passed back to the client with a 550 error code rejecting the "RNFR" request

Parameters
v_cwdthe current working directory
v_origthe original literal argument passed by the client
v_patha reference to a string giving the normalized version of the path (normalized means that it is a complete path from "/" without any references to ".." or "."); the actual path can be changed by this method by modifying the value of the reference (and returning NOTHING to authorize the command)
Returns
no value if the server will accept the request, otherwise return a string that will be passed back to the client with a 550 error code rejecting the request; note that the default is to return no value and therefore accept the request
Example:
*string MyFtpHandler::authRename(string v_cwd, string v_orig, reference v_path) {
*string v_err = AbstractFtpHandler::authRename(v_cwd, v_orig, v_path);
if (exists v_err)
log(LL_INFO, "denying RNFR: %s", v_err);
else
log(LL_INFO, "authorizing RNFR %s", v_cwd, v_path);
return v_err;
}

◆ authSendFile()

*string OMQ::AbstractFtpHandler::authSendFile ( string  cwd,
string  orig,
reference  path 
)

this method is run when the server receives a "RETR" command from the client but before the server opens the data channel to receive the file; return no value if the server should accept the file, otherwise return a string that will be passed back to the client with a 500 error code rejecting the request

Parameters
cwdthe current working directory
origthe original literal argument passed by the client
patha reference to a string giving the normalized path for the file that the client would like to receive from the server; the actual file name can be changed by this method by modifying the value of the reference (and returning NOTHING to authorize sending of the file)
Returns
no value if the server will accept the file, otherwise return a string that will be passed back to the client with a 500 error code rejecting the "STOR" request; note that the default is to return no value and therefore accept the file from the client

◆ constructor()

OMQ::AbstractFtpHandler::constructor ( *string  v_root,
bool  v_bin = False,
HttpServer::AbstractAuthenticator  v_auth = new DefaultQorusRBACAuthenticator() 
)

creates the object with the given arguments

Parameters
v_rootthe root directory for file-based FTP handlers; if this argument is not set, then the filesystem is not directly accessed by this object; instead data will be provided or requested directly (see fileDataReceived())
v_binif True then each file received will be read in as a binary object (only has an effect when no root directory is set)
v_auththe HttpServer::AbstractAuthenticator for the object; if no argument is passed, then the system RBAC authenticator is used; meaning that Qorus application users are required to connect, and the users must have the OMQ::QR_LOGIN role to connect as well
Example:
class MyFtpHandler inherits public OMQ::AbstractFtpHandler {
constructor() : AbstractFtpHandler("/opt/myftproot") {
}
}

◆ deleteFile()

*string OMQ::AbstractFtpHandler::deleteFile ( string  v_cwd,
string  v_orig,
string  v_path 
)

this method is run when the server receives a "DELE" command from the client; return no value if the server should accept the request, otherwise return a string that will be passed back to the client with a 550 error code rejecting the request

Parameters
v_cwdthe current working directory
v_origthe original literal argument passed by the client
v_patha string giving the normalized version of the path (normalized means that it is a complete path from "/" without any references to ".." or ".")
Returns
no value if the server will accept the request, otherwise return a string that will be passed back to the client with a 550 error code rejecting the request; note that the default is to return no value and therefore accept the request
Example:
*string MyFtpHandler::deleteFile(string v_cwd, string v_orig, string v_path) {
*string v_err = AbstractFtpHandler::deleteFile(v_cwd, v_orig, v_path);
if (exists v_err)
log(LL_INFO, "DELE error: %s", v_err);
else
log(LL_INFO, "DELE OK: %s", v_path);
return v_err;
}

◆ fileDataReceived()

OMQ::AbstractFtpHandler::fileDataReceived ( string  path,
data  data 
)

this method is called when the server has received a file and no root directory is set

Parameters
paththe complete path of the file including the current working directory (starting from default "/" if the client did not issue any CWD commands) with the filename as given by the FTP client
datathe file data; will be a string if bin is False, otherwise it will be a binary object
See also
fileReceived()

◆ fileReceived()

OMQ::AbstractFtpHandler::fileReceived ( string  path)

this method is called when the server has received a file

Parameters
paththe complete path of the file that was saved to the filesystem including the current working directory (starting from default "/" if the client did not issue any CWD commands) with the filename as given by the FTP client; the path does not include the FTP handler base directory, so a path of "/" is based in the top-level directory of root
Example:
MyFtpHandler::fileReceived(string path) {
++v_stats."in".files;
log(LL_INFO, "received file: dir=%n fn=%n", dirname(path), basename(path));
}
See also
fileDataReceived()

◆ fileSent()

OMQ::AbstractFtpHandler::fileSent ( string  path)

this method is called when the server has sent a file

Parameters
paththe complete path of the file that was sent including the current working directory (starting from default "/") with the filename as given by the FTP client; the path does not include the FTP handler base directory, so a path of "/" is based in the top-level directory of root
See also
sendFile()

◆ list()

*string OMQ::AbstractFtpHandler::list ( string  v_cwd,
*string  v_path,
reference< string v_output 
)

this method is run when the server receives a "LIST" command from the client; return no value and set the v_output reference if the server should accept the request, otherwise return a string that will be passed back to the client with a 550 error code rejecting the request

Parameters
v_cwdthe current working directory
v_paththe original literal argument passed by the client
v_outputassign an output string to this reference for the output to be returned to the client
Returns
no value if the server will accept the request, otherwise return a string that will be passed back to the client with a 550 error code rejecting the request; note that the default is to return no value
Example:
*string MyFtpHandler::list(string v_cwd, *string v_path, reference v_output) {
*string v_err = AbstractFtpHandler::list(v_cwd, v_path, \v_output);
if (exists v_err)
log(LL_INFO, "LIST error: %s", v_err);
else
log(LL_INFO, "LIST OK: %n", v_path);
return v_err;
}

◆ machineListDir()

*string OMQ::AbstractFtpHandler::machineListDir ( string  v_cwd,
*string  v_orig,
string  v_path,
reference  v_output,
reference< bool >  v_isdir 
)

this method is run when the server receives a "LIST" command from the client; return no value and set the v_output reference if the server should accept the request, otherwise return a string that will be passed back to the client with a 550 error code rejecting the request

Parameters
v_cwdthe current working directory
v_origthe original literal argument passed by the client
v_patha string giving the normalized version of the path argument (normalized means that it is a complete path from "/" without any references to ".." or ".")
v_outputassign an output string to this reference for the output to be returned to the client
v_isdirif False on output and there is an error response, then a 501 code will be generated instead of a 550 code
Returns
no value if the server will accept the request, otherwise return a string that will be passed back to the client with a 550 error code rejecting the request; note that the default is to return no value

◆ machineListFile()

*string OMQ::AbstractFtpHandler::machineListFile ( string  v_cwd,
*string  v_orig,
string  v_path,
reference< string v_output 
)

this method is run when the server receives a "LIST" command from the client; return no value and set the v_output reference if the server should accept the request, otherwise return a string that will be passed back to the client with a 550 error code rejecting the request

Parameters
v_cwdthe current working directory
v_origthe original literal argument passed by the client
v_patha string giving the normalized version of the path argument (normalized means that it is a complete path from "/" without any references to ".." or ".")
v_outputassign an output string to this reference for the output to be returned to the client
Returns
no value if the server will accept the request, otherwise return a string that will be passed back to the client with a 550 error code rejecting the request; note that the default is to return no value

◆ makeDir()

*string OMQ::AbstractFtpHandler::makeDir ( string  v_cwd,
string  v_orig,
string  v_path 
)

this method is run when the server receives a "MKD" command from the client; return no value if the server should accept the request, otherwise return a string that will be passed back to the client with a 550 error code rejecting the request

Parameters
v_cwdthe current working directory
v_origthe original literal argument passed by the client
v_patha string giving the normalized version of the path (normalized means that it is a complete path from "/" without any references to ".." or ".")
Returns
no value if the server will accept the request, otherwise return a string that will be passed back to the client with a 550 error code rejecting the request; note that the default is to return no value and therefore accept the request
Example:
*string MyFtpHandler::makeDir(string v_cwd, string v_orig, string v_path) {
*string v_err = AbstractFtpHandler::makeDir(v_cwd, v_orig, v_path);
if (exists v_err)
log(LL_INFO, "MKD error: %s", v_err);
else
log(LL_INFO, "MKD OK: %s", v_path);
return v_err;
}

◆ modifiedTime()

*string OMQ::AbstractFtpHandler::modifiedTime ( string  v_cwd,
string  v_orig,
string  v_path,
reference< date v_date 
)

this method is called when the "MDTM" command is received

Parameters
v_cwdthe current working directory
v_origthe original literal argument passed by the client
v_paththe complete path of the file including the current working directory (starting from default "/") with the filename as given by the FTP client
v_datea reference to a date for the last modified date of the file (output variable)
Returns
the file size to return to the FTP client

◆ nlst()

*string OMQ::AbstractFtpHandler::nlst ( string  v_cwd,
*string  v_path,
reference< string v_output 
)

this method is run when the server receives a "NLST" command from the client; return no value and set the v_output reference if the server should accept the request, otherwise return a string that will be passed back to the client with a 550 error code rejecting the request

Parameters
v_cwdthe current working directory
v_paththe original literal argument passed by the client
v_outputassign an output string to this reference for the output to be returned to the client
Returns
no value if the server will accept the request, otherwise return a string that will be passed back to the client with a 550 error code rejecting the request; note that the default is to return no value
Example:
*string MyFtpHandler::nlst(string v_cwd, *string v_path, reference v_output) {
*string v_err = AbstractFtpHandler::nlst(v_cwd, v_path, \v_output);
if (exists v_err)
log(LL_INFO, "NLST error: %s", v_err);
else
log(LL_INFO, "NLST OK: %n", v_path);
return v_err;
}

◆ removeDir()

*string OMQ::AbstractFtpHandler::removeDir ( string  v_cwd,
string  v_orig,
string  v_path 
)

this method is run when the server receives a "RMD" command from the client; return no value if the server should accept the request, otherwise return a string that will be passed back to the client with a 550 error code rejecting the request

Parameters
v_cwdthe current working directory
v_origthe original literal argument passed by the client
v_patha string giving the normalized version of the path (normalized means that it is a complete path from "/" without any references to ".." or ".")
Returns
no value if the server will accept the request, otherwise return a string that will be passed back to the client with a 550 error code rejecting the request; note that the default is to return no value and therefore accept the request
Example:
*string MyFtpHandler::removeDir(string v_cwd, string v_orig, string v_path) {
*string v_err = AbstractFtpHandler::removeDir(v_cwd, v_orig, v_path);
if (exists v_err)
log(LL_INFO, "RMD error: %s", v_err);
else
log(LL_INFO, "RMD OK: %s", v_path);
return v_err;
}

◆ rename()

*string OMQ::AbstractFtpHandler::rename ( string  v_cwd,
string  v_orig_to,
string  v_from,
string  v_to 
)

this method is run when the server receives a "RNTO" command from the client; return no value if the server should accept the request (and thie method has already effected the rename of the file), otherwise return a string that will be passed back to the client with a 550 error code rejecting the request

Parameters
v_cwdthe current working directory
v_orig_tothe original literal argument passed by the client
v_froma string giving the normalized version of the "from" (source) path (normalized means that it is a complete path from "/" without any references to ".." or ".")
v_toa string giving the normalized version of the "to" (target) path (normalized means that it is a complete path from "/" without any references to ".." or ".")
Returns
no value if the server will accept the request, otherwise return a string that will be passed back to the client with a 550 error code rejecting the request; note that the default is to return no value and therefore accept the request
Example:
*string MyFtpHandler::rename(string v_cwd, string v_orig_to, string v_from, string v_to) {
*string v_err = AbstractFtpHandler::rename(v_cwd, v_orig_to, v_from, v_to);
if (exists v_err)
log(LL_INFO, "RNTO error: %s", v_err);
else
log(LL_INFO, "RNFR OK: %s - >%s", v_from, v_to);
return v_err;
}

◆ sendFile()

data OMQ::AbstractFtpHandler::sendFile ( string  path)

this method is called when the server should send a file

Parameters
paththe complete path of the file including the current working directory (starting from default "/") with the filename as given by the FTP client
Returns
the file data to send
See also
fileReceived()

◆ size()

*string OMQ::AbstractFtpHandler::size ( string  v_cwd,
string  v_orig,
string  v_path,
reference< int v_size 
)

this method is called when the "SIZE" command is received

Parameters
v_cwdthe current working directory
v_origthe original literal argument passed by the client
v_paththe complete path of the file including the current working directory (starting from default "/") with the filename as given by the FTP client
v_sizea reference to an int for the file size (output variable)
Returns
the file size to return to the FTP client

The documentation for this class was generated from the following file: