Main sections
SOCK_...
Dieses Kapitel beschreibt die SOCK_ Befehle, mit denen man TCP und UDP Nachrichten direkt verschicken kann. Damit ist GLBasic endlich in der Lage die volle Netzwerkfunktinalität anderer Sprachen zu besitzen.
Die einfacheren Befehle NET... bestehen weiterhin, da sie für Spieleprogrammierer eine enorme Erleichterung darstellen.
Weitere Informationen zu Sockets findet man hier:
http://beej.us/guide/bgnet/
http://www.freebsd.org/doc/en/books/developers-handbook/sockets.html
ok% = SOCK_INIT()
Zunächste sollte dieser Befehl aufgerufen werden, um Netzwerkbefehle zu aktivieren. Unter Windows ruft das WSAStartup auf, und bereitet intern verwendeten Speicher. Der Rückgabewert ist TRUE bei Keinem oder FALSE, wenn ein Fehler auftrat.
Fehlercodes bekommt man mit NETGETLASTERROR$().
SOCK_SHUTDOWN
Werden die SOCK_ Befehle nicht mehr benutzt sollte man diesen Befehl für jedes SOCK_INIT einmal aufrufen bevor das Programm geschlossen wird.
sock% = SOCK_TCPLISTEN(port%)
Dieser Befehl erstellt einen socket() und bindet ihn an den lokalen port "port%". Von nun an "hört" has programm auf TCP Nachrichten auf diesen Port.
Der Rückgabewert ist ein Socket, oder -1 wenn ein Fehler auftritt.
Fehlercodes bekommt man mit NETGETLASTERROR$().
sock% = SOCK_TCPCONNECT(server$, port%)
Hiermit erstellt man einen Socket, der das Gegenstück zu SOCK_TCPLISTEN() darstellt. Der Socket versucht zum Server zu verbinden.
server$ ist hierbei ein Computername oder eine IP Adresse ("www.glbasic.com", "PC-GF", "129.128.0.25").
Mit port% gibt man an, auf welchen Port man auf dem Server etwas schicken möchte. Also der Port, auf den SOCK_TCPLISTEN "horcht".
Der Rückgabewert ist ein Socket, oder -1 wenn ein Fehler auftritt.
sock% = SOCK_TCPACCEPT(sock_listen%, ip%%)
Diese Funktion gibt einen gültigen Socket (<> -1) zurück, wenn ein anderer Prozess erfolgreich SOCK_TCPCONNECT() durchgefüht hat.
Man kann nun von diesem Socket lesen oder über ihn schreiben um mit dem anderen Prozess zu kommunizieren.
Benötigt man diese Verbindung nicht mehr, muss man SOCK_CLOSE() für diesen Socket aufrufen.
Auf die Ganzzahlen ip% wird die IP Adresse des entfernten Computers übertragen. Diese kann man z.B. für SOCK_UDPSEND verwenden, um an diesen Rechner UDP Nachrichten zu senden.
Mit SOCK_GETIP$() kann man diese IP in eine lesbare Form bringen.
rv% = SOCK_TCPSEND(dest_sock%, msg$)
Sendet eine Nachricht per TCP an einen verbundenen Socket, den man z.B. durch SOCK_TCPACCEPT() oder SOCK_TCPCONNECT() erhalten hat.
msg$ ist dabei der zu versendende Text. Es wird die Länge des Texts Zeichen versandt.
Der Rückgabewert rv% gibt die Anzahl der versandten Zeichen an. Bei -1 ist ein Fehler aufgetreten.
UDP Befehle
sock% = SOCK_UDPOPEN(port%)
Dieser Befehl erstellt einen Socket, der es ermöglicht UDP Nachrichten an den lokalen port% zu empfangen und an andere Rechner per UDP zu senden.
Der Rückgabewert ist ein Socket, oder -1 wenn ein Fehler auftritt.
Fehlercodes bekommt man mit NETGETLASTERROR$().
Die UDP Scokets in GLBasic haben immer SO_BROADCAST aktiviert. Es ist also möglich Broadcasts zu senden.
rv% = SOCK_UDPSEND(sockudp%, msg$, dest_ip%, dest_port%)
Sendet eine Nachricht per UDP über einen Socket, den man mit SOCK_UDPOPEN() erstellt hat.
msg$ ist dabei der zu versendende Text. Es wird exakt die Länge des Texts versandt. Es wird also kein abschließendes '\0' Zeichen mitgesandt, wie das für viele TCP Applikationen üblich ist.
dest_ip% ist die IP Adresse des Empfängers. Man erhält sie mit SOCK_GETIP().
dest_port% ist der Port von dem der Empfänger liest.
Der Rückgabewert rv% gibt die Anzahl der versandten Zeichen an. Bei -1 ist ein Fehler aufgetreten.
Allgemeine Befehle
rv% = SOCK_RECV(sock%, msg$$, length%)
Mit dieser Funktion kann man Daten über einen TCP Stream empfangen, den man mit SOCK_TCPACCEPT() oder SOCK_TCPCONNECT() erhalten hat.
Diese Funktion empfängt auch UDP Nachrichten, die an einen Port gesandt werden an den ein SOCK_UDPOPEN() gebunden wurde.
msg$ enthält nach dem Datenempfang die übertragene Nachricht oder ist im Fehlerfall leer.
length% gibt an, wieviele Zeichen maximal empfangen werden sollen.
Die Nachricht erhält die Länge bis zum ersten '\0' Zeichen. Wenn per INLINE Binärdaten gesendet werden, ist die Auswertung des Rückgabewertes informativ.
Da GLBasic standartmäßig nicht-blockierende Sockets verwendet, kann ein Fehler auftreten, wenn der Socket noch nicht bereit ist Daten zu empfangen.
Der Rückgabewert kann folgendes bedeuten:
-2 : Ein nicht-blockierender Socket ist noch nicht bereit gelesen zu werden und würde somit blockieren. Bitte diesen Socket in einiger Zeit nochmal lesen.
-1 : Es ist ein Fehler aufgetreten.
0 : Die Gegenstelle wurde getrennt (nur für TCP). Dieser Socket ist damit unnütz und muss mit SOCK_CLOSE() geschlossen werden.
>0 : Die Anzahl der emfangenen Zeichen (Bytes).
ip% = SOCK_GETIP(server$)
Versucht die IP Addresse des Rechners "server$" zu erhalten.
server$ ist hierbei ein Computername oder eine IP Adresse ("www.glbasic.com", "PC-GF", "129.128.0.25").
Wird nichts gefunden, erhält man den Wert 0 zurück.
ip$ = SOCK_GETIP$(ip%)
Konvertiert eine IP Adresse, die man mit SOCK_GETIP() oder SOCK_ACCEPT() erhalten hat, in ein lesbares Format: z.B. "127.0.0.1".
rv% = SOCK_CLOSE(sock%)
Schließt einen Socket der nicht mehr benötigt wird. Es darf anschließend nicht mehr verwendet werden, da GLBasic ihn beim Esrtellen eines neuen Sockets wiederverwenden wird.
Der Rückgabewert ist TRUE, wenn kein Fehler auftritt.