11 Interface To L3 TCP And UDP Functionality (under construction)

11.1.1 Purpose of this Document

This document is addressed to people using the built-in TCP/IP functionality provided by TCP Manager, UDP Manager and Name Server L3 tasks.

The C-Interface for these managers was created as a basis for the development of a socket server for the UNIX emulation project on top of L3. However, they allow usage of networking functions (but without the socket interface).

The functions are still in a pre-release state, since only rudimentary testing was undertaken. In addition, the documentation is currently incomplete and awaits testers.

11.1.2 Related Documents

There is a document describing the network implementation of L3 (in Elan).

11.2 TCP Manager functions

The information contained here is basically from tcpifc.h.

11.2.1 Datastructures

typedef struct { int index; int state; ThreadT thread; } TCPChannelT; TCPChannelT contains the thread owning the connection, an index into a table managed by TCP Manager and the state of the connection (see below).

typedef struct { int IP_Address; WordT Port; } TCPSocketT; This structure (6 bytes) identifies uniquely the communication peer. IP_Address ( 4 Bytes) can be set using the L3_IP_Adress macro (see on top). Port contains the remote port.

Possible connection states

• L3_TCP_CLOSED
• L3_TCP_LISTEN
• L3_TCP_SYNSENT
• L3_TCP_SYNRECEIVED
• L3_TCP_ESTABLISHED
• L3_TCP_FINWAIT
• L3_TCP_FINWAIT2
• L3_TCP_CLOSEWAIT
• L3_TCP_CLOSING
• L3_TCP_LASTACK
• L3_TCP_TIMEWAIT

Some macros are defined in netmacros.h for easier access to the functions provided here.

• L3_Bytes2DWord(b1,b2,b3,b4) ((b1)<<24 | (b2)<<16 | (b3)<<8 |(b4))
• L3_IP_ADDRESS(b1,b2,b3,b4) (L3_Bytes2DWord(b4,b3,b2,b1))
• L3_Words2DWord(b1,b2) ((b1)<<16 |(b2))
• L3_SwapBytes(w) (((w) & 0xFF) << 8 | ((w) & 0xFF00) >> 8)
• L3_SwapDWords(dw) (((dw) & 0xFFFF) << 16 | ((dw) & 0xFFFF0000) >> 16)

int TCPRead (TCPChannelT * Channel, int Mode, char *Buffer, int BufSize, int RecvTimeOut);

TCPRead reads data from an existing TCP connection. This can be either blocking or nonblocking, depending on mode. { L3_TCP_BLOCKING,L3_TCP_NONBLOCKING }

Notes

1. A connection must exist.
2. If the read is blocking (e.g., for normal server operation), one can specify a timeout after which the call comes back (recommended during testing).
3. You must provide a buffer. If it is too small, multiple reads should get the remaining data.
4. TCPRead sets the connection state in TCPChannelT variable.

int TCPWrite (TCPChannelT * C, char *SendMsg, int MessageLength, char *Buffer, int BufSize, int flags);

Writes to an existing TCP connection. The message to be send must be placed in SendMsg.

If an error occured, the error message is placed in Buffer (? needs testing).

Flags can be:

• L3_TCP_NON
• L3_TCP_FIN Sender is done, wants to close.
• L3_TCP_SYN Used by TCPOpen.
• L3_TCP_RST Connection reset.
• L3_TCP_PSH Disable Nagle algorithm.
• L3_TCP_ACK Used by both Open und Write.
• L3_TCP_URG Urgent flag.

It is not clear to what extend the current L3 implementation supports these flags.

11.2.5 TCPOpen

int TCPOpen (TCPSocketT RSock, int Own_Port, int mode, int timer, TCPChannelT * Channel);

Remarks

• RSock contains the peer IP address and the remote port.
• Own_Port can be either -1 (automatic port selection), [1024..8999] or, if privileged [1..1023].
• Open can be either passive or active.
• Active open: SYN-Datagram is sent, do an waitack afterwards to wait for the TCP 3-way handshake to complete. Remote port and IP address must be specified in this case.
• Passive open: Just say that we are ready to accept connections on Own_Port. Remote_IP and port should be 0.
• Timer specifies the time interval before giving up connection setup (? -test this)

int TCPWaitAck (TCPChannelT * ChannelPtr);

MUST be called after an active open.

int TCPClose (TCPChannelT * Channel);

int TCPAbort (TCPChannelT *Channel);

int printChannel (TCPChannelT * Ch);

int TCPAbort(TCPChannelT * Channel);

int TCPGetSocket(TCPChannelT * Channel, TCPSocketT * MySockPtr, TCPSocketT * RSockPtr);

Fills Remote Socket and Own Socket.

int TCPInitTCPServerThreadID (void);

This function must be called before anything else.

11.3 UDP Manager Interface

Information from udpifc.h

11.4 Name Server Interface

Information from nsifc.h