s48-refman/library/socket.texi

@node TCP & UDP sockets
@section TCP & UDP sockets

@cindex networking
@stindex sockets
@stindex udp-sockets
Scheme48 provides a simple facility for TCP & UDP sockets.  Both the
structures @code{sockets} and @code{udp-sockets} export several general
socket-related procedures:

@deffn procedure close-socket socket @returns{} unspecified
@deffnx procedure socket-port-number socket @returns{} integer
@deffnx procedure get-host-name @returns{} string
@code{Close-socket} closes @var{socket}, which may be any type of
socket.  @code{Socket-port-number} returns the port number through
which @var{socket} is communicating.  @code{Get-host-name} returns the
network name of the current machine.

@strong{Note:} Programmers should be wary of storing the result of a
call to @code{get-host-name} in a dumped heap image, because the actual
machine's host name may vary from invocation to invocation of the
Scheme48 VM on that image, since heap images may be resumed on multiple
different machines.
@end deffn

@subsection TCP sockets

@stindex sockets
The @code{sockets} structure provides simple TCP socket facilities.

@deffn procedure open-socket [port-number] @returns{} socket
@deffnx procedure socket-accept socket @returns{} [input-port output-port]
The server interface.  @code{Open-socket} creates a socket that listens
on @var{port-number}, which defaults to a random number above 1024.
@code{Socket-accept} blocks until there is a client waiting to be
accepted, at which point it returns two values: an input port & an
output port to send & receive data to & from the client.
@end deffn

@deffn procedure socket-client host-name port-number @returns{} [input-port output-port]
Connects to the server at @var{port-number} denoted by the machine name
@var{host-name} and returns an input port and an output port for
sending & receiving data to & from the server.  @code{Socket-client}
blocks the current thread until the server accepts the connection
request.
@end deffn

@subsection UDP sockets

@stindex udp-sockets
The @code{udp-sockets} structure defines a UDP socket facility.

@deffn procedure open-udp-socket [port-number] @returns{} socket
Opens a UDP socket on @var{port-number}, or a random port number if
none was passed.  @code{Open-udp-socket} returns two values: an input
UDP socket and an output UDP socket.
@end deffn

@deffn procedure udp-send socket address buffer count @returns{} count-sent
@deffnx procedure udp-receive socket buffer @returns{} [count-received remote-address]
@code{Udp-send} attempts to send @var{count} elements from the string
or byte vector @var{buffer} from the output UDP socket @var{socket} to
the UDP address @var{address}, and returns the number of octets it
successfully sent.  @code{Udp-receive} receives a UDP message from
@var{socket}, reading it into @var{buffer} destructively.  It returns
two values: the number of octets read into @var{buffer} and the address
whence the octets came.
@end deffn

@deffn procedure lookup-udp-address name port @returns{} udp-address
@deffnx procedure udp-address? object @returns{} boolean
@deffnx procedure udp-address-address address @returns{} c-byte-vector
@deffnx procedure udp-address-port address @returns{} port-number
@deffnx procedure udp-address-hostname address @returns{} string-address
@code{Lookup-udp-address} returns a UDP address for the machine name
@var{name} at the port number @var{port}.  @code{Udp-address?} is the
disjoint type predicate for UDP addresses.  @code{Udp-address-address}
returns a byte vector that contains the C representation of
@var{address}, suitable for passing to C with Scheme48's C FFI.
@code{Udp-address-port} returns the port number of @var{address}.
@code{Udp-address-hostname} returns a string representation of the IP
address of @var{address}.
@end deffn