TheIndustriousRabbit
/
amos-pro-bsdsocket-extension
1
0
Fork 0
Code Issues Pull Requests Projects Releases 6 Wiki Activity

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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

83
API.md
View File

@ -3,7 +3,9 @@
Most functions will return -2 if the bsdsocket.library is Most functions will return -2 if the bsdsocket.library is
not open. not open.
### Setup ---
## Setup
#### ADDR=Socket Library Open #### 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 * If needed, you'll be able to directly access library functions
using this address. using this address.
---
#### Socket Library Close #### Socket Library Close
Close bsdsocket.library. This is safe to call if the library Close bsdsocket.library. This is safe to call if the library
is not open is not open
---
#### RESULT=Socket Set Nonblocking(Socket, IsNonblocking BOOL) #### RESULT=Socket Set Nonblocking(Socket, IsNonblocking BOOL)
Make a socket blocking (False, default), or nonblocking (True). 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 of IoctlSocket call.
---
#### RESULT=Socket Reuse Addr(Socket) #### RESULT=Socket Reuse Addr(Socket)
Make a listening socket reuse the address it's trying to bind to. 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. * Result of setsockopt call.
---
## Connections
### Connections
#### SOCKET=Socket Create Inet Socket #### SOCKET=Socket Create Inet Socket
@ -51,6 +59,8 @@ Create a new Internet socket for reading or writing.
* Socket number on success * Socket number on success
* -1 on failure * -1 on failure
---
#### RESULT=Socket Connect(Socket to IPAddress$, Port) #### RESULT=Socket Connect(Socket to IPAddress$, Port)
Attempt to connect to a remote host. Currently doesn't Attempt to connect to a remote host. Currently doesn't
@ -65,6 +75,8 @@ support DNS lookups.
to see if the connection succeeded to see if the connection succeeded
* -11 port out of range * -11 port out of range
---
#### RESULT=Socket Reuse Addr(Socket) #### RESULT=Socket Reuse Addr(Socket)
Set a server socket to reuse an interface and port that had 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 The result of calling setsockopt() while setting your socket
to reuse addresses. to reuse addresses.
---
#### RESULT=Socket Bind(Socket to IPAddress, Port) #### RESULT=Socket Bind(Socket to IPAddress, Port)
Attempt to bind a socket to a network interface. Use Attempt to bind a socket to a network interface. Use
@ -89,6 +103,8 @@ interfaces.
* -1 on other error * -1 on other error
* -11 port out of range * -11 port out of range
---
#### RESULT=Socket Listen(Socket) #### RESULT=Socket Listen(Socket)
Start listening for connections. Start listening for connections.
@ -98,6 +114,8 @@ Start listening for connections.
* 0 on success * 0 on success
* -1 on failure * -1 on failure
---
#### NEW_SOCKET=Socket Accept(Socket) #### NEW_SOCKET=Socket Accept(Socket)
Get the socket that connected to this one. Wait for a connect 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 * The remote socket number on success
* -1 on failure * -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. 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 Use on a listen socket to await new connections, or on a connected socket to await
a remote socket to send you data. incoming data packets.
##### Returns ##### Returns
@ -127,7 +147,9 @@ a remote socket to send you data.
* -1 on error. Use `Socket Errno` for more detail. * -1 on error. Use `Socket Errno` for more detail.
* 1 on success. * 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. 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 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. checks will return 1.
* 1 on success. * 1 on success.
---
#### RESULT=Socket Set Timeout(Socket, Wait_ms) #### RESULT=Socket Set Timeout(Socket, Wait_ms)
Set a socket to timeout after Wait_ms milliseconds if reading or writing doesn't complete. 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 * 0 on success
* -1 on error * -1 on error
---
#### RESULT=Socket Close Socket(Socket) #### RESULT=Socket Close Socket(Socket)
Close a socket. Close a socket.
@ -161,9 +187,9 @@ Close a socket.
* 0 on success * 0 on success
* -1 on error * -1 on error
---
## Data Transfers
### Data Transfers
#### SENT=Socket Send$(Socket, String$) #### SENT=Socket Send$(Socket, String$)
@ -194,6 +220,8 @@ End Proc
* Number of characters sent * Number of characters sent
* -1 on other error * -1 on other error
---
#### SENT=Socket Send(Socket, Data Pointer, Length) #### SENT=Socket Send(Socket, Data Pointer, Length)
Send a block of data to a connected socket. 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 * Number of characters sent
* -1 on other error * -1 on other error
---
#### DATA$=Socket Recv$(Socket, MaxLength) #### DATA$=Socket Recv$(Socket, MaxLength)
Retrieve at most MaxLength bytes from Socket, and put them into a string. 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. * 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 Retrieve at most MaxLength bytes from Socket, and put them into the memory
address at Dataptr. address at Dataptr.
@ -222,9 +254,9 @@ address at Dataptr.
* Count of bytes read * Count of bytes read
* -1 on error * -1 on error
---
## Informational
### Informational
#### HOST=Socket Get Host(Socket) #### 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 * Host as a long value
---
#### PORT=Socket Get Port(Socket) #### PORT=Socket Get Port(Socket)
Get the 16-bit port (Word) value the given socket is using. 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 * Port as a word value
---
#### RESULT$=Socket Inet Ntoa$(Host) #### RESULT$=Socket Inet Ntoa$(Host)
Turn a long Host address into a string. Turn a long Host address into a string.
@ -250,6 +286,8 @@ Turn a long Host address into a string.
* IP address as string * IP address as string
---
#### RESULT=Socket Errno #### RESULT=Socket Errno
Get the error from the last command. Note that this is 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 Error number from last call. Look in <sys/error.h> for more
details. details.
---
#### RESULT=Socket Herrno #### RESULT=Socket Herrno
Get the error from the last DNS resolver command. 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. Resolver error number (`h_errno`) from last call.
---
#### RESULT$=Dns Get Address By Name$(Domain Name$) #### RESULT$=Dns Get Address By Name$(Domain Name$)
Look up the first IP address associated with this hostname. 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. String with IP address, or blank string on error.
---
#### RESULT=Socket Status(Socket) #### RESULT=Socket Status(Socket)
Returns basic connection information about a socket. Returns basic connection information about a socket.
@ -305,9 +349,9 @@ Status of socket:
* 6 = Connecting * 6 = Connecting
* 7 = Connected * 7 = Connected
---
## Low Level
### Low Level
#### RESULT=Socket Setsockopt Int(Socket, Option, Value) #### RESULT=Socket Setsockopt Int(Socket, Option, Value)
@ -319,6 +363,8 @@ Socket Reuse Addr().
* Result of setsockopt call * Result of setsockopt call
---
#### RESULT=Socket Getsockopt Int(Socket, Option) #### RESULT=Socket Getsockopt Int(Socket, Option)
Get a socket option. You probably want SO_ERROR, 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 * Result of getsockopt call
---
#### ADDR=Socket Fdset Zero(fd_set) #### ADDR=Socket Fdset Zero(fd_set)
Clear out the specified fd_set. Clear out the specified fd_set.
@ -338,6 +386,8 @@ Clear out the specified fd_set.
* Address to that particular fd_set * Address to that particular fd_set
* -1 if fd_set out of range. You get 16 of them. * -1 if fd_set out of range. You get 16 of them.
---
#### ADDR=Socket Fdset Set(fd_set, Socket to Value BOOL) #### ADDR=Socket Fdset Set(fd_set, Socket to Value BOOL)
Set or clear a socket bit in an fd_set. 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 * Address to that particular fd_set
* -1 if fd_set is out of range or socket is out of range. * -1 if fd_set is out of range or socket is out of range.
---
#### RESULT=Socket Fdset Is Set(fd_set, Socket) #### RESULT=Socket Fdset Is Set(fd_set, Socket)
See if the particular socket remained after a Socket Select call. 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 * 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) #### 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 Wait for the specified number of milliseconds. If any of the sockets
@ -366,4 +420,3 @@ how many sockets were left.
* 0 on timeout * 0 on timeout
* -1 on error * -1 on error
* # of interesting sockets on success