|
sequence res =
|
-
get_socket_error(integer err=SOCKET_ERROR) -- (Phix specific) obtain error details
-
err: An error code, if you happen to have one. Should probably be omitted more often than not.
res is of the form {integer err, string id, string short}, where:
err is eg 10049 (and never SOCKET_ERROR, which is -1)
id is eg "WSAEADDRNOTAVAIL" (matching in this case the constant WSAEADDRNOTAVAIL = 10049)
short is eg "Cannot assign requested address."
Invoked when socket/bind/listen/select/accept/recv/connect/send/etc return SOCKET_ERROR or otherwise indicate failure.
Note that SOCKET_ERROR effectively means "go fetch the real error" and obviously there is no point in passing that
along inside an "if res=SOCKET_ERROR then" conditional branch (nor any real harm, apart from proving to everyone that
you don’t quite know what you’re doing).
Also note that many Windows WSA codes are the same as the Linux equivalents, eg WSAEWOULDBLOCK == EWOULDBLOCK.
The (private) constant MAPWSA in builtins\sockets.e is expected to be gradually extended as and when needed, at the
time of writing it only contains about half a dozen entries (including the one just given).
|
|
atom hSocket =
|
-
socket(integer af, socktype, pf=0) -- create a new socket bound to a specific transport service provider
-
af: Address family, typically AF_INET for internet addresses.
socktype: Socket type, use SOCK_DGRAM for UDP or SOCK_STREAM for TCP.
pf: Protocol family, eg IPPROTO_xxx, or 0 to let the service provider choose, based on the address family.
There should be a matching closesocket() call for every socket() call.
Returns INVALID_SOCKET on error.
|
|
atom long =
|
-
htonl(atom long) -- host to network byte order for a u_long.
-
Network byte order is big-endian, but your machine is most likely little-endian.
This routine swaps the byte order for a long (4-byte) field, if necessary.
|
|
atom long =
|
-
ntohl(atom long) -- network to host byte order for a u_long.
-
The inverse of htonl (functionally identical, but with different semantics).
|
|
integer short =
|
-
htons(integer short) -- host to network byte order for a u_short.
-
Network byte order is big-endian, but your machine is most likely little-endian.
This routine swaps the byte order for a short (2-byte) field, if necessary.
|
|
integer short =
|
-
ntohs(integer short) -- network to host byte order for a u_short.
-
The inverse of htons (functionally identical, but with different semantics).
|
|
atom pSockAddr =
|
-
getsockname(atom hSocket) -- retrieves the local name for a socket.
-
hSocket: a socket handle, typically a result from socket(), or perhaps something out of libcurl, etc.
Returns a SOCKADDR structure, terminates on error.
|
|
integer port =
|
-
getsockport(atom hSocket) -- (Phix specific) retrieves the port number from a socket.
-
hSocket: a socket handle, typically a result from socket(), or perhaps something out of libcurl, etc.
Returns the port number, from the SOCKADDR structure obtained from getsockname().
|
|
atom addr =
|
-
getsockaddr(atom hSocket) -- (Phix specific) retrieves the address from a socket.
-
hSocket: a socket handle, typically a result from socket(), or perhaps something out of libcurl, etc.
Returns the address from the SOCKADDR structure obtained from getsockname(), suitable for passing to eg ip_to_string().
|
|
atom addr =
|
-
gethostbyname(string host) -- retrieves host information corresponding to a host name from a host database.
-
host: a host name, can be "".
Returns just the address portion of a hostent structure, INADDR_ANY if host is "", or SOCKET_ERROR if an error occured.
Note that the C function of the same name returns the entire hostent structure.
Apparently gethostbyname is deprecated and getaddrinfo should be used instead, erm - good luck with that.
|
|
atom pSockAddr =
|
-
sockaddr_in(integer af=AF_INET, string host="", integer port=0) -- allocate and populate a sockaddr_in structure.
-
af: Address family, typically AF_INET for internet addresses.
host: a host name, can be "" (for localhost).
port: a port number, or 0 (meaning "any").
Applies gethostbyname() and takes care of any host-to-network byte order conversions as needed.
Returns a sockaddr_in structure, or SOCKET_ERROR if an error occured.
|
|
integer res =
|
-
bind(atom sock, pSockAddr, integer len=socklen) -- associates a local address with a socket.
-
sock: a prior result from socket()
pSockAddr: a prior result from (eg) sockaddr_in()
len: Defaulted to the value used in sockaddr_in()
Must be used on an unconnected socket before a subsequent call to the listen() function.
Returns zero or SOCKET_ERROR on failure.
|
|
integer res =
|
-
connect(atom sock, pSockAddr, integer len=socklen) -- establishes a connection to a specified socket.
-
sock: a prior result from socket()
pSockAddr: a prior result from (eg) sockaddr_in()
len: Defaulted to the value used in sockaddr_in()
Returns zero or SOCKET_ERROR on failure.
|
|
integer res =
|
-
listen(atom sock, integer backlog) -- places a socket in a state in which it is listening for an incoming connection.
-
sock: a prior result from socket()
backlog: specifies the maximum number of pending connections.
Returns zero or SOCKET_ERROR on failure.
|
|
sequence res =
|
-
select(sequence read_set={}, write_set={}, error_set={}, object timeout={}) -- determine status of one or more sockets, waiting if necessary.
-
Check/wait the specified socket[s] until one or more is ready to read or write or has an error.
The result is of the form {integer ret_code, sequence {read_set, write_set, error_set}} = res,
or when only checking one socket the simpler integer {ret_code} = select(...) suffices.
read_set: sockets to check for readiness to read.
write_set: sockets to check for readiness to write.
error_set: sockets to check for errors.
timeout: in {seconds,microseconds} or atom microseconds format:
{0,0} or 0 means "return immediately", whereas {} means "wait forever".
{2,0} or 2000000 means "timeout after two seconds".
Each of the handles in each set should be a result from socket(), usually with listen() or connect() applied.
(IANASS - I Am Not A Socket Specialist).
I have also used this successfully with sockets obtained from libcurl/CURLINFO_ACTIVESOCKET.
For thread safety you may want to use sequence none = repeat(0,0) rather than {}, and avoid relying on those parameter defaults.
ret_code is SOCKET_ERROR, 0 for timeout, or a positive total number of socket handles that are ready.
Each of the returned read_set, write_set, and error_set should be a subset of the respective input sets.
|
|
atom peer =
|
-
accept(atom sock) -- permits an incoming connection attempt on a socket.
-
sock: previously passed to listen()
Returns a new socket on which the actual connection is made, or INVALID_SOCKET in the case of error.
|
|
sequence res =
|
-
recv(atom peer, integer maxlen=2048) -- receives data from a connected socket or a bound connectionless socket.
-
peer: a connected or bound socket
maxlen: obviously, can be increased if not large enough, or perhaps even reduced.
The result is of the form {integer len, string buffer} = res, where
len is SOCKET_ERROR (-1), 0 if the connection has been gracefully closed, or the number of bytes recieved, and
buffer is "" for len<=0, otherwise a binary string of length len (<=maxlen).
Note the C function accepts a buffer, but since we allocate a string result anyway, we may as well just use that directly.
Also note that some unreliable protocols (eg UDP) may simply discard any data beyond maxlen.
|
|
integer bytes_sent =
|
-
send(atom peer, string message) -- sends data on a connected socket.
-
peer: previously passed to connect()
message: can be a binary string.
Returns the actual number of bytes transmitted, which may be less than the total message length, or SOCKET_ERROR on failure.
|
|
procedure
|
-
shutdown(atom sock, integer how) -- disable sends or recieves on a socket
-
sock: a prior result from socket()
how: SD_RECEIVE, SD_SEND, or SD_BOTH
Deliberately crashes on error, eg with ERROR (shutdown): {10057,"WSAENOTCONN","Socket is not connected."}
|
|
procedure
|
-
atom sock = closesocket(atom sock) -- close a socket
-
There should be a matching closesocket() call for every socket() call.
Deliberately triggers a (catchable) crash on error, but does nothing when passed a sock of 0 or SOCKET_ERROR.
Returns 0 on success, intended for clearing the input parameter as shown, or SOCKET_ERROR if it was already 0.
|
|
procedure
|
-
WSACleanup() -- terminates use of the Winsock 2 DLL (Ws2_32.dll).
-
The corresponding WSAStartup() is handled automatically for you, should you forget, does nothing on Linux, and is not separately documented.
Deliberately crashes on error. The "WSAStartup not called" error should never happen, but it can fail if the network subsystem
has failed or something is still in progress, so occasionally you may need to wrap the call in a try/catch,
which I figured was probably better than forcing everyone else to ignore an irrelevant error code and/or in so doing make them
miss out on spotting some other coding error, such as leaving more and more blocked threads hogging resources for no good reason.
Does nothing on Linux, apart from making the program more portable.
|
|
atom res =
|
-
inet_addr(string cp) -- converts a string containing an IPv4 dotted-decimal address into a proper address for the IN_ADDR structure
-
Example: inet_addr("127.0.0.1") ==> #100007F
Returns INADDR_NONE on error.
There is a simple IPv4-only phix-specific inverse: string cp = ip_to_string(atom ip) - which does things manually, rather
than wrapping the inet_ntoa C function, which might have been a mistake.
|
|
procedure
|
-
setsockopt(atom sock, integer level, optname, atom pOptVal, integer optlen) -- set a socket option
-
sock: a prior result from socket()
level: eg SOL_SOCKET
optname: eg SO_BROADCAST
pOptVal: A pointer to buffer in which the value for the requested options is specified
optlen: The size, in bytes, of the buffer pointed to by the optval parameter
Not actually used in anger anywhere that I know of yet. Terminates in error on failure.
|
