Info
Content

TCPIP

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
No Comments
Back to top