allows Qore programs to send and receive data through an ssh2 channel More...

#include <QC_SSH2Channel.dox.h>

Public Member Methods
nothing	close (timeout timeout=-1)
	Closes the channel. More...

	constructor ()
	Throws an exception; the constructor cannot be called manually. More...

	copy ()
	Throws an exception; currently SSH2Channel objects cannot be copied. More...

	destructor ()
	destroys the object by disconnecting the channel and deregistering with the parent object

bool	eof ()
	returns `True` if an end of file condition is flagged on an open channel More...

nothing	exec (string command, timeout timeout=-1)
	Executes a command on the channel. More...

nothing	extendedDataIgnore (timeout timeout=-1)
	Discard all data in substreams (i.e. stderr, etc) immediately when it arrives. More...

nothing	extendedDataMerge (timeout timeout=-1)
	Merge substreams (i.e. `stderr`, etc) into stream 0 for reading. More...

nothing	extendedDataNormal (timeout timeout=-1)
	Queue data in substreams (i.e. `stderr`, etc) for eventual reading. More...

string	getEncoding ()
	Returns the name of the default string encoding of the channel. More...

int	getExitStatus ()
	Returns the exit code raised by the process running on the remote host at the other end of the named channel. More...

string	read (softint stream_id=0, timeout timeout=10000)
	Reads data on the given stream and returns it as a string. More...

binary	readBinary (softint stream_id=0, timeout timeout=10000)
	Reads data on the given stream and returns it as a binary object. More...

binary	readBinaryBlock (softint size, softint stream_id=0, timeout timeout=-1)
	Reads a block of data of a given size on the given stream and returns it as a binary object. More...

string	readBlock (softint size, softint stream_id=0, timeout timeout=-1)
	Reads a block of data of a given size on the given stream and returns it as a string. More...

nothing	requestPty (string term="vanilla", string modes="", softint width=LIBSSH2_TERM_WIDTH, softint height=LIBSSH2_TERM_HEIGHT, softint width_px=LIBSSH2_TERM_WIDTH_PX, softint height_px=LIBSSH2_TERM_HEIGHT_PX, timeout timeout=-1)
	Requests a terminal to be allocated to the channel. More...

nothing	requestX11Forwarding (softint screen_no=0, bool single_connection=False, string auth_proto="", string auth_cookie="", timeout timeout=-1)
	Request X11 forwarding on the channel. More...

nothing	sendEof (timeout timeout=-1)
	Informs the remote end that we are closing the connection. More...

nothing	setEncoding (string encoding)
	Sets the default string encoding for the channel; all string data read from the channel will be tagged with the encoding given. More...

nothing	setenv (string var, string value, timeout timeout=-1)
	Sets an environment variable on the channel. More...

nothing	shell (timeout timeout=-1)
	Request a login shell to be started for the channel. More...

nothing	subsystem (string command, timeout timeout=-1)
	Executes a command on the channel as a subsystem. More...

nothing	waitClosed (timeout timeout=-1)
	Wait for the remote end to acknowledge the close request. More...

nothing	waitEof (timeout timeout=-1)
	Wait for the remote end to acknowledge an EOF request. More...

nothing	write (data data, softint stream_id=0, timeout timeout_ms=-1)
	Writes data to a stream. More...

Detailed Description

allows Qore programs to send and receive data through an ssh2 channel

Restrictions:: Qore::PO_NO_NETWORK

Member Function Documentation

◆ close()

nothing Qore::SSH2::SSH2Channel::close ( timeout timeout = -1 )

Closes the channel.

Example:: chan.close(30s);

Parameters

timeout an integer giving a timeout in milliseconds or a relative date/time value (ex: 15s for 15 seconds); a negative value means do not time out

Exceptions

SSH2CHANNEL-CLOSE-ERROR	server returned an error while waiting for a response
SSH2CHANNEL-ERROR	the channel has been closed
SSH2CHANNEL-TIMEOUT	timeout communicating on channel
SSH2-ERROR	socket error sending data; timeout on socket; invalid SSH2 protocol response; server returned an error message

◆ constructor()

Qore::SSH2::SSH2Channel::constructor ( )

Throws an exception; the constructor cannot be called manually.

Throws an exception if called directly; this class cannot be instantiated directly

Exceptions

SSH2CHANNEL-CONSTRUCTOR-ERROR this class cannot be directly constructed but is created from methods in the SSH2Client class

◆ copy()

Qore::SSH2::SSH2Channel::copy ( )

Throws an exception; currently SSH2Channel objects cannot be copied.

Exceptions

SSH2CHANNEL-COPY-ERROR copying SSH2Channel objects is not supported

◆ eof()

bool Qore::SSH2::SSH2Channel::eof ( )

returns True if an end of file condition is flagged on an open channel

Example:: bool b = chan.eof();

Returns: True if an end of file condition is flagged on an open channel, False if not

Exceptions

SSH2CHANNEL-ERROR the channel has been closed

◆ exec()

nothing Qore::SSH2::SSH2Channel::exec	(	string	command,
		timeout	timeout = `-1`
	)

Executes a command on the channel.

Example:: chan.exec("ls -l", 30s);

use SSH2Channel::read() to read the output

Parameters

command	the command to run
timeout	an integer giving a timeout in milliseconds or a relative date/time value (ex: `15s` for 15 seconds); a negative value means do not time out

Exceptions

SSH2CHANNEL-EXEC-ERROR	libssh2 reported an error on the channel while waiting for confirmation from the server
SSH2CHANNEL-ERROR	the channel has been closed
SSH2CHANNEL-TIMEOUT	timeout communicating on channel
SSH2-ERROR	socket error sending data; timeout on socket; invalid SSH2 protocol response; server returned an error message

◆ extendedDataIgnore()

nothing Qore::SSH2::SSH2Channel::extendedDataIgnore ( timeout timeout = -1 )

Discard all data in substreams (i.e. stderr, etc) immediately when it arrives.

Example:: chan.extendedDataIgnore(30s);

Parameters

timeout an integer giving a timeout in milliseconds or a relative date/time value (ex: 15s for 15 seconds); a negative value means do not time out

Exceptions

SSH2CHANNEL-EXTENDEDDATAIGNORE-ERROR	server returned an error while waiting for a response
SSH2CHANNEL-ERROR	the channel has been closed
SSH2CHANNEL-TIMEOUT	timeout communicating on channel
SSH2-ERROR	socket error sending data; timeout on socket; invalid SSH2 protocol response; server returned an error message

◆ extendedDataMerge()

nothing Qore::SSH2::SSH2Channel::extendedDataMerge ( timeout timeout = -1 )

Merge substreams (i.e. stderr, etc) into stream 0 for reading.

Example:: chan.extendedDataMerge(30s);

Parameters

timeout an integer giving a timeout in milliseconds or a relative date/time value (ex: 15s for 15 seconds); a negative value means do not time out

Exceptions

SSH2CHANNEL-EXTENDEDDATAMERGE-ERROR	server returned an error while waiting for a response
SSH2CHANNEL-ERROR	the channel has been closed
SSH2CHANNEL-TIMEOUT	timeout communicating on channel
SSH2-ERROR	socket error sending data; timeout on socket; invalid SSH2 protocol response; server returned an error message

◆ extendedDataNormal()

nothing Qore::SSH2::SSH2Channel::extendedDataNormal ( timeout timeout = -1 )

Queue data in substreams (i.e. stderr, etc) for eventual reading.

Example:: chan.extendedDataNormal(30s);

Parameters

timeout an integer giving a timeout in milliseconds or a relative date/time value (ex: 15s for 15 seconds); a negative value means do not time out

Exceptions

SSH2CHANNEL-EXTENDEDDATANORMAL-ERROR	server returned an error while waiting for a response
SSH2CHANNEL-ERROR	the channel has been closed
SSH2CHANNEL-TIMEOUT	timeout communicating on channel
SSH2-ERROR	socket error sending data; timeout on socket; invalid SSH2 protocol response; server returned an error message

◆ getEncoding()

string Qore::SSH2::SSH2Channel::getEncoding ( )

Returns the name of the default string encoding of the channel.

Code Flags:: CONSTANT

Example:: string enc = chan.getEncoding();

Returns: the name of the default string encoding of the channel

◆ getExitStatus()

int Qore::SSH2::SSH2Channel::getExitStatus ( )

Returns the exit code raised by the process running on the remote host at the other end of the named channel.

Example:: int rc = chan.getExitStatus();

Note that the exit status may not be available if the remote end has not yet set its status to closed

Returns: the exit code raised by the process running on the remote host at the other end of the named channel

Exceptions

SSH2CHANNEL-ERROR the channel has been closed

◆ read()

string Qore::SSH2::SSH2Channel::read	(	softint	stream_id = `0`,
		timeout	timeout = `10000`
	)

Reads data on the given stream and returns it as a string.

Example:: string str = chan.read(0, 30s);

Parameters

stream_id	the stream ID to read (0 is the default, meaning `stdin`, 1 is for `stderr`
timeout	an integer giving a timeout in milliseconds or a relative date/time value (ex: `15s` for 15 seconds); a negative value means do not time out

Exceptions

SSH2CHANNEL-READ-ERROR	expecting non-negative integer for stream id as optional first argument to SSH2Channel::read(); use 0 for stdin, 1 for stderr; libssh2 reported an error on the channel while waiting for data from the server
SSH2CHANNEL-ERROR	the channel has been closed
SSH2CHANNEL-TIMEOUT	timeout communicating on channel
SSH2-ERROR	socket error sending data; timeout on socket; invalid SSH2 protocol response; server returned an error message

◆ readBinary()

binary Qore::SSH2::SSH2Channel::readBinary	(	softint	stream_id = `0`,
		timeout	timeout = `10000`
	)

Reads data on the given stream and returns it as a binary object.

Example:: string str = chan.read(0, 30s);

Parameters

stream_id	the stream ID to read (0 is the default, meaning `stdin`, 1 is for `stderr`
timeout	an integer giving a timeout in milliseconds or a relative date/time value (ex: `15s` for 15 seconds); a negative value means do not time out

Exceptions

SSH2CHANNEL-READBINARY-ERROR	expecting non-negative integer for stream id as optional first argument to SSH2Channel::read(); use 0 for stdin, 1 for stderr; libssh2 reported an error on the channel while waiting for data from the server
SSH2CHANNEL-ERROR	the channel has been closed
SSH2CHANNEL-TIMEOUT	timeout communicating on channel
SSH2-ERROR	socket error sending data; timeout on socket; invalid SSH2 protocol response; server returned an error message

◆ readBinaryBlock()

binary Qore::SSH2::SSH2Channel::readBinaryBlock	(	softint	size,
		softint	stream_id = `0`,
		timeout	timeout = `-1`
	)

Reads a block of data of a given size on the given stream and returns it as a binary object.

Example:: binary b = chan.readBinaryBlock(4096, 0, 30s);

Parameters

size	the maximum size of the block of data to read in bytes
stream_id	the stream ID to read (0 is the default, meaning `stdin`, 1 is for `stderr`
timeout	an integer giving a timeout in milliseconds or a relative date/time value (ex: `15s` for 15 seconds); a negative value means do not time out

Returns: a binary object of data representing the block read

Exceptions

SSH2CHANNEL-READBLOCK-ERROR	zero or negative value passed for block size; negative value passed for stream id; libssh2 reported an error on the channel while waiting for data from the server
SSH2CHANNEL-ERROR	the channel has been closed
SSH2CHANNEL-TIMEOUT	timeout communicating on channel
SSH2-ERROR	socket error sending data; timeout on socket; invalid SSH2 protocol response; server returned an error message

◆ readBlock()

string Qore::SSH2::SSH2Channel::readBlock	(	softint	size,
		softint	stream_id = `0`,
		timeout	timeout = `-1`
	)

Reads a block of data of a given size on the given stream and returns it as a string.

Example:: string str = chan.readBlock(4096, 0, 30s);

Parameters

size	the maximum size of the block of data to read in bytes
stream_id	the stream ID to read (0 is the default, meaning `stdin`, 1 is for `stderr`
timeout	an integer giving a timeout in milliseconds or a relative date/time value (ex: `15s` for 15 seconds); a negative value means do not time out

Returns: a string representing the block read; note that if a multibyte character encoding is being read and the end of the block lands in the middle of a character, then the string returned (or the next string read) could have invalid bytes if an attempt is made to use the string as-is

Exceptions

SSH2CHANNEL-READBLOCK-ERROR	zero or negative value passed for block size; negative value passed for stream id; libssh2 reported an error on the channel while waiting for data from the server
SSH2CHANNEL-ERROR	the channel has been closed;
SSH2CHANNEL-TIMEOUT	timeout communicating on channel
SSH2-ERROR	socket error sending data; timeout on socket; invalid SSH2 protocol response; server returned an error message

◆ requestPty()

nothing Qore::SSH2::SSH2Channel::requestPty	(	string	term = `"vanilla"`,
		string	modes = `""`,
		softint	width = `LIBSSH2_TERM_WIDTH`,
		softint	height = `LIBSSH2_TERM_HEIGHT`,
		softint	width_px = `LIBSSH2_TERM_WIDTH_PX`,
		softint	height_px = `LIBSSH2_TERM_HEIGHT_PX`,
		timeout	timeout = `-1`
	)

Requests a terminal to be allocated to the channel.

Example:: chan.requestPty("vt100");

Parameters

term	terminal emulation requested
modes	terminal mode modifier values
width	width of the pty in characters
height	height of the pty in characters
width_px	width of the pty in pixels
height_px	height of the pty in pixels
timeout	an integer giving a timeout in milliseconds or a relative date/time value (ex: `15s` for 15 seconds); a negative value means do not time out

Exceptions

SSH2CHANNEL-REQUESTPTY-ERROR	negative terminal or pixel width, height passed
SSH2CHANNEL-ERROR	the channel has been closed
SSH2CHANNEL-TIMEOUT	timeout communicating on channel
SSH2-ERROR	socket error sending data; timeout on socket; invalid SSH2 protocol response; server returned an error message

◆ requestX11Forwarding()

nothing Qore::SSH2::SSH2Channel::requestX11Forwarding	(	softint	screen_no = `0`,
		bool	single_connection = `False`,
		string	auth_proto = `""`,
		string	auth_cookie = `""`,
		timeout	timeout = `-1`
	)

Request X11 forwarding on the channel.

Example:: chan.requestX11Forwarding(NOTHING, NOTHING, NOTHING, NOTHING, 30s);

Parameters

screen_no	the X11 screen number to forward
single_connection	set to True to forward only a single connection on the channel
auth_proto	the authorization protocol to use
auth_cookie	the authorization cookie to use
timeout	an integer giving a timeout in milliseconds or a relative date/time value (ex: `15s` for 15 seconds); a negative value means do not time out

Exceptions

SSH2CHANNEL-REQUESTX11FORWARDING-ERROR	invalid stream ID; libssh2 reported an error on the channel while waiting for data from the server
SSH2CHANNEL-ERROR	the channel has been closed
SSH2CHANNEL-TIMEOUT	timeout communicating on channel
SSH2-ERROR	socket error sending data; timeout on socket; invalid SSH2 protocol response; server returned an error message

◆ sendEof()

nothing Qore::SSH2::SSH2Channel::sendEof ( timeout timeout = -1 )

Informs the remote end that we are closing the connection.

Example:: chan.sendEof(30s);

Parameters

timeout an integer giving a timeout in milliseconds or a relative date/time value (ex: 15s for 15 seconds); a negative value means do not time out

Exceptions

SSH2CHANNEL-SENDEOF-ERROR	server returned an error while waiting for a response
SSH2CHANNEL-ERROR	the channel has been closed
SSH2CHANNEL-TIMEOUT	timeout communicating on channel
SSH2-ERROR	socket error sending data; timeout on socket; invalid SSH2 protocol response; server returned an error message

◆ setEncoding()

nothing Qore::SSH2::SSH2Channel::setEncoding ( string encoding )

Sets the default string encoding for the channel; all string data read from the channel will be tagged with the encoding given.

Example:: chan.setEncoding("utf8");

Parameters

encoding the string encoding to set for the channel

◆ setenv()

nothing Qore::SSH2::SSH2Channel::setenv	(	string	var,
		string	value,
		timeout	timeout = `-1`
	)

Sets an environment variable on the channel.

Example:: chan.setenv("", "", 30s);

Parameters

var	the environment variable to set
value	the value to set
timeout	an integer giving a timeout in milliseconds or a relative date/time value (ex: `15s` for 15 seconds); a negative value means do not time out

Exceptions

SSH2CHANNEL-SETENV-ERROR	libssh2 reported an error on the channel
SSH2CHANNEL-ERROR	the channel has been closed
SSH2CHANNEL-TIMEOUT	timeout communicating on channel
SSH2-ERROR	socket error sending data; timeout on socket; invalid SSH2 protocol response; server returned an error message

◆ shell()

nothing Qore::SSH2::SSH2Channel::shell ( timeout timeout = -1 )

Request a login shell to be started for the channel.

Example:: chan.shell(30s);

Parameters

timeout an integer giving a timeout in milliseconds or a relative date/time value (ex: 15s for 15 seconds); a negative value means do not time out

Exceptions

SSH2CHANNEL-SHELL-ERROR	server returned an error while waiting for a response
SSH2CHANNEL-ERROR	the channel has been closed
SSH2CHANNEL-TIMEOUT	timeout communicating on channel
SSH2-ERROR	socket error sending data; timeout on socket; invalid SSH2 protocol response; server returned an error message

◆ subsystem()

nothing Qore::SSH2::SSH2Channel::subsystem	(	string	command,
		timeout	timeout = `-1`
	)

Executes a command on the channel as a subsystem.

Example:: chan.subsystem("ls -l", 30s);

use SSH2Channel::read() to read the output

Parameters

command	the command to run as a subsystem
timeout	an integer giving a timeout in milliseconds or a relative date/time value (ex: `15s` for 15 seconds); a negative value means do not time out

Exceptions

SSH2CHANNEL-SUBSYSTEM-ERROR	libssh2 reported an error on the channel while waiting for confirmation from the server
SSH2CHANNEL-ERROR	the channel has been closed
SSH2CHANNEL-TIMEOUT	timeout communicating on channel
SSH2-ERROR	socket error sending data; timeout on socket; invalid SSH2 protocol response; server returned an error message

◆ waitClosed()

nothing Qore::SSH2::SSH2Channel::waitClosed ( timeout timeout = -1 )

Wait for the remote end to acknowledge the close request.

Example:: chan.waitClosed(30s);

Parameters

timeout an integer giving a timeout in milliseconds or a relative date/time value (ex: 15s for 15 seconds); a negative value means do not time out

Exceptions

SSH2CHANNEL-WAITCLOSED-ERROR	server returned an error while waiting for a response
SSH2CHANNEL-ERROR	the channel has been closed
SSH2CHANNEL-TIMEOUT	timeout communicating on channel
SSH2-ERROR	socket error sending data; timeout on socket; invalid SSH2 protocol response; server returned an error message

◆ waitEof()

nothing Qore::SSH2::SSH2Channel::waitEof ( timeout timeout = -1 )

Wait for the remote end to acknowledge an EOF request.

Example:: chan.waitEof(30s);

Parameters

timeout an integer giving a timeout in milliseconds or a relative date/time value (ex: 15s for 15 seconds); a negative value means do not time out

Exceptions

SSH2CHANNEL-WAITEOF-ERROR	server returned an error while waiting for a response
SSH2CHANNEL-ERROR	the channel has been closed
SSH2CHANNEL-TIMEOUT	timeout communicating on channel
SSH2-ERROR	socket error sending data; timeout on socket; invalid SSH2 protocol response; server returned an error message

◆ write()

nothing Qore::SSH2::SSH2Channel::write	(	data	data,
		softint	stream_id = `0`,
		timeout	timeout_ms = `-1`
	)

Writes data to a stream.

Example:: chan.write(data, 0, 30s);

Parameters

data	the data to write; must be either a string or binary
stream_id	the stream ID to write (0 is the default, 1 is for `stderr`)
timeout	an integer giving a timeout in milliseconds or a relative date/time value (ex: `15s` for 15 seconds); a negative value means do not time out

Exceptions

SSH2CHANNEL-WRITE-ERROR	invalid stream ID; libssh2 reported an error on the channel while waiting for a response from the server
SSH2CHANNEL-ERROR	the channel has been closed
SSH2CHANNEL-TIMEOUT	timeout communicating on channel
SSH2-ERROR	socket error sending data; timeout on socket; invalid SSH2 protocol response; server returned an error message

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

QC_SSH2Channel.dox.h

Public Member Methods

Detailed Description

Member Function Documentation

◆ close()

◆ constructor()

◆ copy()

◆ eof()

◆ exec()

◆ extendedDataIgnore()

◆ extendedDataMerge()

◆ extendedDataNormal()

◆ getEncoding()

◆ getExitStatus()

◆ read()

◆ readBinary()

◆ readBinaryBlock()

◆ readBlock()

◆ requestPty()

◆ requestX11Forwarding()

◆ sendEof()

◆ setEncoding()

◆ setenv()

◆ shell()

◆ subsystem()

◆ waitClosed()

◆ waitEof()

◆ write()