[How to use] Kilobyte's Pheripherals' sockets

Presentation :

My main purpose writing it is to learn how to use it myself and share as I write it


Webinterface :

WebInterfaces is the pheripheral used to access sockets. You can use it directly by placing it next to a Computer OR combine it to a turtle to make an "Internet turtle"

Crafting it requires 7 stones, 1 diamond, and a modem -> You put the diamond in the center, the modem underneath and you place stone in to fill the reste of the slots

http://puu.sh/1QxKE

How to access and use?

First of all, you need to wrap the peripheral :

socket = peripheral.wrap(side)

- "socket" is a name I choose, you can put whatever you like
- peripheral.wrap() is the method to wrap a peripheral, so you can access its own methods
- side is the side where the WebInterface is (possible values are "front", "back", "top", "bottom", "left", "right")

Now we can access all the methods below prefixing it with "socket."

socket.registerHandle(String handle)
- Register an handle (a string that identifies the socket). You can call it whatever you like

socket.registerHandle("MySocket")

socket.unregisterHandle(String handle)
- Basically does the opposite of the register, you give it the name of the handle, and it unregisters it

socket.unregisterHandle("MySocket")

/!\ You are limited (by default) to 10 sockets per webinterface

socket.subscribeEvent(String handle, String event)
- "It actually enables you to receive events, i highly recommend to subscribe the event "text" for every new connection unless you only want to send data."

socket.subscribeEvent("MySocket", "text")

socket.unsubscribeEvent(String handle, String event)
- Unregisters an event you had registered with "socket.subscribeEvent()"

socket.unsubscribeEvent("MySocket", "text")

socket.connect(String handle, String ip, int port, bool SSL)
- Connects to a listening socket (So basically you are the client and you connect to a server).
- The handle is the same as the one you registered using registerHandle(String handle)
- The ip is the destination socket's adress (I.E : 173.194.78.94 (One of Google's servers))
- The port is the destination socket's listening port (If we want to connect to the webserver we'd say "80")
- The SSL bool isn't doing anything at the moment you can give him FALSE

socket.connect("MySocket", "173.194.78.94", 80, false)

socket.disconnect(String handle)
- Disconnects the socket we previously connected (The handle given is the one we gave to the connect method)

socket.disconnect("MySocket")

socket.disconnectAll()
- Disconnects all the sockets linked to that WebInterface

socket.disconnectAll()

socket.clearHandles()
- Does the same as unregisterHandle but with ALL the handles

socket.clearHandles()

socket.writeLine(String Handle, String content)
- Sends "content" through the socket identified by "Handle"

socket.writeLine("MySocket", "Hey, socket is working !")

Note : : All the methods return 2 values depending on errors : First one is the Err number second one is the string describing it

ERR_CONNECTED = -1   Already connected
ERR_NOT_CONNECTED = -2   No Connection etablished
ERR_INVALID_HANDLE = -3   Handle not registered
ERR_WRONG_OWNER = -4   Currently unused
ERR_UNKNOWN_HOST = -5   Can''t connect because host not avaible
ERR_CANT_CONNECT = -6   Other connection error
ERR_UNKNOWN = -7   Unknown error occured
ERR_INSUFFICANT_ARGS = -8   Wrong param number passed

How do we read what is sent through the socket? What method?

To read a socket, we do something a little bit different, we listen to triggered events.
Different events are pulled by the peripheral here is a list I'll complete when I'll know them all :

"socket_line_received"   Tells you a line has been received through the socket
"socket_remote_closed"   Tells you the socket has been remotely closed

And here's a little example on how to read :

-- Waits for a line to be received
local function readLine()
  while true do
	e, p1, p2 = os.pullEvent()
	if e == "socket_line_received" then
	  return p2
	elseif e == "socket_remote_closed" then
	  return nil
	end
  end
end

Note : To make it trigger socket_line_received you need to register "text" event (See above)


Credits :
Kilobyte - Dev of the peripheral, and (really) helped me write this tutorial

Nice! One thing though… Could you have a functin return a userdata, so we could just do handle:write() or whatever?