EasySocket is a simple, high-level interface to the RISC OS Socket handling SWIs. It provides an abstraction layer that allows applications to perform network operations without dealing with the complexities of the underlying TCP/IP stack directly.

The module manages two primary types of objects: sockets and monitors. Sockets represent network connections or listening points, while monitors provide a mechanism for multitasking applications to wait for events on those sockets using pollwords.

The module is designed to be easy to use from high-level languages like BBC BASIC, providing string-oriented operations like and alongside raw data transfers.

The module maintains an internal list of active socket handles. Each handle is a pointer to a workspace block containing the socket's state, buffers, and metadata. Handles are validated using a magic number (&hex;FEEF1EF0).

A socket can be in one of several states, which can be queried via :

Looking up address Connecting to host Listening for connection Connected Host lookup failed (doesn't exist?) Resolve failed (no response) Resolver error (not running?) No sockets left Host is unreachable (network down?) Connection refused (not listening at destination) Could not bind to local port Nobody connected to socket

All socket operations are performed in non-blocking mode. Connection establishment and DNS resolution (via the Resolver module) occur asynchronously. Applications should poll to track progress.

Monitors allow Wimp applications to use 6. The module updates a monitor's pollword when data arrives on the associated socket, when the connection is closed, or when keyboard activity is detected (via or Wimp filters).

Pointer to null-terminated hostname or IP literal in [brackets]

Port number

ESocket handle, or negative error code

This SWI initiates a connection to the specified host. The process begins with an asynchronous DNS lookup if necessary.

ESocket handle

Connection state (1-4 or negative error)

Returns the current state of the connection. This SWI also triggers internal background processing for all active sockets.

ESocket or Monitor handle

Closes the network connection and frees all associated memory. If a monitor handle is passed, the monitor is destroyed.

ESocket handle

Pointer to string

Flags: Do not send CR Do not send LF String is terminated by character 13 (otherwise 0)

Sends a string to the remote host, optionally appending CR and/or LF.

ESocket handle

Pointer to buffer

Size of buffer

Flags: Terminator type: 0: CRLF 1: LF 2: CR 3: Any Terminate output with character 13 (otherwise 0) Process delete/backspace characters

Pointer to buffer, or 0 if no line available or buffer too small

Length of line read, or size required if R1=0 on exit

Reads a line of text from the internal buffer. If a complete line is not available, it returns 0 in R1.

ESocket handle

Pointer to data

Length of data

Bytes actually sent

Sends raw binary data to the remote host.

ESocket handle

Pointer to buffer (or 0 to query)

Size of buffer

Bytes read, or bytes available if R1 was 0 on entry

Reads raw binary data from the socket. If R1 is 0, it returns the total number of bytes available to read immediately.

ESocket handle

Flags: Ignore internal buffer (check socket directly)

1 if closed, 0 otherwise

Checks whether the connection has been closed by the remote host.

Local port number, or 0 to allocate

ESocket handle, or negative error code

Allocated port number (if R0 was 0 on entry)

Creates a listening socket on the specified port.

ESocket handle of listening socket

Flags: Close the listening socket after accepting

New ESocket handle for the connection, or -8 if no connection is waiting

Accepts a connection waiting on a listening socket.

ESocket handle

Pointer to null-terminated hostname or IP string

Returns the name or IP address of the remote host associated with the socket.

Type (must be 0)

ESocket handle

Monitor handle

Creates a monitor object that can be used to poll for activity on a socket.

Monitor handle

Address of custom pollword (not currently supported, must be 0)

Pointer to the monitor's pollword

Resets the monitor's pollword to 0 and returns its address.

ESocket handle

Local IP address

Local port number

Returns the local IP address and port number for the socket.

State number

Pointer to descriptive string

Converts a numeric connection state or error code into a human-readable string.

ESocket or Monitor handle

1 to associate, 0 to dissociate

Manually changes the task association of a socket or monitor. Associated objects are automatically closed when the task terminates.

Remote IP address

Remote port number

ESocket handle, or negative error code

Initiates a connection to a specific remote IP address and port.

ESocket handle

Remote IP address

Remote port number

Returns the remote IP address and port number for the socket.

Displays a list of all active EasySocket handles, their remote addresses, ports, and current states.

Displays a list of all active monitors, including their pollword addresses and traffic statistics.