From 1ad514b80bfda7680a6d6af456e9c6fd8f883090 Mon Sep 17 00:00:00 2001 From: John Bintz Date: Wed, 17 Apr 2024 19:41:33 -0400 Subject: [PATCH] Change up documentation structure --- API.md | 83 +++++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 68 insertions(+), 15 deletions(-) diff --git a/API.md b/API.md index 760c670..5c6f022 100644 --- a/API.md +++ b/API.md @@ -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 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