Main sections
SOCK_...
This chapter describes the SOCK_ command set with which you can send TCP and UDP messages. You will find that GLBasic's network programming capabilities are equal or superior to any other programming languages.
The much easier network commands NET... will still exist, since they are easy to use by game programmers.
For reference, a socket is an object that has a local address (your network card's IP) a remote address (where you have connected to) and a port (which you will use to listen or send).
Further information about sockets can be found here:
http://beej.us/guide/bgnet/
http://www.freebsd.org/doc/en/books/developers-handbook/sockets.html
ok% = SOCK_INIT()
Call this command first to enable network commands. On Windows this will call WSAStartup and initialize some memory used internally. The return value is either TRUE if everything is OK or FALSE to indicate an error.
You can retrieve any error messages with NETGETLASTERROR$().
SOCK_SHUTDOWN
If you don't need the SOCK_ commands anymore, you should call this command for each call of SOCK_INIT.
sock% = SOCK_TCPLISTEN(port%)
This command creates a socket() and binds it to a local port "port%". From now on the program "listens" to TCP messages sent to this port.
The return value is either a socket or -1 if an error occurred.
You can retrieve any error messages with NETGETLASTERROR$().
sock% = SOCK_TCPCONNECT(server$, port%)
With this command you create a socket that tries to connect to a server (it is the opposite of SOCK_TCPLISTEN()).
server$ is a computer name or an IP address, for example "www.glbasic.com", "PC-GF" or "129.128.0.25".
With port% you can specify which port you want to connect to. This will correspond with the port that the server called SOCK_TCPLISTEN to listen on.
The return value is either a valid socket or -1, indicating an error.
You can retrieve any error messages with NETGETLASTERROR$().
sock% = SOCK_TCPACCEPT(sock_listen%, BYREF ip%)
This function returns a valid socket (<> -1) if another process has successfully used SOCK_TCPCONNECT() to connect to your SOCK_TCPLISTEN() port.
You can now communicate with other processes by reading from or writing to this socket.
When you don't need this connection anymore, call SOCK_CLOSE() to close this socket.
The integer number ip% will get the IP address of the remote computer. You can use it in SOCK_UDPSEND to send a UDP message to this computer.
With SOCK_GETIP$() you can translate this IP into a readable form.
You can retrieve any error messages with NETGETLASTERROR$().
rv% = SOCK_TCPSEND(dest_sock%, msg$)
Sends a message via TCP to a connected socket - one that you connected to via a command like SOCK_TCPACCEPT() or SOCK_TCPCONNECT().
msg$ is the message text to send. GLBasic will send the exact text without appending any special characters to it, so any extra characters you'd like sent (eg \0 -> chr$(0)) you will need to append yourself.
The return value rv% indicates the number of sent characters (bytes). If rv%=-1, an error occurred.
You can retrieve any error messages with NETGETLASTERROR$().
UDP Commands
sock% = SOCK_UDPOPEN(port%)
This command creates a socket that enables the sending and receiving of messages via the local UDP port port%.
The return value is either a valid socket or -1 if an error occurred.
You can get any error messages with NETGETLASTERROR$().
The UDP sockets in GLBasic always have the internal parameter SO_BROADCAST enabled, thus you may send broadcast messages with them.
You can retrieve any error messages with NETGETLASTERROR$().
rv% = SOCK_UDPSEND(sockudp%, msg$, dest_ip%, dest_port%)
Sends a message via UDP using a socket previously created with SOCK_UDPOPEN().
msg$ is the message text to send. The length of the message sent is the exact length of the text provided. No terminating '\0' will be appended for example as a TCP application would usually do.
dest_ip% is the IP address of the recipient. You can get this information from SOCK_GETIP().
dest_port% is the port from which the recipient reads.
The return value rv% indicates the number of bytes sent. If the value is -1, there was an error.
You can retrieve any error messages with NETGETLASTERROR$().
Common Commands
rv% = SOCK_RECV(sock%, BYREF msg$, length%)
With this function you read data from a TCP stream previously created with SOCK_TCPACCEPT() or SOCK_TCPCONNECT().
You can also use this function to receive UDP messages sent to a port previously bound with SOCK_UDPOPEN().
msg$ is the transmitted message, or empty in the case of an error.
length% specifies the maximum number of characters to be received.
The message is read until either the maximum length is reached or the first '\0' character is read. If you read binary data with INLINE, you have to check the return value to find the real length.
Since GLBasic uses non blocking sockets by default, there may be an error if the socket is not ready to receive data yet.
The return value could mean:
-2 : a non blocking socket is not ready to be read and would block. Try reading from that socket a bit later.
-1 : there was an error.
0 : the connected host has disconnected (only for TCP). As a result this socket is useless and must be closed with SOCK_CLOSE().
>0 : number of successfully read bytes.
You can retrieve any error messages with NETGETLASTERROR$().
ip% = SOCK_GETIP(server$)
Tries to get the IP address of the remote computer "server$".
server$ is a computer name - for example "www.glbasic.com" or "PC-GF".
The IP adress returned will be a 32-bit integer.
If nothing was found, 0 is returned.
ip$ = SOCK_GETIP$(ip%)
Converts an IP address (a 32-bit integer) returned from SOCK_GETIP() into a readable IP string like: "127.0.0.1".
rv% = SOCK_CLOSE(sock%)
Closes a socket once it is no longer required. Ensure you do not try to use it after it has been closed as GLBasic will reuse the socket number for new connections very quickly.
The return value is TRUE if no error occurs.
You can retrieve any error messages with NETGETLASTERROR$().