This the multi-page printable view of this section.Click here to print.

Return to the regular view of this page.

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…0x3FSocket operations
0x40…0x7FResolver operations
0x80…0xBFReserved for future use
0xC0…0xFFReserved 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
0x06Socket Receive From
0x07Socket Receive Message
0x09Socket Send to
0x0ASocket Send Message
0x0CSocket Set Socket Option
0x0DSocket Get Socket Option
0x0ESocket Get Peer Name
0x0FSocket Get Socket Name
0x11Socket Select
0x12Socket Ioctl
0x13Socket Read
0x14Socket Write
0x15Socket Stat
0x16Socket Readv
0x17Socket 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
0x42Resolver Get Cache
0x43Resolver 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