_{Official ZPE/YASS documentation}Socket

Introduction

The Socket object provides basic TCP socket support in ZPE.

It can operate in two modes:

• Client mode using connect to connect to an existing server.
• Server mode using open to listen on a port and execute a function whenever a line of text is received.

Internally, this object wraps Java's Socket and ServerSocket APIs and uses a line-based protocol for input/output.

All functions exposed by this object require a permission level of 4.

Socket object functions

The following is a list of internal functions the Socket object exposes. All functions are ZPEObjectNativeFunctions therefore run in native code.

connect(string hostname, number port) ⇒ boolean

Connects to a TCP server at the specified hostname and port. Returns true if the connection is successfully established, otherwise false.

open(number port, function function) ⇒ boolean

Opens a TCP server socket on the given port and blocks while waiting for a client to connect. Once connected, it reads incoming data line-by-line and executes the provided function for each received line. Returns true if the server ran successfully, otherwise false.

write(string message) ⇒ boolean

Writes a line of text to the connected socket and flushes the output stream. A newline character is appended automatically. Returns true.

Examples

Connecting to a server and sending a message:

$s = new Socket()

if ($s->connect("localhost", 9000))
    $s->write("Hello from ZPE")
else
    print("Could not connect.")
end

Opening a simple server and handling each incoming line using a callback function:

function onMessage($line)
    print("Received: " + $line)
end

$server = new Socket()
$server->open(9000, onMessage)

Notes:

• Line-based: Incoming data is processed using readLine(), therefore each message should be newline-terminated.
• Blocking behaviour: open() blocks while waiting for a client and while reading messages.
• Callback parameter: The callback function supplied to open() should accept one parameter, which receives the incoming line.
• Permissions: Socket operations require permission level 4.