ExtronLib-CDS/extronlib/interface/EthernetClientInterface.py
2021-09-21 10:27:39 -05:00

123 lines
5.4 KiB
Python
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

class EthernetClientInterface():
""" This class provides an interface to a client ethernet socket. This class allows the user to send data over the ethernet port in a synchronous or asynchronous manner.
Note: In synchronous mode, the user will use SendAndWait to wait for the response. In asynchronous mode, the user will assign a handler function to ReceiveData event handler. Then responses and unsolicited messages will be sent to the users receive data handler.
Arguments:
- Hostname (string) - DNS Name of the connection. Can be IP Address
- IPPort (int) - IP port number of the connection
- (optional) Protocol (string) - Value for either 'TCP', 'UDP', or 'SSH'
- (optional) ServicePort (int) - Sets the port on which to listen for response data, UDP only, zero means listen on port OS assigns
- (optional) Credentials (tuple) - Username and password for SSH connection.
Parameters:
- Credentials - Returns (tuple, bool) - Username and password for SSH connection.
- Note:
- returns tuple: ('username', 'password') if provided otherwise None.
- only applies when protocol 'SSH' is used.
- Hostname - Returns (string) - server Host name
- IPAddress - Returns (string) - server IP Address
- IPPort - Returns (int) - IP port number of the connection
- Protocol - Returns (string) - Value for either TCP, UDP, 'SSH' connection.
- ServicePort - Returns (int) - the port on which the socket is listening for response data
Events:
- Connected - (Event) Triggers when socket connection is established.
- Disconnected - (Event) Triggers when the socket connection is broken
- ReceiveData - (Event) Receive Data event handler used for asynchronous transactions. The callback takes two arguments. The first one is the EthernetClientInterface instance triggering the event and the second one is a bytes string.
- Note:
- The maximum amount of data per ReceiveData event that will be passed into the handler is 1024 bytes. For payloads greater than 1024 bytes, multiple events will be triggered.
- When UDP protocol is used, the data will be truncated to 1024 bytes.
"""
Hostname = ''
IPAddress = ''
IPPort = 0
Protocol = ''
ServicePort = 0
Credentials = None
Connected = None
Disconnected = None
ReceiveData = None
def __init__(self, Hostname, IPPort, Protocol='TCP', ServicePort=0, Credentials=None):
""" EthernetClientInterface class constructor.
Arguments:
- Hostname (string) - DNS Name of the connection. Can be IP Address
- IPPort (int) - IP port number of the connection
- (optional) Protocol (string) - Value for either 'TCP', 'UDP', or 'SSH'
- (optional) ServicePort (int) - Sets the port on which to listen for response data, UDP only, zero means listen on port OS assigns
- (optional) Credentials (tuple) - Username and password for SSH connection.
"""
self.Hostname = Hostname
self.IPPort = IPPort
self.Protocol = Protocol
self.ServicePort = ServicePort
self.Credentials = Credentials
def Connect(self, timeout=None):
""" Connect to the server
Arguments:
- (optional) timeout (float) - time in seconds to attempt connection before giving up.
Returns
- 'Connected' or 'ConnectedAlready' or reason for failure (string)
Note: Does not apply to UDP connections.
"""
pass
def Disconnect(self):
""" Disconnect the socket
Note: Does not apply to UDP connections.
"""
pass
def Send(self, data):
""" Send string over ethernet port if its open
Arguments:
- data (bytes, string) - string to send out
Raises:
- TypeError
- IOError
"""
pass
def SendAndWait(self, data, timeout, delimiter):
""" Send data to the controlled device and wait (blocking) for response. It returns after timeout seconds expires or immediately if the optional condition is satisfied.
Note: In addition to data and timeout, the method accepts an optional delimiter, which is used to compare against the received response. It supports any one of the following conditions:
- > deliLen (int) - length of the response
- > deliTag (bytes) - suffix of the response
- > deliRex (regular expression object) - regular expression
Note: The function will return an empty byte array if timeout expires and nothing is received, or the condition (if provided) is not met.
Arguments:
- data (bytes, string) - data to send.
- timeout (float) - amount of time to wait for response.
- delimiter (see above) - optional conditions to look for in response.
Returns:
- Response received data (may be empty) (bytes)
"""
pass
def StartKeepAlive(self, interval, data):
""" Repeatedly sends data at the given interval
Arguments:
- interval (float) - Time in seconds between transmissions
- data (bytes, string) - data bytes to send
"""
pass
def StopKeepAlive(self):
""" Stop the currently running keep alive routine
"""
pass