alice
library
manual.

Alice Project

The Socket structure


________ Synopsis ____________________________________________________

    signature SOCKET
    structure Socket : SOCKET

This structure provides a simplified interface for creating INET socket based client/server applications. This interface is expected to change in a later release. Note that this structure is incompatible with the Socket structure defined by the Standard Basis Library.


________ Import ______________________________________________________

    import signature SOCKET from "x-alice:/lib/system/SOCKET-sig"
    import structure Socket from "x-alice:/lib/system/Socket"

________ Interface ___________________________________________________

    signature SOCKET =
    sig
	type socket
	type t = socket
	type vector = string
	type elem = char

	type host = string
	type port = int

	val server : port option * (socket * host * port -> unit) -> socket * port
	val client : host * port -> socket

	val input1 : socket -> char option
	val inputN : socket * int -> vector
	val inputLine : socket -> vector option
	val output : socket * vector -> unit
	val output1 : socket * char -> unit

	val close : socket -> unit
    end

________ Description _________________________________________________

type socket
type t = socket

The type of sockets.

type vector = string
type elem = char

The types of vectors and elements used for communication over sockets.

type host = string
type port = int

The types of host names and port numbers used for establishing socket connections.

server (portOpt, acceptor)

starts a server listening for connections. If portOpt is SOME port, makes the server listen on port if available, if it is NONE, selects a free port. Returns the socket with which one can close down the server and the actual port on which it listens. Raises IO.Io if a port was specified but was unavailable.

For every client that connects to the server,

acceptor (sock, host, port)

is invoked, where sock, host and port are the socket with which to speak to the client, the client's host name and the port number on which the client connected, respectively. The next connection is accepted only once acceptor returns.

client (host, port)

establishes a connection to a server listening on host on port. Raises IO.Io if no connection could be established. Returns the socket with which the client can speak to the server.

input1 sock

receives a single character from sock. If the socket was closed by the other end, returns NONE, else returns SOME c where c is the character received. Raises IO.Io if receiving failed.

inputN (sock, n)

receives at most n characters from sock. If the returned string is shorter than n characters, then this indicates that the socket was closed by the other end. Raises IO.Io if receiving failed.

inputLine sock

receives characters from sock until the next newline character (#"\n") and returns them, including the newline character. If NONE is returned, then this indicates that the socket was closed by the other end. The last line is always terminated by a newline character, even if it did not end in one. Raises IO.Io if receiving failed.

output (sock, s)

sends s to sock. Raises IO.Io if sending failed.

output1 (sock, c)

sends c to sock. Raises IO.Io if sending failed.

close sock

closes sock. If sock was returned by server, shuts down the server, else closes an active connection.



last modified 2007/Mar/30 17:10