SftpPoller client class implementation. More...

#include <SftpPoller.qm.dox.h>

Public Member Methods
void	destructor ()
	stops the polling operation if in progress and destroys the object

int	getPollCount ()
	returns the current poll count

void	logInfo (string fmt)
	calls the `"log_info"` closure or call reference with important information

void	logDetail (string fmt)
	calls the `"log_detail"` closure or call reference with detail information

void	logDebug (string fmt)
	calls the `"log_debug"` closure or call reference with verbose debugging information

void	setMask ()
	converts a glob mask into a regex

int	getStoreFile (soft< timeout > n_timeout, string remote_path, string local_path)
	retrieves a remote file and stores it to a local path

string	getTextFile (soft< string > n_encoding, string path, soft< timeout > n_timeout)
	retrieves a text file and returns the file's contents

binary	getFile (string path, soft< timeout > n_timeout)
	retrieves a binary file and returns the file's contents

void	rename (soft< timeout > n_timeout, string old, string nnew)
	renames a file on the server

void	removeFile (string fn, soft< timeout > n_timeout)
	deletes a file on the server

soft< hash< Qore::SSH2::Ssh2StatInfo > >	stat (string path, soft< timeout > n_timeout)
	returns information about a remote file (see Qore::SSH2::SFTPClient::stat for a description of the return format)

int	start ()
	starts polling in the background; returns the thread ID of the polling thread

void	stopNoWait ()
	stops the polling operation, returns immediately

void	stop ()
	stops the polling operation, returns when the polling operation has been stopped

void	waitStop ()
	waits indefinitely for the polling operation to stop; if polling was not in progress then this method returns immediately

void	startInline ()
	starts the polling operation inline (not in a background thread)

hash< SftpPollerFileEventInfo >	retrieveTempFile (hash< SftpPollerFileEventInfo > event)
	Retrieves the remote file to local_dir using a temporary file.

hash< SftpPollerFileEventInfo >	retrieveFile (hash< SftpPollerFileEventInfo > event)
	Retrieves the remote file to local_dir directly.

void	sftpSleep (softint secs)
	sleeps for the specificed number of seconds

void	setup (SFTPClient sftp)
	Sets up a new SFTP connection.

void	run ()
	starts the polling operation

soft< bool >	fileEvent (list< hash< SftpPollerFileEventInfo > > l)
	called for each poll with a list of all files matched before transfer; if this method returns False or nothing, then the singleFileEvent method is not called

abstract void	singleFileEvent (hash< SftpPollerFileEventInfo > fih)
	called for each matching file individually whenever matching files are polled with the list of matching file names; if any error occurs here, the error is logged and the polling operation is retried

abstract void	postSingleFileEvent (hash< SftpPollerFileEventInfo > fih)
	called after singleFileEvent() for each matching file individually whenever matching files are polled with the list of matching file names; if any error occurs here, the polling operation stops

Static Public Member Methods
static void	checkPath (string path, string type, bool write)
	checks a path on the local file system

Public Attributes
const auto	OrderAsc = ...
	ascending sort order

const auto	OrderDesc = ...
	descending sort order

const auto	SortNone = ...
	no sorting

const auto	SortName = ...
	sort by name

const auto	RequiredKeys = ...
	minimum required keys for all constructors

const auto	RequiredKeysWithHost = ...
	RequiredKeys for the constructor(hash) without an Qore::SSH2::SFTPClient argument.

const auto	Defaults = ...
	default values for constructor hash argument

const auto	OptionalKeys = ...
	optional constructor hash keys

const auto	AllKeys = ...
	all keys

const auto	ErrorDelay = ...
	pause when SFTP errors are detected

Private Attributes
string	host
	host or address name

int	port
	port

string	user
	user

string	url
	url

soft< string >	pass
	password; one of `"pass"` or `"keyfile"` must be set

soft< string >	keyfile
	path to the ssh private key in PEM format; one of `"pass"` or `"keyfile"` must be set

string	rootSftpPath
	path after connect to SFTP server

soft< string >	mask
	file glob name mask (ignored if `"regex_mask"` also set)

int	poll_interval
	poll interval in seconds

string	local_dir
	Local directory to transfer file.

string	tempfile_template
	The temporary filename template when `local_dir` is set.

bool	atomic_transfer
	Atomic transfer flag for use with `local_dir`.

bool	delete_remote_file
	Delete file on remote SFTP server after processing?

soft< string >	move_remote_file
	Remote target directory for moving the file on the remote SFTP server after processing.

bool	get_files
	internal "get files" flag

int	tid
	polling tid

timeout	timeout
	timeout in ms

Qore::SSH2::SFTPClient	sftp
	SFTPClient object.

soft< softint >	minage
	minimum file age

soft< string >	encoding
	file encoding for text files

soft< code >	log_info
	optional info log closure

soft< code >	log_detail
	optional detail log closure

soft< code >	log_debug
	optional debug log closure

soft< code >	start_thread
	optional start thread closure

soft< code >	sleep
	optional sleep closure

bool	binary
	binary transfer flag (for singleFileEvent())

bool	writable
	chech if path is writable for others in constructor

string	check_file
	name of check writable file

soft< bool >	skip_file_content_retrieval
	whether or not to skip the file content retrieval in runOnce()

SFTPClient	new_sftp
	For when the client gets updating during polling.

Detailed Description

SftpPoller client class implementation.

See the constructor options for information on how to configure this object; note that either

delete_remote_file or
move_remote_file must be set, or SFTP files polled will remain where they are in the remote SFTP server, unless they are removed or moved during polling processing.

Only one of these options may be set at one time; setting both will result in an error

Member Function Documentation

◆ checkPath()

static void SftpPoller::SftpPoller::checkPath	(	string	path,
		string	type,
		bool	write
	)

static

checks a path on the local file system

Exceptions

DIR-ERROR this exception is thrown if the local path does not exist, is not readable, is not a directory, or should be writable and is not

◆ getStoreFile()

int SftpPoller::SftpPoller::getStoreFile	(	soft< timeout >	n_timeout,
		string	remote_path,
		string	local_path
	)

retrieves a remote file and stores it to a local path

Parameters

remote_path	the remote file path
local_path	the local file path
n_timeout	a timeout in milliseconds

Returns: the number of bytes transferred

◆ postSingleFileEvent()

abstract void SftpPoller::SftpPoller::postSingleFileEvent ( hash< SftpPollerFileEventInfo > fih )

called after singleFileEvent() for each matching file individually whenever matching files are polled with the list of matching file names; if any error occurs here, the polling operation stops

This method would normally delete / rename / move files processed by singleFileEvent() so that they would not be polled a second time. If an error occurs in this operation, then the polling event will stop since continuing after failing to delete, rename, or move a file already processed would cause the file to be processed more than once.

Parameters

fih

a hash of file data and information with the following keys:

name: the name of the file, link, or directory
size: the size of the file in bytes
uid: the UID of the owner of the file
gid: the GID of the owner of the file
mode: the permissions / mode of the file
atime: the last accessed date/time of the file
mtime: the last modified date/time of the file
type: the type of file; one of: "REGULAR", "DIRECTORY", "SYMBOLIC-LINK", "BLOCK-DEVICE", "CHARACTER-DEVICE", "FIFO", "SYMBOLIC-LINK", "SOCKET", or "UNKNOWN"
perm: a string giving UNIX-style permissions for the file (ex: "-rwxr-xr-x")
data: the file's data; this will be a string unless the "binary" option is set to True, in which case this key is assigned to the files binary data; this hash key is only present if skip_file_content_retrieval was False in the SftpPoller::SftpPoller::constructor options
filepath: the remote filepath relative to SFTP root directory

◆ singleFileEvent()

abstract void SftpPoller::SftpPoller::singleFileEvent ( hash< SftpPollerFileEventInfo > fih )

called for each matching file individually whenever matching files are polled with the list of matching file names; if any error occurs here, the error is logged and the polling operation is retried

Parameters

fih

a hash of file data and information with the following keys:

name: the name of the file, link, or directory
size: the size of the file in bytes
uid: the UID of the owner of the file
gid: the GID of the owner of the file
mode: the permissions / mode of the file
atime: the last accessed date/time of the file
mtime: the last modified date/time of the file
type: the type of file; one of: "REGULAR", "DIRECTORY", "SYMBOLIC-LINK", "BLOCK-DEVICE", "CHARACTER-DEVICE", "FIFO", "SYMBOLIC-LINK", "SOCKET", or "UNKNOWN"
perm: a string giving UNIX-style permissions for the file (ex: "-rwxr-xr-x")
data: the file's data; this will be a string unless the "binary" option is set to True, in which case this key is assigned to the files binary data; this hash key is only present if skip_file_content_retrieval was False in the SftpPoller::SftpPoller::constructor options
filepath: the remote filepath relative to SFTP root directory

◆ start()

int SftpPoller::SftpPoller::start ( )

starts polling in the background; returns the thread ID of the polling thread

if polling had already been started, then the thread ID of the polling thread is returned immediately

◆ startInline()

void SftpPoller::SftpPoller::startInline ( )

starts the polling operation inline (not in a background thread)

Exceptions

SFTPPOLLER-ERROR this exception is thrown if polling is already in progress

◆ stop()

void SftpPoller::SftpPoller::stop ( )

stops the polling operation, returns when the polling operation has been stopped

if polling was not in progress then this method returns immediately

Exceptions

THREAD-ERROR this exception is thrown if this method is called from the event thread since it would result in a deadlock

See also: stopNoWait()

◆ stopNoWait()

void SftpPoller::SftpPoller::stopNoWait ( )

stops the polling operation, returns immediately

See also: stop()

◆ waitStop()

void SftpPoller::SftpPoller::waitStop ( )

waits indefinitely for the polling operation to stop; if polling was not in progress then this method returns immediately

Exceptions

THREAD-ERROR this exception is thrown if this method is called from the event thread since it would result in a deadlock

Member Data Documentation

◆ delete_remote_file

bool SftpPoller::SftpPoller::delete_remote_file

private

Delete file on remote SFTP server after processing?

This cannot be True while move_remote_file is set

◆ move_remote_file

soft<string> SftpPoller::SftpPoller::move_remote_file

private

Remote target directory for moving the file on the remote SFTP server after processing.

This cannot be True while delete_remote_file is set

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

doxygen/qlib/SftpPoller/SftpPoller.qm.dox.h

Public Member Methods

Static Public Member Methods

Public Attributes

Private Attributes

Detailed Description

Member Function Documentation

◆ checkPath()

◆ getStoreFile()

◆ postSingleFileEvent()

◆ singleFileEvent()

◆ start()

◆ startInline()

◆ stop()

◆ stopNoWait()

◆ waitStop()

Member Data Documentation

◆ delete_remote_file

◆ move_remote_file