PSIONICS FILE - TCPIP
=====================
Interface to TCP/IP
Last modified 1998-02-23
========================
The TCP/IP stack for the Psion 3 series is shipped as a separate product
called PsiMail; it comes with various utilities. This file describes the
programming interface to this stack. It assumes knowledge of the Unix
Berkeley Sockets interface, and terms not defined here have the same meaning
as there.
General conventions
-------------------
Most network functions are carried out by sending messages to objects. There
are two objects - the IP object and the DNS object.
Messages are sent to the objects with SEND. This takes from 2 to 5
arguments: the object handle, the message type number, and 0 to 2 additional
items. These items are called V1, V2, and V3 in this file, and are described
in OPL terms as an object. Thus, for example, given:
Message 99 - Activate or deactivate network
V1: 10 byte buffer described below
V2: a word holding the value 8
Returns: zero for success, non-zero for failure
typical code to make the call would be:
LOCAL bufx%,bufy&,bufz&,x%
x%=8
IF SEND(ipobj%, 99, bufx%, x%)<>0
ALERT("Can't activate network")
ENDIF
and the variables bufx%, bufy&, and bufz& form the buffer.
Where a constant is given, exactly that value must be used. Where bits are
not mentioned in a value, they must be set to zero and ignored when read.
Network addresses are 16 bytes long, and have the following format:
Offset 0 (word): must be 2
Offset 2 (word): port number, in network order
Offset 4 (long): IP address, in network order
Offset 8 to 15: unused
Note that the address and port numbers are in network order (most
significant byte in the lowest offset).
Accessing the interface
-----------------------
The interface is provided by a library called SOCKDYL.DYL. If there is a
copy in the ROM, it will be in the file ROM::SOCKDYL.DYL and can be invoked
by:
FINDLIB(tcpipch%, "SOCKDYL.DYL")
Otherwise it should be in a directory called \NET on a local drive. Programs
are recommended to look on all drives and determine the copy with the
highest version number (stored in a word at offset 24 of the file). Then
invoke the library by:
LOADLIB(tcpipch%, "file", 1)
where the second parameter is the name of the file holding the copy used.
In either case, the command will return 0 for success; tcpipch% is the
category handle for the library.
When the program has finished with the network, it should unload the library
using UNLOADLIB.
Actual access to the network is carried out through two objects - the IP
object and the DNS object. The IP object is created by:
ipobj%=NEWOBJH(tcpipch%,0)
SEND(ipobj%,25,#0,#0) : REM see below for explanation
The DNS object is created by:
dnsobj%=NEWOBJH(tcpipch%,2)
Before unloading the library, these objects should be destroyed by sending
them message 0:
SEND(ipobj%,0)
SEND(dnsobj%,0)
The IP object
-------------
The IP object provides the following messages.
Messages 2 to 24 have two additional arguments with a standard meaning: the
first is a control block of some size, whose format is given instead of the
argument descriptions, and the second is a status word. These calls can be
made synchronously or asynchronously.
To make a synchronous call, set the status word to 0 beforehand. If the
call fails, -1 is returned and the error code is in the status word.
Otherwise the call succeeded and the returned value is as described.
To make an asynchronous call, set the status word to 1 beforehand. If
the call returns -1, it failed and the error code is in the status word.
Otherwise, the status word will have been set to -46; when the operation
finishes, the status word will be changed and the semaphore signalled.
The new status word should now be passed to message 1. If the operation
failed, -1 is returned and the status word holds the error code. Otherwise
the value returned is the result of the operation.
Message 1 - interpret asynchronous result
V1: status word
See above for how to use this message.
Message 2 - create socket
The control block is 6 bytes:
Offset 0 (word): must be 2
Offset 2 (word): socket type: 1 = TCP stream, 2 = UDP datagram, 3 = raw
Offset 4 (word): must be 0
Returns: socket handle for a new socket
Creates a new socket.
Message 3 - bind socket
The control block is 6 bytes:
Offset 0 (word): socket handle
Offset 2 (word): address of a 16 byte network address block
Offset 4 (word): must be 16
Binds a socket. Within the address, IP address 0 may be used to bind to
any local interface, and port number 0 may be used to request that a port
is assigned on connection.
Message 4 - listen on socket
The control block is 4 bytes:
Offset 0 (word): socket handle
Offset 2 (word): length of the backlog queue
Starts a bound TCP socket listening for new connections.
Message 5 - accept a connection
The control block is 6 bytes:
Offset 0 (word): socket handle
Offset 2 (word): address of a 16 byte network address block
Offset 4 (word): must be 16 (may be changed by the call)
Returns: handle of new socket
Accepts a connection from a remote client, placing it on a new socket. The
original socket remains open for connections; the new socket can be used
for data transfer. The address block will be filled in with the address of
the remote client.
Message 6 - make a connection
The control block is 6 bytes:
Offset 0 (word): socket handle
Offset 2 (word): address of a 16 byte network address block
Offset 4 (word): must be 16
Connects a socket to a remote service. The address block should specify
the address of the remote service.
Message 7 - get peer name
Message 8 - get socket name
The control block is 6 bytes:
Offset 0 (word): socket handle
Offset 2 (word): address of a 16 byte network address block
Offset 4 (word): must be 16 (may be changed by the call)
Obtains the address of the remote or local end (respectively) of a socket.
The address block will be filled with the relevant address.
Message 9 - get socket option
Message 10 - set socket option
The control block is 10 bytes:
Offset 0 (word): socket handle
Offset 2 (word): must be $FFFF
Offset 4 (word): option code
Offset 6 (word): address of the area the value is taken from or put in
Offset 8 (word): size in bytes of the area (for message 9, this will be
changed to the actual size of the value)
Gets or sets an option on a socket. In the following table, "bool" means a
word that is either zero (for false or disabled) or non-zero (for true or
enabled).
Available options are:
option size meaning
$0004 bool local address can be reused
$0008 bool keep connections alive
$0010 bool don't route outgoing messages
$0020 bool broadcasting permitted
$0080 4 linger control block
$0100 bool out of band data will be received in-band
$1001 2 output buffer size
$1002 2 input buffer size
$1003 2 transmit low water mark
$1004 2 receive low water mark
$1005 2 transmit timeout
$1006 2 receive timeout
$1007 2 pending error (will clear the error) [can't be set]
$1008 2 socket type [can't be set]
The linger control block has the format:
Offset 0 (word): 0 to disable lingering, 1 to enable
Offset 2 (word): linger time in seconds
Lingering affects the behaviour of a TCP socket where data is waiting to
be sent when the socket is closed. If it is enabled, the close will wait
up to the linger time for the data to be sent. If it is disabled, the close
will return as soon as possible.
Message 11 - receive data
Message 12 - receive data
The control block is 8 bytes (message 11) or 12 bytes (message 12):
Offset 0 (word): socket handle
Offset 2 (word): address of buffer to store data in
Offset 4 (word): maximum number of bytes to receive
Offset 6 (word): flags:
Bit 0: set to process out of band data
Bit 1: if set, the data remains in the input stream and can be received
a second time
Offset 8 (word): address of a 16 byte network address block
Offset 10 (word): must be 16 (may be changed by the call)
Returns: number of bytes received
Receives data from the socket and places them in memory. Either message can
be used with any socket, but message 12 stores the sender's address in the
block, and so is more useful with datagram sockets that are not connected to
a single peer.
Message 13 - receive data
@@@@ Documentation not available
Message 14 - select
@@@@ Documentation not available
Message 15 - send data
Message 16 - send data to specified address
The control block is 8 bytes (message 15) or 12 bytes (message 16):
Offset 0 (word): socket handle
Offset 2 (word): address of first byte to send
Offset 4 (word): number of bytes to send
Offset 6 (word): flags:
Bit 0: set for out of band data
Bit 2: set to bypass routing
Offset 8 (word): address of a 16 byte network address block
Offset 10 (word): must be 16
Returns: number of bytes actually sent
Sends data to the remote peer of a connected socket (message 15) or to the
specified address with an unconnected socket (message 16).
Message 17 - send data
@@@@ Documentation not available
Message 18 - partially close a socket
The control block is 4 bytes:
Offset 0 (word): socket handle
Offset 2 (word): 0 = end reception, 1 = end transmission, 2 = end both
Performs a close on one or both directions of a connected TCP socket.
Message 19 - close a socket
The control block is 2 bytes:
Offset 0 (word): socket handle
Close a socket; the handle may no longer be used.
Message 20 - asynchronous action
@@@@ Documentation not available
Message 21 - configuration
@@@@ Documentation not available
Message 22 - control network
The control block is 6 bytes:
Offset 0 (long): action:
1 = connect to network,
2 = disconnect from network,
3 = return network status,
4 = get length of time connected, in seconds
5 = get local IP address, in network order
Offset 4 (word): address of a long to store any fetched value in
Returns: network status (action 3 only, see below)
Performs some network control action. Note that it is not necessary to use
this function to set up a connection; the first attempt to use the network
will do so automatically.
For action 2 only, the returned value gives the current status:
0 = disconnected, 1 = connecting, 2 = connected.
For actions 3 and 4, the result is stored in the long pointed to by
offset 4; the result is only valid if the call was made while connected to
the network.
Message 23 - cancel a pending operation on a socket
The control block is 2 bytes:
Offset 0 (word): socket handle
Cancels any pending operation on a socket. This call should only be made in
synchronous mode, with the status word initialized to zero.
Message 24 - assign socket
@@@@ Documentation not available
@@@@ socket, pid
Message 25 - register network client
No additional arguments
Returns: 0 for success, a negative error code for failure
This call registers the current process as a client of the network system.
It must be made when the IP object is created (see above), and can be
called additional times, in which case the calls are counted by the network
server process. Programs do not normally need to make additional calls.
Message 26 - deregister network client
No additional arguments
Returns: 0 for success, a negative error code for failure
This call cancels a registration of the current process as a client of the
network system, decrementing the count held by the network server. One such
cancellation is made when the IP object is destroyed, and all registrations
are cancelled when the current process terminates. Programs do not normally
need to call this directly.
The DNS object
--------------
The DNS object provides the following messages.
Message 1 - convert host to network (long)
Message 2 - convert network to host (long)
Message 3 - convert host to network (word)
Message 4 - convert network to host (word)
V1: 2 byte or 4 byte buffer holding the value
Each of these converts a value between host and network ordering; the
conversion is done in situ.
Message 5 - convert dotted quad to IP address
V1: long to hold resulting address
V2: cstr to be converted
Returns: zero for success or a non-zero error code
Converts a dotted quad name (such as "158.152.1.222") to an IP address
such as $9E9801DE, but in network order. The dotted quad may have two or
three components, and each component may be a C decimal, octal, or hex
number (so another form for the above is "0x9E.230.478").
Message 6 - test for valid IP address
@@@@ Documentation not available
Message 7 - get host by name
V1: 10 byte buffer which is filled in with the host information
V2: cstr of host name to be looked up
V3: status word
Returns: zero for success or a non-zero error code
This call is always asynchronous. It looks up a host in the DNS, and, if
found, the buffer is filled with the following information:
Offset 0 (word): address of the canonical name (a cstr)
Offset 2 (word): address of a zero-terminated list of words, each holding
the address of a cstr giving an alias, or zero if there
are no aliases
Offset 4 (long): unused
Offset 8 (word): address of a zero-terminated list of words, each holding
the address of a block holding a network address
The data pointed to is stored in an area which may be overwritten by any
other call to the interface module.
Message 8 - get host by address
V1: 10 byte buffer which is filled in with the host information
V2: 6 byte control block
V3: status word
Returns: zero for success or a non-zero error code
This call is always asynchronous. It looks up a host in the DNS, and, if
found, the buffer is filled with the same information as for message 7. The
control block has the following format:
Offset 0 (word): address of a long holding the IP address in network order
Offset 2 (word): must be 4
Offset 4 (word): must be 2
Message 9 - cancel a pending get host operation
V1: 10 byte buffer provided to the get host operation
This call cancels any outstanding get host operation (messages 7 and 8).
The V1 value must be that provided to the original operation.
Message 10 - extract local component of IP address
Message 11 - construct IP address from local and network components
Message 12 - extract network component of IP address
These calls are intended to split and recombine IP addresses treated as
network and local components, using the old class A, B, and C network
concepts. They are not documented here, partly because subnets and CIDR
have made them obsolete, and partly because the interfaces are flawed.
Message 13 - convert IP address to dotted quad
V1: long holding the IP address in network order
V2: 16 byte buffer filled in with the dotted quad as a cstr
This call converts an IP address such as $9E9801DE (but in network order)
to a dotted quad name such as "158.152.1.222".
Error codes
-----------
The IP object generates the following error codes:
-33 TCP/IP is not installed on the system
-32 Incompatible versions of TCP/IP are being used simultaneously
-16 sockdyl.dyl is corrupt
-10 Insufficient memory to initialize
9 Bad socket handle
11 Out of resources
14 Bad argument to operation (e.g. not a valid ADDR)
22 Invalid argument (e.g. attempting to re-bind a bound socket)
35 Operation would block and socket is non-blocking
36 Non-blocking operation in progress but not completed
37 Previous non-blocking operation still in progress
38 Socket operation on non-socket
39 Destination address required and socket not connected
40 Message too long and socket type does not allow it to be split
41 Wrong protocol type for this socket type
42 Unknown option for this protocol level
43 Protocol not supported in this address domain
44 Socket type not supported
45 Operation not supported on this socket type
46 Protocol family not supported
47 Address family not supported by protocol family
48 Address already in use
49 Can't assign requested address
50 Network is down
51 Network is unreachable
52 Network dropped connection on reset
53 Software caused connection abort
54 Connection reset by peer
55 No buffer space available in the socket server
56 Socket is already connected
57 Socket is not connected
58 Can't send after socket shutdown
@@ 59 Too many references: can't splice
60 Connection timed out
61 Connection refused
64 Host is down
65 No route to host
66 Network has not been initialized
1001 Syntax error in connection script
1002 Got abort string while connecting
1004 Error in configuration
1005 Serial port is in use
1006 Error with serial port
1007 Error reading connection script file
1008 Timer timed out while connecting
1009 Not enough memory to connect
1010 Couldn't find connection script dyl
1011 Couldn't load connection script dyl
1012 ISP modem busy
1013 No carrier
1014 No answer from ISP modem
1015 Couldn't read dial settings
The DNS object generates the following error codes:
1 insufficient memory in DNS process
2 failure creating socket in DNS process
3 failure during connect to DNS server
4 failure during send to DNS server
5 failure during receive from DNS server
6 DNS lookup returned "no such entry"
7 timeout waiting for DNS server
8 bad arguments
|
|
