Change up documentation structure

This commit is contained in:
John Bintz 2024-04-17 19:41:33 -04:00
parent bd74050e06
commit 1ad514b80b
1 changed files with 68 additions and 15 deletions

83
API.md
View File

@ -3,7 +3,9 @@
Most functions will return -2 if the bsdsocket.library is
not open.
### Setup
---
## Setup
#### ADDR=Socket Library Open
@ -16,11 +18,15 @@ Try to open bsdsocket.library version 4.
* If needed, you'll be able to directly access library functions
using this address.
---
#### Socket Library Close
Close bsdsocket.library. This is safe to call if the library
is not open
---
#### RESULT=Socket Set Nonblocking(Socket, IsNonblocking BOOL)
Make a socket blocking (False, default), or nonblocking (True).
@ -29,6 +35,8 @@ Make a socket blocking (False, default), or nonblocking (True).
* Result of IoctlSocket call.
---
#### RESULT=Socket Reuse Addr(Socket)
Make a listening socket reuse the address it's trying to bind to.
@ -38,9 +46,9 @@ You probably want to call this right before Socket Listen.
* Result of setsockopt call.
---
### Connections
## Connections
#### SOCKET=Socket Create Inet Socket
@ -51,6 +59,8 @@ Create a new Internet socket for reading or writing.
* Socket number on success
* -1 on failure
---
#### RESULT=Socket Connect(Socket to IPAddress$, Port)
Attempt to connect to a remote host. Currently doesn't
@ -65,6 +75,8 @@ support DNS lookups.
to see if the connection succeeded
* -11 port out of range
---
#### RESULT=Socket Reuse Addr(Socket)
Set a server socket to reuse an interface and port that had
@ -77,6 +89,8 @@ setsockopt() for you.
The result of calling setsockopt() while setting your socket
to reuse addresses.
---
#### RESULT=Socket Bind(Socket to IPAddress, Port)
Attempt to bind a socket to a network interface. Use
@ -89,6 +103,8 @@ interfaces.
* -1 on other error
* -11 port out of range
---
#### RESULT=Socket Listen(Socket)
Start listening for connections.
@ -98,6 +114,8 @@ Start listening for connections.
* 0 on success
* -1 on failure
---
#### NEW_SOCKET=Socket Accept(Socket)
Get the socket that connected to this one. Wait for a connect
@ -115,11 +133,13 @@ socket non-blocking and use Fdsets and Select!
* The remote socket number on success
* -1 on failure
#### RESULT=Socket Async Wait Reading(Socket, Wait_ms)
---
#### RESULT=Socket Wait Async Reading(Socket, Wait_ms)
Wait the given number of milliseconds for the nonblocking socket to be ready for reading.
Use this when you're waiting for a client to connect to you, or if you're waiting for
a remote socket to send you data.
Use on a listen socket to await new connections, or on a connected socket to await
incoming data packets.
##### Returns
@ -127,7 +147,9 @@ a remote socket to send you data.
* -1 on error. Use `Socket Errno` for more detail.
* 1 on success.
#### RESULT=Socket Async Wait Writing(Socket, Wait_ms)
---
#### RESULT=Socket Wait Async Writing(Socket, Wait_ms)
Wait the given number of milliseconds for the nonblocking socket to be ready for writing.
Use this when you're connecting to a remote server and want to know if the connection
@ -143,6 +165,8 @@ has been completed.
checks will return 1.
* 1 on success.
---
#### RESULT=Socket Set Timeout(Socket, Wait_ms)
Set a socket to timeout after Wait_ms milliseconds if reading or writing doesn't complete.
@ -152,6 +176,8 @@ Set a socket to timeout after Wait_ms milliseconds if reading or writing doesn't
* 0 on success
* -1 on error
---
#### RESULT=Socket Close Socket(Socket)
Close a socket.
@ -161,9 +187,9 @@ Close a socket.
* 0 on success
* -1 on error
---
### Data Transfers
## Data Transfers
#### SENT=Socket Send$(Socket, String$)
@ -194,6 +220,8 @@ End Proc
* Number of characters sent
* -1 on other error
---
#### SENT=Socket Send(Socket, Data Pointer, Length)
Send a block of data to a connected socket.
@ -203,6 +231,8 @@ Send a block of data to a connected socket.
* Number of characters sent
* -1 on other error
---
#### DATA$=Socket Recv$(Socket, MaxLength)
Retrieve at most MaxLength bytes from Socket, and put them into a string.
@ -212,7 +242,9 @@ If Len(DATA$) < MaxLength, you've read the last bit of data from the socket.
* String of data, which is blank if there is no more data.
### LENGTH=Socket Recv(Socket to Dataptr, MaxLength)
---
#### LENGTH=Socket Recv(Socket to Dataptr, MaxLength)
Retrieve at most MaxLength bytes from Socket, and put them into the memory
address at Dataptr.
@ -222,9 +254,9 @@ address at Dataptr.
* Count of bytes read
* -1 on error
---
### Informational
## Informational
#### HOST=Socket Get Host(Socket)
@ -234,6 +266,8 @@ Get the IPv4 (Long) host value the given socket is using.
* Host as a long value
---
#### PORT=Socket Get Port(Socket)
Get the 16-bit port (Word) value the given socket is using.
@ -242,6 +276,8 @@ Get the 16-bit port (Word) value the given socket is using.
* Port as a word value
---
#### RESULT$=Socket Inet Ntoa$(Host)
Turn a long Host address into a string.
@ -250,6 +286,8 @@ Turn a long Host address into a string.
* IP address as string
---
#### RESULT=Socket Errno
Get the error from the last command. Note that this is
@ -260,6 +298,8 @@ not cleared on a successful command!
Error number from last call. Look in <sys/error.h> for more
details.
---
#### RESULT=Socket Herrno
Get the error from the last DNS resolver command.
@ -268,6 +308,8 @@ Get the error from the last DNS resolver command.
Resolver error number (`h_errno`) from last call.
---
#### RESULT$=Dns Get Address By Name$(Domain Name$)
Look up the first IP address associated with this hostname.
@ -282,6 +324,8 @@ out. There's no way to set this timeout, or cancel or override it via AMOS.
String with IP address, or blank string on error.
---
#### RESULT=Socket Status(Socket)
Returns basic connection information about a socket.
@ -305,9 +349,9 @@ Status of socket:
* 6 = Connecting
* 7 = Connected
---
### Low Level
## Low Level
#### RESULT=Socket Setsockopt Int(Socket, Option, Value)
@ -319,6 +363,8 @@ Socket Reuse Addr().
* Result of setsockopt call
---
#### RESULT=Socket Getsockopt Int(Socket, Option)
Get a socket option. You probably want SO_ERROR,
@ -329,6 +375,8 @@ attempt a connection with a non-blocking socket.
* Result of getsockopt call
---
#### ADDR=Socket Fdset Zero(fd_set)
Clear out the specified fd_set.
@ -338,6 +386,8 @@ Clear out the specified fd_set.
* Address to that particular fd_set
* -1 if fd_set out of range. You get 16 of them.
---
#### ADDR=Socket Fdset Set(fd_set, Socket to Value BOOL)
Set or clear a socket bit in an fd_set.
@ -347,6 +397,8 @@ Set or clear a socket bit in an fd_set.
* Address to that particular fd_set
* -1 if fd_set is out of range or socket is out of range.
---
#### RESULT=Socket Fdset Is Set(fd_set, Socket)
See if the particular socket remained after a Socket Select call.
@ -355,6 +407,8 @@ See if the particular socket remained after a Socket Select call.
* True or False if the socket is set or not
---
#### RESULT=Socket Select(Max Socket, Read fd_set, Write fd_set, Error fd_set, TimeoutMS)
Wait for the specified number of milliseconds. If any of the sockets
@ -366,4 +420,3 @@ how many sockets were left.
* 0 on timeout
* -1 on error
* # of interesting sockets on success