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

Public Member Methods
	constructor (*string root, bool bin=False, HttpServer::AbstractAuthenticator 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< auto > 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 cwd, string orig, string path, reference< int > size)
	this method is called when the `"SIZE"` command is received More...

*string	modifiedTime (string cwd, string orig, string path, reference< date > mdate)
	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 cwd, string orig, reference< string > 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 cwd, string orig, reference< string > 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 cwd, string orig_to, string from, string 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 cwd, *string path, reference< string > output)
	this method is run when the server receives a `"LIST"` command from the client; return no value and set the 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 cwd, *string path, reference< string > output)
	this method is run when the server receives a `"NLST"` command from the client; return no value and set the 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 cwd, *string orig, string path, reference< string > output)
	this method is run when the server receives a `"LIST"` command from the client; return no value and set the 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 cwd, *string orig, string path, reference< string > output, reference< bool > isdir)
	this method is run when the server receives a `"LIST"` command from the client; return no value and set the 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 path)
	returns the real path on the filesystem for the given virtual path

*string	makeDir (string cwd, string orig, string 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 cwd, string orig, string 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 cwd, string orig, string 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...

	logFatal (softstring msg)
	writes the message to the service log file if the log level is equal or lower More...

	logError (softstring msg)
	writes the message to the service log file if the log level is equal or lower More...

	logWarn (softstring msg)
	writes the message to the service log file if the log level is equal or lower More...

	logInfo (softstring msg)
	writes the message to the service log file if the log level is equal or lower More...

	logDebug (softstring msg)
	writes the message to the service log file if the log level is equal or lower More...

	logTrace (softstring msg)
	writes the message to the service log file if the log level is equal or lower 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

port	the 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

bind	the address:port string to bind the listener to

◆ addListeners()

OMQ::AbstractFtpHandler::addListeners ( list< auto > 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

l	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

◆ authChangeDir()

*string OMQ::AbstractFtpHandler::authChangeDir	(	string	cwd,
		string	orig,
		reference< string >	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

cwd	the current working directory
orig	the original literal argument passed by the client
path	a 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 authChangeDir(string cwd, string orig, reference path) {
log(LL_INFO, "cwd: %n orig: %n path: %n", cwd, orig, path);
*string v_err = AbstractFtpHandler::authChangeDir(cwd, orig, path);
if (exists v_err)
log(LL_INFO, "denying CWD: %s", v_err);
else
log(LL_INFO, "authorizing CWD %s -> %s", cwd, 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

cwd	the current working directory
orig	the original literal argument passed by the client
path	a 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	cwd,
		string	orig,
		reference< string >	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

cwd	the current working directory
orig	the original literal argument passed by the client
path	a 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 cwd, string orig, reference path) {
*string v_err = AbstractFtpHandler::authRename(cwd, orig, path);
if (exists v_err)
log(LL_INFO, "denying RNFR: %s", v_err);
else
log(LL_INFO, "authorizing RNFR %s", cwd, 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

cwd	the current working directory
orig	the original literal argument passed by the client
path	a 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	root,
		bool	bin = `False`,
		HttpServer::AbstractAuthenticator	auth = `new DefaultQorusRBACAuthenticator()`
	)

creates the object with the given arguments

Parameters

root	the 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())
bin	if True then each file received will be read in as a binary object (only has an effect when no root directory is set)
auth	the 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	cwd,
		string	orig,
		string	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

cwd	the current working directory
orig	the original literal argument passed by the client
path	a 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 cwd, string orig, string path) {
*string v_err = AbstractFtpHandler::deleteFile(cwd, orig, path);
if (exists v_err)
log(LL_INFO, "DELE error: %s", v_err);
else
log(LL_INFO, "DELE OK: %s", 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

path	the 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
data	the 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

path the 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

path	the 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	cwd,
		*string	path,
		reference< string >	output
	)

this method is run when the server receives a "LIST" command from the client; return no value and set the 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

cwd	the current working directory
path	the original literal argument passed by the client
output	assign 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 cwd, *string path, reference<string> output) {
*string v_err = AbstractFtpHandler::list(cwd, path, \output);
if (exists v_err)
log(LL_INFO, "LIST error: %s", v_err);
else
log(LL_INFO, "LIST OK: %n", path);
return v_err;
}