π Introduction
Hi everyone, in this topic i'll introduce you to my extension:Server Socket Pro
With it you can create a TCP server (using Java's ServerSocket class) that will be accessible to the devices on the same network to transfer data and files.
If you have the server already and you're in need of a client, get a look at my Client Socket Pro extension
β Main features
Here you can find a list containing the main features of the extension, explaining even what's different from other extensions that offer similar featuresMulti-threaded connections management
The extension is designed to manage multiple connections (clients) at the same time, providing ways to communicate with a specific device, a group or all the devices connected
Multiple charsets supported
You can select the charset to use for communications according to your needs, allowing you to adapt the extension to your needs
βFiles transfer
Unlike other similar extensions, where only text data is supported, you can easily and quickly receive files from the clients and save them in a directory of your choice and, if needed, with a customized name (requires using my Client Socket Pro extension since it uses a custom protocol)
βAdvanced error handling
The extension comes with an advanced errors management and handling system, that will catch most of the errors and avoid crashes, returning a severity level to filter the errors more easily, an error tag to quickly identify the error's category and the error message
π Blocks and documentation
Overview
Events
Show/hide events
Error occurred
Fired when an error occurs
Parameters:
severity
| Integer rapresenting the severity level of the error, the highest the more severe [1-3]tag
| Short string useful to quickly identify the type of error (get a look at the Error tags section in this post)message
| Error message returned by the app
Started
Fired when the server is started
Stopped
Fired when the server is stopped
Client Connected
Fired when a client connects
Parameters:
address
| String containing the connected device's address
Client Disconnected
Fired when a client disconencts
Parameters:
address
| String containing the disconnected device's address
Message Received
Fired when the server receives a message from a client
Parameters:
address
| String containing the source device's addressmessage
| String containing the message
Message Sent
Fired when the server has sent a message to a client
Parameters:
destination
| String containing the destination device's addressmessage
| String containing the message
File Received
Fired when the server receives a file from a client, note that this uses a custom protocol and requires the use of my Server Socket Pro extension (check the Protocol section in this post)
Parameters:
address
| String containing the source device's addresspath
| String containing the full path where the file has been saved
File Receive Progress
Fired everytime there's an update in the file's download from a client, note that this uses a custom protocol and requires the use of my Server Socket Pro extension (check the Protocol section in this post)
Parameters:
address
| String containing the source device's addressfileName
| String containing the file name (with extension)received
| Long (number) indicating the amount of bytes receivedtotal
| Long (number) indicating the total size of the filepercentComplete
| Double (number) containing the current transfer completion percentage
Ping Result
Fired after a ping has been executed
Parameters:
address
| String containing the pinged device's addressconnected
| Boolean containing the ping result (true = connected)
Methods
Show/hide methods
Start
Starts the server on the specified port
Parameters:
port
| Integer containing the port number [0-65535]
Stop
Stops the server
Write
Writes a message to all the clients, if ln = false sending not guaranteed since the EOL character is not sent
Parameters:
message
| String containing the messageln
| Boolean indicating whether the EOL character should be sent at the end of the message
Write To
Writes a message to a specific client, if ln = false sending not guaranteed since the EOL character is not sent
Parameters:
address
| String containing the destination addressmessage
| String containing the messageln
| Boolean indicating whether the EOL character should be sent at the end of the message
Write To List
Writes a message to a list of specific clients, if ln = false sending not guaranteed since the EOL character is not sent
Parameters:
addresses
| List of strings containing the destination addresssesmessage
| String containing the messageln
| Boolean indicating whether the EOL character should be sent at the end of the message
Ping
Pings a specific client to test connection by sending the Ping Character (defined in properties), for more details check the Protocol section in this post
Parameters:
address
| String containing the address of the device to ping
Disconnect Client
Disconnects the specified client
Parameters:
address
| String containing the address of the device to disconnect
Is Running
Retrieves the server's status
Returns:
boolean
| true if the server is currently running, false otherwise
Get Address
Retrieves the server's address
Returns:
string
| the server IP address that can be used by clients to connect
Get Clients
Retrieves all connected clients' info
Returns:
dictionary
| containing the addresses and info of connected clients (ip : data), data is a dictionary containing the hostname, canonical hostname and the ip address of the device
Get Client
Retrieves the specified device's info
Parameters:
address
| String containing the address of the clientReturns:
dictionary
| dictionary containing the hostname, canonical hostname and the ip address of the device
Is Client Connected
Retrieves the server's status
Parameters:
address
| String containing the address of the clientReturns:
boolean
| true if the client with the given address is connected. Note that this differs from ping because it only checks if the device disconnected in a graceful way, so doesn't work in limit cases or when, for example, it crashed. For that use the Ping method, that actively checks if a device is connected and responsive
Is Ip Valid
Utility function to check if the provided address is a valid IP
Parameters:
address
| String containing the address to checkReturns:
boolean
| true if the provided string is a valid IP address
Properties
Show/hide properties
Socket Timeout
Timeout (in milliseconds) for IO operations and connection
Default: 0, disabled
Ping Timeout
Maximum time (in milliseconds) the server will wait for pingback signal to be sent
Default: 5000 (ms)
Ping Char
Character to be sent for ping execution and protocol messages (check the Protocol section in this post). The character is defined using an integer, which is the decimal ASCII rapresentation of it
Default: 6 (ACK character)
Files Directory
Directory path where received files are saved, if one or more folders don't exist, they'll be created (if possible). Also get a look at https://community.appinventor.mit.edu/t/some-basics-on-android-storage-system/21556 to prevent errors
Default: "" (empty) [files saved in "/storage/emulated/0/gotFiles"]
File Name
Full name to use for received files, if empty gets the name automatically from the client
Default: "" (empty) [got from client]
Line Delimiter
Line end delimiter (EOL)
Default: "\n"
Charset
Charset to use for data transmission
Default: "UTF_8" (check available types below)
Charset types
Charset name constants
β Error tags
As specified in the main features, this extension provides a complete and efficient errors management system, here you can find a resume of all the possible error tags with their severity and description
Show/hide errors
SERVER START
[3] START_ERROR: generic server start error (Exception)
[2] START_ERROR_ALREADY_RUNNING: tried to start server while it was running already
[3] START_ERROR_BIND: if the server socket cannot bind to the specified port. For instance, if the port is already in use by another application (BindException)
[3] START_ERROR_INTERRUPT: if the thread is interrupted while blocked in an I/O operation (ClosedByInterruptException)
[3] START_ERROR_CLOSED_CHANNEL: if the channel or socket is closed while an I/O operation is in progress (ClosedChannelException)
[3] START_ERROR_NO_ROUTE: if the socket cannot connect due to a missing route to the host, potentially caused by network issues (NoRouteToHostException)
[3] START_ERROR_SOCKET: socket error (SocketException)
[3] START_ERROR_IO: error while creating the ServerSocket or while accepting connection (IOException)
[3] START_ERROR_SECURITY: a security manager denies access to create a socket on the given port (SecurityException)
[3] START_ERROR_INVALID_PORT: port number must be between 0 and 65535
[3] START_ERROR_TIMEOUT: socket timeout (SocketTimeoutException)
SERVER STOP
[3] STOP_ERROR: generic error occurred while stopping (Exception)
[3] STOP_ERROR_IO: unable to disconnect due to IO issues (IOException)
OPERATIONS
[1/2] ERROR_NOT_RUNNING: tried to perform an operation while server wasn't running
[3] WRITE_ERROR: error while writing to client socket(s) (Exception)
[2] WRITE_CLIENT_NOT_FOUND: the specified client is not connected, message can't be sent
[3] PINGBACK_ERROR_UNAVAILABLE: Socket output stream unavailable, fired while replying to client's ping
[3] PINGBACK_ERROR: error while writing to output stream, fired while replying to client's ping (Exception)
[3] PING_ERROR: error while performing connection test (Exception)
[2] PING_CLIENT_NOT_FOUND: the specified client is not connected
[1] PING_ERROR_ALREADY_WAITING: tried performing a ping on a client while another was pending on the same client
[3] CLIENT_READ_ERROR_IO: IO error while reading data from client (IOException)
[3] CLIENT_READ_ERROR_NULL: error while reading data from client due to the socket or reader being null (NullPointerException)
[3] CLIENT_READ_ERROR_: generic error while reading data from client (Exception)
[3] CLIENT_FILE_ERROR_IO: IO error while reading file data from client (IOException)
[3] CLIENT_FILE_ERROR: generic error while reading file data from client (Exception)
[3] CLIENT_FILE_NOT_CREATED: error while creating files folder/file
PROPERTIES
[2] INVALID_PROPERTY: invalid property value provided
[2] CHARSET_ILLEGAL: illegal charset name provided (IllegalCharsetNameException)
[2] CHARSET_INVALID: provided charset is not valid, might be null, empty or not supported by the current device (IllegalArgumentException)
[2] CHARSET_ERROR: generic charset error (Exception)
[2] PROPERTY_BLOCK: tried to change a property while server was running
[3] ERROR_IP_ADDRESS: unable to retrieve device's IP address
CLIENTS
[3] CLIENT_DISCONNECT_ERROR_IO: IO error while trying to close connection with client (IOException)
[3] CLIENT_DISCONNECT_ERROR: generic error occurred while closing connection with client(Exception)
[3] CLIENT_DISCONNECTED: client closed connection not properly (e.g. crash, network issue) and is no longer connected
[2] DISCONNECT_CLIENT_NOT_FOUND: the specified client is not connected, can't be disconnected
[3] CLIENT_ERROR_IO: IO error while setting up client socket
[3] CLIENT_ERROR: generic error while setting up client socket
[2] GET_CLIENT_NOT_FOUND: the specified client is not connected, cannot get info
[3] ERROR_GET_CLIENTS: error while getting clients details (Exception)
π Protocol
The extension implements a custom protocol to ping devices and perform file transfers, here's an explaination of how it works, to avoid conflicts with custom logics or external extensions. On the base of the protocol there's the "Ping Char" which, by default, if the ACK character (dec 6 in ASCII table). This character is used how it follows:Show/hide protocol description
-
PING REQUEST,
Sent 1 time from server to client to request a pingback, happens when the Ping method is executed -
PINGBACK
Sent 2 times from the client to the server in response to a ping request -
FILE TRANSFER START
Sent 3 times from the client to the server to denote that a file transfer is going to happen, right after it the client sends files info to the server (e.g. file name, size...) and then waits for the file transfer ready signal from the server before starting to send the actual file -
FILE TRANSFER READY
Sent 3 times from the server to the client after it has received from the client the file's info, denotes that the server is ready to read the file's bytes and that the actual transfer can start
πΈ Pricing and download
In the initial phase the extension will be paid, but i plan on making it free after a while, if i see that many people are interested in it and supported me for my workπMinimum donation: $15.00 (you can donate more if you appreciate my work!)
Includes: ServerSocketPro extension (.aix file, version 1.0, 2024-03-12T23:00:00Z)
License : license.pdf (51.1 KB)
Please contact me in DM before buying
Payment methods:
PayPal
Revolut
If you plan on buying my "Client Socket Pro" extension as well, contact me to receive a bundle offer and save something!
Thanks to @shreyash and his tool Rush that i used to build the extension! (looking forward to helper blocks implementation )