Methods
Ssh.NewCreates a new SSH instance.
Syntax
Ssh.New()
:ConnectAttempts to connect using the specified host address, port, and credentials.
Syntax
:Connect("host", port, "user", "password")
Arguments
host : String. The IP Address or FQDN (fully qualified domain name) which represents the remote host.
port : Integer, 0 - 65535. The connection port number on the remote host.
user : String. The connection user name, in quotes.
password : String. The connection password, in quotes.
:DisconnectDisconnects the socket.
Syntax
:Disconnect()
:WriteWrites specified data to the socket. Raises error if socket is not connected.
Syntax
:Write(data)
Arguments
data : String. The data to write to the socket.
:ReadAttempts to read up to 'length' bytes from socket. These bytes are removed from the buffer, leaving any remaining bytes beyond the 'length' specified.
Syntax
:Read(length)
Arguments
length : Positive integer. The number of bytes of data to read from the socket buffer.
Return Value
Returns a string containing the number of bytes requested or the number of bytes available, whichever comes first. Returns Nil if the buffer is empty.
:ReadLineAttempts to read a 'line' from the socket buffer.
Syntax
:ReadLine(TcpSocket.EOL.keyword, <custom>)
Arguments
TcpSocket.EOL.keyword : The EOL keyword can be any of the types shown in the EOL table below.
custom : Used only if the EOL keyword is Custom. A string literal containing the custom end of line character combination to search for.
|
TcpSocket.EOL Keywords |
Description |
|---|---|
|
Any |
The end of line is any sequence of any number of carriage return and/or linefeed characters. This is the appropriate choice if the protocol uses simply a carriage return as the end of message. |
|
CrLf |
The end of the line is an optional carriage return, followed by a linefeed. (In other words, it is either a "\r\n" or a "\n".) This format is useful in parsing text-based Internet protocols, since the standards generally prescribe a "\r\n" line-terminator, but nonconformant clients sometimes use just "\n". |
|
CrLfStrict |
The end of a line is a single carriage return, followed by a single linefeed. (This is also known as "\r\n". The ASCII values are 0x0D 0x0A). |
|
Lf |
The end of a line is a single linefeed character. (This is also known as "\n". It is ASCII value is 0x0A.) |
|
Null |
The end of line is a single byte with the value 0 — an ASCII NUL. |
|
Custom |
The end of line is defined by the string passed into the ReadLine() method. |
Return Value
Nil if the EOL was not found, otherwise returns the string up to the EOL sequence.
:Search
Searches the socket buffer for string 'str' (starting at integer 'start_pos') and returns the index of where 'str' is found. 'start_pos' defaults to 1.
Syntax
:Search(str, [start_pos])
Arguments
str : The string to search for.
start_pos : Integer. Optional. The index of where to start in the socket buffer. Default is index 1.
Return Value
Nil if the search string was not found, otherwise returns the integer index of where the search string was found.
Event Handlers
|
Name |
Function Signature |
Description |
|---|---|---|
|
.LoginFailed |
function( tcpTable ) |
Assign a function which is called upon a failed login. |
|
.Connected |
function( tcpTable ) |
Assign a function which is called upon connection to remote host |
|
.Reconnect |
function( tcpTable ) |
Assign a function which is called when socket is attempting to reconnect to the remote host |
|
.Data |
function( tcpTable, data ) |
Assign a function which is called when there is new data available in the socket buffer |
|
.Closed |
function( tcpTable ) |
Assign a function which is called when the socket is closed by the remote host |
|
.Error |
function( tcpTable, err ) |
Assign a function which is called when the socket is closed due to error. The error argument in the function will contain more information, which can be displayed if a variable was created to catch the error message. |
|
.Timeout |
function( tcpTable, err) |
Assign a function which is called when a read or write timeout is triggered and the socket was closed. |
Events
|
Name |
Description |
|---|---|
|
Connected |
The socket has connected to the remote host. |
|
Reconnect |
The socket is attempting to reconnect to the remote host |
|
Data |
There is new data available in the socket buffer |
|
Closed |
The socket was closed by the remote host |
|
Error |
The socket was closed due to error. The error argument to the EventHandler will have more information, which can be displayed if a variable was created to catch the error message. |
|
Timeout |
A read or write timeout was triggered and the socket was closed. |
Properties
|
Name |
Notes |
Description |
|---|---|---|
|
.ReadTimeout |
Optional; Default is 0 ( disabled ) |
Time, in seconds, to wait for data to be available on socket before raising an error. |
|
.WriteTimeout |
Optional; Default is 0 ( disabled ) |
Time, in seconds, to wait for data write to complete before raising an error. |
|
.ReconnectTimeout |
Optional; Default is 5 seconds |
Time in seconds to wait before attempting to reconnect. 0 disables automatic reconnect. |
|
.IsConnected |
Read-Only |
Returns true if socket is connected. |
|
.BufferLength |
Read-Only |
Amount of data in buffer, in bytes. |
Example
In this example script, a new SSH connection is created. Multiple event handlers are included to print connection status. Upon connection:
- The date is written.
- Data from the socket buffer is read and printed.
- The buffer length is printed.
ssh = Ssh.New()
address = "192.0.2.199"
port = 22
user = "myusername"
pass = "mypassword"
timer = Timer.New()
timer.EventHandler = function()
ssh:Write("date\n")
end
ssh.Connected = function()
print("ssh connected")
timer:Start(10)
end
ssh.Reconnect = function()
print("ssh reconnect")
end
ssh.Data = function()
print("ssh data")
line = ssh:ReadLine(TcpSocket.EOL.Any)
while line do
print(line)
print(ssh.BufferLength)
line = ssh:ReadLine(TcpSocket.EOL.Any)
end
end
ssh.Closed = function()
print("ssh closed")
timer:Stop()
end
ssh.Error = function(s, err)
print("ssh error", err)
end
ssh.Timeout = function()
print("ssh timeout")
end
ssh.LoginFailed = function()
print("ssh LoginFailed")
end
ssh:Connect(address, port, user, pass)
