IP Networking and DNS Resolution
Table of Contents
This call is supported on the Network API
documentation for the
SPROW Ethernet upgrade for the Master Series
which I happen to have installed in my BBC Master 128.
This call is modelled on the Berkeley Sockets API.
Call format
The control block follows the convention for high-numbered OSWORD calls where the control block contains the
request & response sizes, action and result codes as the first 4 bytes of the block.
| XY+ |
On entry |
On exit |
Range |
| 0 |
send block length, depends on subreason code |
preserved |
0x02…0x7F |
| 1 |
return block length, depends on subreason code |
preserved |
0x02…0x7F |
| 2 |
action |
set to zero |
|
| 3 |
must be zero |
result |
|
| 4… |
request data |
result data |
|
Actions
To allow for many functions to be performed but without using up lots of OSWord numbers a one byte
action code is included, allowing for up to 256 different pieces of functionality.
The action codes are further split into groups of 64 each:
| Action (range) |
Functionality |
| 0x00…0x3F | Socket operations |
| 0x40…0x7F | Resolver operations |
| 0x80…0xBF | Reserved for future use |
| 0xC0…0xFF | Reserved for future use |
Unused or reserved action codes will return an error number at XY+3.
1 - Socket operations
0x00 Socket Create
This function sets up a new socket and returns a handle for its future use.
Only a limited number of sockets can be opened simultaneously.
| XY+ |
Length |
On entry |
On exit |
| 4 |
4 |
Communications domain, 2 for PF_INET |
socket number created or -1 on failure |
| 8 |
4 |
Socket type:
1=stream
2=datagram
3=raw
|
|
| 12 |
4 |
Protocol or zero for default for the socket type |
|
0x01 Socket Bind
Bind a socket to a specific local address.
| XY+ |
Length |
On entry |
On exit |
| 4 |
4 |
socket |
-1 if the bind fails |
| 8 |
4 |
Pointer to socket address to bind to |
|
| 12 |
4 |
Size of socket address, usually 16 |
|
Socket address
| sa+ |
Length |
On entry |
On exit |
| 0 |
1 |
Size of socket address, usually 16 |
| 1 |
1 |
Address family, 2 for AF_INET |
| 2 |
2 |
Port number |
| 4 |
4 |
IPv4 address |
| 8 |
4 |
Zero |
| 12 |
4 |
Zero |
Note that the size of the socket address structure is used twice, once in the structure itself, and also as the
third parameter at YX+12.
0x02 Socket Listen
Switch a socket into listening for incoming connection attempts.
Only sockets opened and configured to tbe stream based sockets can be set to listen,
datagram and raw sockets are connectionless and cannot be set to listen.
| XY+ |
Length |
On entry |
On exit |
| 4 |
4 |
socket |
-1 if the call fails |
| 8 |
4 |
Backlog of unaccepted connections to allow before rejecting |
|
0x03 Socket Accept
Switch a socket into listening for incoming connection attempts.
Only sockets opened and configured to tbe stream based sockets can be set to listen,
datagram and raw sockets are connectionless and cannot be set to listen.
| XY+ |
Length |
On entry |
On exit |
| 4 |
4 |
socket |
-1 if the bind fails |
| 8 |
4 |
Pointer to socket address to bind to |
|
| 12 |
4 |
pointer to an integer describing the size of socket address (usually 16) |
|
Note: XY+12 in the original documentation mentions this is a pointer, but in other calls it's an actual value.
This needs clarifying.
0x04 Socket Connect
Accept an incoming connection on an existing socket.
If there are no pending incoming connections, this call will block until there is one.
On accepting, the address details of the remote computer will be filled in at the block pointed to by YX+8.
| XY+ |
Length |
On entry |
On exit |
| 4 |
4 |
socket |
-1 if the connect fails |
| 8 |
4 |
Pointer to socket address to bind to |
|
| 12 |
4 |
size of socket address (usually 16) |
|
0x05 Socket Receive
Read data from the given socket.
This function attempts to read data or waits until some is ready.
It is possible that zero bytes are returned, probably indicating that the remote computer has disconnected.
| XY+ |
Length |
On entry |
On exit |
| 4 |
4 |
socket |
-1 on failure, otherwise number of bytes received |
| 8 |
4 |
Pointer to data buffer to receive into |
|
| 12 |
4 |
Buffer size |
|
| 16 |
4 |
Flags, usually 0 |
|
0x08 Socket Send
Send out data on the given socket.
For raw and datagram style sockets the message length must fit within one packet otherwise the request will
be rejected, for stream style sockets as much as the message as possible will be queued and sent subject to
available memory.
| XY+ |
Length |
On entry |
On exit |
| 4 |
4 |
socket |
-1 on failure, otherwise number of bytes sent |
| 8 |
4 |
Pointer to data buffer to send |
|
| 12 |
4 |
Buffer size |
|
| 16 |
4 |
Flags, usually 0 |
|
0x0B Socket Shutdown
Shutdown part of a socket.
This allows a socket to be partially shut where the TCP/IP stack supports this. Caution should be taken as
this does not actually close the socket, so does not free up any of the resources associated with the socket -
see details of Close for how to do this.
| XY+ |
Length |
On entry |
On exit |
| 4 |
4 |
socket |
-1 on failure |
| 8 |
4 |
Direction to shut
0=receive side
1=transmit side
2=both sides |
|
| 12 |
4 |
Buffer size |
|
| 16 |
4 |
Flags, usually 0 |
|
0x10 Socket Close
Close a socket.
As there are fixed number of sockets available it is important to remember to close sockets once any
transactions are complete.
| XY+ |
Length |
On entry |
On exit |
| 4 |
4 |
socket |
-1 on failure |
Unsupported actions
The following actions are defined but are not supported. Using them will return an error.
| Action |
Description |
| 0x06 | Socket Receive From |
| 0x07 | Socket Receive Message |
| 0x09 | Socket Send to |
| 0x0A | Socket Send Message |
| 0x0C | Socket Set Socket Option |
| 0x0D | Socket Get Socket Option |
| 0x0E | Socket Get Peer Name |
| 0x0F | Socket Get Socket Name |
| 0x11 | Socket Select |
| 0x12 | Socket Ioctl |
| 0x13 | Socket Read |
| 0x14 | Socket Write |
| 0x15 | Socket Stat |
| 0x16 | Socket Readv |
| 0x17 | Socket Writev |
2 - Resolver operations
0x40 Resolver Get Host By Name
Resolves a host name to a network address.
A control terminated name will be passed to the DNS resolver software built into the network module.
This call will then wait for a result, and only return when a match is found or timeout occurs.
The returned block at YX+8 onwards is a 'hostent' structure containing a list of IP addresses amongst other information,
the lists will remain valid until the next resolver request.
| XY+ |
Length |
On entry |
On exit |
| 4 |
4 |
|
Pointer to name looked up |
| 8 |
4 |
|
Pointer to null terminated list of pointers to aliases |
| 12 |
4 |
|
IP address type returned, 2 for AF_INET |
| 16 |
4 |
|
Length of this address type, 4 for IPv4 |
| 20 |
4 |
|
Pointer to null terminated list of pointers to IP address(es) |
0x41 Resolver Get Host
Resolves a host name to a network address.
This is very similar to GetHostByName except that it returns immediately.
If the name is already in the DNS cache the result will be filled in and YX+3 is zero,
otherwise a request is issued and a 'resolver busy' error returned.
Further calls to GetHost will update YX+3 until either a timeout occurs or the name is found.
This allows the request to be sent and the foreground program continue operating, compare this with
GetHostByName which blocks until the name has been found.
| XY+ |
Length |
On entry |
On exit |
| 4 |
4 |
|
Pointer to name looked up |
| 8 |
4 |
|
Pointer to null terminated list of pointers to aliases |
| 12 |
4 |
|
IP address type returned, 2 for AF_INET |
| 16 |
4 |
|
Length of this address type, 4 for IPv4 |
| 20 |
4 |
|
Pointer to null terminated list of pointers to IP address(es) |
Unsupported actions
The following actions are defined but do nothing. They do not return an error.
| Action |
Description |
| 0x42 | Resolver Get Cache |
| 0x43 | Resolver Cache Control |
3 - Library functions
The following listing provides BASIC functions with the same names and parameters as the corresponding
function in most libraries for the 'C' programming language as a convenience for use.
This is taken verbatim from the original documentation:
1REM Network functions
2REM (C)2010 SPROW
3:
4DEFFNgethost(name$)
5wordblk?0=8:REM Parameters in
6wordblk?1=24:REM Parameters out
7wordblk?2=&41:REM Resolver_GetHost
8wordblk?3=0:REM No error on entry
9wordblk!4=nameblk
10$nameblk=name$
11A%=192:X%=wordblk:Y%=wordblk DIV256:CALL&FFF1
12IFwordblk?3<>0 THEN=0
13=wordblk+4:REM Address not value
14:
15DEFFNcreat(pf%,type%,prot%)
16wordblk?0=16:REM Parameters in
17wordblk?1=8:REM Parameters out
18wordblk?2=&00:REM Socket_Creat
19wordblk?3=0:REM No error on entry
20wordblk!4=pf%
21wordblk!8=type%
22wordblk!12=prot%
23A%=192:X%=wordblk:Y%=wordblk DIV256:CALL&FFF1
24IFwordblk?3<>0 THEN=-1
25=wordblk!4
26:
27DEFFNbind(handle%,addr%,addrlen%)
28wordblk?0=16:REM Parameters in
29wordblk?1=8:REM Parameters out
30wordblk?2=&01:REM Socket_Bind
31wordblk?3=0:REM No error on entry
32wordblk!4=handle%
33wordblk!8=addr%
34wordblk!12=addrlen%
35A%=192:X%=wordblk:Y%=wordblk DIV256:CALL&FFF1
36IFwordblk?3<>0 THEN=-1
37=wordblk!4
38:
39DEFFNlisten(handle%,count%)
40wordblk?0=12:REM Parameters in
41wordblk?1=8:REM Parameters out
42wordblk?2=&02:REM Socket_Listen
43wordblk?3=0:REM No error on entry
44wordblk!4=handle%
45wordblk!8=count%
46A%=192:X%=wordblk:Y%=wordblk DIV256:CALL&FFF1
47IFwordblk?3<>0 THEN=-1
48=wordblk!4
49:
50DEFFNaccept(handle%,addr%,addrlenblk%)Network programmer's API
51wordblk?0=16:REM Parameters in
52wordblk?1=8:REM Parameters out
53wordblk?2=&03:REM Socket_Accept
54wordblk?3=0:REM No error on entry
55wordblk!4=handle%
56wordblk!8=addr%
57wordblk!12=addrlenblk%
58A%=192:X%=wordblk:Y%=wordblk DIV256:CALL&FFF1
59IFwordblk?3<>0 THEN=-1
60=wordblk!4
61:
62DEFFNconnect(handle%,addr%,addrlen%)
63wordblk?0=16:REM Parameters in
64wordblk?1=8:REM Parameters out
65wordblk?2=&04:REM Socket_Connect
66wordblk?3=0:REM No error on entry
67wordblk!4=handle%
68wordblk!8=addr%
69wordblk!12=addrlen%
70A%=192:X%=wordblk:Y%=wordblk DIV256:CALL&FFF1
71IFwordblk?3<>0 THEN=-1
72=wordblk!4
73:
74DEFFNrecv(handle%,data%,len%,opts%)
75wordblk?0=20:REM Parameters in
76wordblk?1=8:REM Parameters out
77wordblk?2=&05:REM Socket_Recv
78wordblk?3=0:REM No error on entry
79wordblk!4=handle%
80wordblk!8=data%
81wordblk!12=len%
82wordblk!16=opts%
83A%=192:X%=wordblk:Y%=wordblk DIV256:CALL&FFF1
84IFwordblk?3<>0 THEN=-1
85=wordblk!4
86:
87DEFFNsend(handle%,data%,len%,opts%)
88wordblk?0=20:REM Parameters in
89wordblk?1=8:REM Parameters out
90wordblk?2=&08:REM Socket_Send
91wordblk?3=0:REM No error on entry
92wordblk!4=handle%
93wordblk!8=data%
94wordblk!12=len%
95wordblk!16=opts%
96A%=192:X%=wordblk:Y%=wordblk DIV256:CALL&FFF1
97IFwordblk?3<>0 THEN=-1
98=wordblk!4
99:
100DEFPROCshutdown(handle%,type%)
101wordblk?0=12:REM Parameters in
102wordblk?1=4:REM Parameters out
103wordblk?2=&0B:REM Socket_Shutdown
104wordblk?3=0:REM No error on entry
105wordblk!4=handle%Network programmer's API
106wordblk!8=type%
107A%=192:X%=wordblk:Y%=wordblk DIV256:CALL&FFF1
108ENDPROC
109:
110DEFPROCclose(handle%)
111wordblk?0=8:REM Parameters in
112wordblk?1=4:REM Parameters out
113wordblk?2=&10:REM Socket_Close
114wordblk?3=0:REM No error on entry
115wordblk!4=handle%
116A%=192:X%=wordblk:Y%=wordblk DIV256:CALL&FFF1
117ENDPROC