API/internet - Revision history

SoraFirestorm: Fix link to Internet Card component API

2026-09-01T19:12:54Z

Fix link to Internet Card component API

← Older revision		Revision as of 19:12, 1 September 2026
Line 1:		Line 1:
	= Internet API =		= Internet API =

	This library wraps functionality of Internet cards. Also see the [[Component~~/internet~~\|Internet Component]] for more low level functionality (such as querying availability of HTTP and TCP functionality).		This library wraps functionality of Internet cards. Also see the [[Internet Card#Component API\|Internet Component]] for more low level functionality (such as querying availability of HTTP and TCP functionality).

	'''NOTE''': It is not possible to create a listening interface on a port. OC can only connect directly to a server to send and receive messages.		'''NOTE''': It is not possible to create a listening interface on a port. OC can only connect directly to a server to send and receive messages.

Michiyo: Clean up Markdown artifacts from DokuWiki migration

2026-08-24T20:26:44Z

Clean up Markdown artifacts from DokuWiki migration

← Older revision		Revision as of 20:26, 24 August 2026
Line 5:		Line 5:
	'''NOTE''': It is not possible to create a listening interface on a port. OC can only connect directly to a server to send and receive messages.		'''NOTE''': It is not possible to create a listening interface on a port. OC can only connect directly to a server to send and receive messages.

	* `internet.request(url: string[, data: string or table[, headers: table[, method: string]]]): function`		* <code>internet.request(url: string[, data: string or table[, headers: table[, method: string]]]): function</code>

	<pre>Sends an HTTP request to the specified URL, with the specified POST data, if any. If no data is specified, a GET request will be made. The POST data can be in one of two formats: if it's a string, it will be sent as-is. If it's a table, it will be converted to a string by assuming that each key is the name of a POST variable, and it's associated value is the value for that variable. method can be explicitly specified to values such as GET, POST, or PUT. Some examples:		<pre>Sends an HTTP request to the specified URL, with the specified POST data, if any. If no data is specified, a GET request will be made. The POST data can be in one of two formats: if it's a string, it will be sent as-is. If it's a table, it will be converted to a string by assuming that each key is the name of a POST variable, and it's associated value is the value for that variable. method can be explicitly specified to values such as GET, POST, or PUT. Some examples:
	`internet.request(url, {some = "variable", another = 1})`		internet.request(url, {some = "variable", another = 1})
	Will send `some=variable&another=1`.		Will send some=variable&another=1.
	The returned function is an iterator over chunks of the result, use it like so:		The returned function is an iterator over chunks of the result, use it like so:
	`for chunk in internet.request(...) do stuff() end`		for chunk in internet.request(...) do stuff() end
	Note that this method ALSO support HTTPS. So simply use		Note that this method ALSO support HTTPS. So simply use
	`internet.request("https://example.com")` to send a request through HTTPS.		internet.request("https://example.com") to send a request through HTTPS.

	Example specifying PUT:		Example specifying PUT:
	`internet.request("https://example.com", "put data", {}, "PUT")`.		internet.request("https://example.com", "put data", {}, "PUT").
	</pre>		</pre>
	* `internet.socket(address:string[, port:number]):table`		* <code>internet.socket(address:string[, port:number]):table</code>

	<pre>Opens a TCP socket using an internet component's `connect` method and wraps it in a table that provides the same methods as a file opened using `filesystem.open`: `read`, `write` and `close` (and `seek`, which will always fail). It is recommended to use `internet.open` instead, which will wrap the opened socket in a [[API/buffer\|buffer]], the same way `io.open` wraps files.		<pre>Opens a TCP socket using an internet component's connect method and wraps it in a table that provides the same methods as a file opened using filesystem.open: read, write and close (and seek, which will always fail). It is recommended to use internet.open instead, which will wrap the opened socket in a [[API/buffer\|buffer]], the same way io.open wraps files.
	The read method on the returned socket is ''non-blocking''. Read will instantly return, but may return an empty string if there is nothing to read. Write ''may'' block until all data has been successfully written. It'll ''usually'' return immediately, though.		The read method on the returned socket is ''non-blocking''. Read will instantly return, but may return an empty string if there is nothing to read. Write ''may'' block until all data has been successfully written. It'll ''usually'' return immediately, though.
	</pre>		</pre>
	* `internet.open(address:string[, port:number]):table`		* <code>internet.open(address:string[, port:number]):table</code>

	<pre>Opens a buffered socket stream to the specified address. The stream can be read from and written from, using `s:read` and `s:write` - in general it can be treated much like files opened using `io.open`. It may often be desirable to set the buffer's read timeout using `s:setTimeout(seconds)`, to avoid it blocking indefinitely.		<pre>Opens a buffered socket stream to the specified address. The stream can be read from and written from, using s:read and s:write - in general it can be treated much like files opened using io.open. It may often be desirable to set the buffer's read timeout using s:setTimeout(seconds), to avoid it blocking indefinitely.
	The read method on the returned buffer is ''blocking''. Read will wait until some data is available to be read and return that.		The read method on the returned buffer is ''blocking''. Read will wait until some data is available to be read and return that.
	</pre>		</pre>
	Example usage:		Example usage:

	~~```~~lua local internet = require("internet") local handle = internet.open("example.com", 1337) local data = handle:read(10) handle:write("1234") handle:close() ~~```~~ If you need the HTTP response code, message, and headers, they are retrieved from the internal object, which is stored in the metatable of the returned object. ~~```~~lua -- https://github.com/kikito/inspect.lua/blob/master/inspect.lua local inspect = require("inspect") local internet = require("internet")		<syntaxhighlight lang="lua">
			local internet = require("internet") local handle = internet.open("example.com", 1337) local data = handle:read(10) handle:write("1234") handle:close()
			</syntaxhighlight> If you need the HTTP response code, message, and headers, they are retrieved from the internal object, which is stored in the metatable of the returned object. <syntaxhighlight lang="lua">
			-- https://github.com/kikito/inspect.lua/blob/master/inspect.lua local inspect = require("inspect") local internet = require("internet")

	local handle = internet.request("https://www.google.com") local result = "" for chunk in handle do result = result..chunk end -- Print the body of the HTTP response -- print(result)		local handle = internet.request("https://www.google.com") local result = "" for chunk in handle do result = result..chunk end -- Print the body of the HTTP response -- print(result)
Line 36:		Line 39:
	-- Grab the metatable for the handle. This contains the -- internal HTTPRequest object. local mt = getmetatable(handle)		-- Grab the metatable for the handle. This contains the -- internal HTTPRequest object. local mt = getmetatable(handle)

	-- The response method grabs the information for -- the HTTP response code, the response message, and the -- response headers. local code, message, headers = mt.__index.response() print("code = "..tostring(code)) print("message = "..tostring(message)) print(inspect(headers)) ~~```~~		-- The response method grabs the information for -- the HTTP response code, the response message, and the -- response headers. local code, message, headers = mt.__index.response() print("code = "..tostring(code)) print("message = "..tostring(message)) print(inspect(headers))
			</syntaxhighlight>

	This is an example of a basic IRC bot that echos back what you say to it, using the sockets in the internet api. ~~```~~lua --this is just a basic split function we'll use to split the messages function split(data, pat)		This is an example of a basic IRC bot that echos back what you say to it, using the sockets in the internet api. <syntaxhighlight lang="lua">
			--this is just a basic split function we'll use to split the messages function split(data, pat)

	~~<pre>~~ local ret = {}		local ret = {}
	for i in string.gmatch(data,pat) do		for i in string.gmatch(data,pat) do
	table.insert(ret,i)		table.insert(ret,i)
	end		end
	return ret		return ret
	~~</pre>~~
	end --config local nickname = "myircbot" local channel = "#mybotchannel"		end --config local nickname = "myircbot" local channel = "#mybotchannel"

	local net = require("internet") local con = net.open("irc.esper.net",6667) --define server / port here, this will connect to the server if(con) then		local net = require("internet") local con = net.open("irc.esper.net",6667) --define server / port here, this will connect to the server if(con) then

	~~<pre>~~ local line,png,linesplt,msgfrom = ""		local line,png,linesplt,msgfrom = ""
	while(true) do		while(true) do
	line = con:read() --read a line from the socket		line = con:read() --read a line from the socket
Line 70:		Line 75:
	end		end
	end		end
	~~</pre>~~
	else		else

	~~<pre>~~ print("Connection failed.")		print("Connection failed.")
	</~~pre~~>
	~~end ```~~		end
			</syntaxhighlight>

	For a more advanced example, check out the IRC Client program available in the latest release of OpenComputers: [~~irc.lua](~~https://github.com/MightyPirates/OpenComputers/blob/master-MC1.7.10/src/main/resources/assets/opencomputers/loot/irc/usr/bin/irc.lua)		For a more advanced example, check out the IRC Client program available in the latest release of OpenComputers: [https://github.com/MightyPirates/OpenComputers/blob/master-MC1.7.10/src/main/resources/assets/opencomputers/loot/irc/usr/bin/irc.lua irc.lua]

	== Contents ==		== Contents ==

	{{:API/contents}}		{{:API/contents}}

imported>OCDoc Import: Imported from legacy OpenComputers documentation at ocdoc.cil.li

2026-08-24T08:08:27Z

Imported from legacy OpenComputers documentation at ocdoc.cil.li

New page

= Internet API =

This library wraps functionality of Internet cards. Also see the [[Component/internet|Internet Component]] for more low level functionality (such as querying availability of HTTP and TCP functionality).

'''NOTE''': It is not possible to create a listening interface on a port. OC can only connect directly to a server to send and receive messages.

* `internet.request(url: string[, data: string or table[, headers: table[, method: string]]]): function`

<pre>Sends an HTTP request to the specified URL, with the specified POST data, if any. If no data is specified, a GET request will be made. The POST data can be in one of two formats: if it's a string, it will be sent as-is. If it's a table, it will be converted to a string by assuming that each key is the name of a POST variable, and it's associated value is the value for that variable. **method** can be explicitly specified to values such as GET, POST, or PUT. Some examples:
`internet.request(url, {some = "variable", another = 1})`
Will send `some=variable&another=1`.
The returned function is an iterator over chunks of the result, use it like so:
`for chunk in internet.request(...) do stuff() end`
Note that **this method ALSO support HTTPS**. So simply use
`internet.request("https://example.com")` to send a request through HTTPS.

Example specifying PUT:
`internet.request("https://example.com", "put data", {}, "PUT")`.
</pre>
* `internet.socket(address:string[, port:number]):table`

<pre>Opens a TCP socket using an internet component's `connect` method and wraps it in a table that provides the same methods as a file opened using `filesystem.open`: `read`, `write` and `close` (and `seek`, which will always fail). It is recommended to use `internet.open` instead, which will wrap the opened socket in a [[API/buffer|buffer]], the same way `io.open` wraps files.
The read method on the returned socket is ''non-blocking''. Read will instantly return, but may return an empty string if there is nothing to read. Write ''may'' block until all data has been successfully written. It'll ''usually'' return immediately, though.
</pre>
* `internet.open(address:string[, port:number]):table`

<pre>Opens a buffered socket stream to the specified address. The stream can be read from and written from, using `s:read` and `s:write` - in general it can be treated much like files opened using `io.open`. It may often be desirable to set the buffer's read timeout using `s:setTimeout(seconds)`, to avoid it blocking indefinitely.
The read method on the returned buffer is ''blocking''. Read will wait until some data is available to be read and return that.
</pre>
Example usage:

```lua local internet = require("internet") local handle = internet.open("example.com", 1337) local data = handle:read(10) handle:write("1234") handle:close() ``` If you need the HTTP response code, message, and headers, they are retrieved from the internal object, which is stored in the metatable of the returned object. ```lua -- https://github.com/kikito/inspect.lua/blob/master/inspect.lua local inspect = require("inspect") local internet = require("internet")

local handle = internet.request("https://www.google.com") local result = "" for chunk in handle do result = result..chunk end -- Print the body of the HTTP response -- print(result)

-- Grab the metatable for the handle. This contains the -- internal HTTPRequest object. local mt = getmetatable(handle)

-- The response method grabs the information for -- the HTTP response code, the response message, and the -- response headers. local code, message, headers = mt.__index.response() print("code = "..tostring(code)) print("message = "..tostring(message)) print(inspect(headers)) ```

This is an example of a basic IRC bot that echos back what you say to it, using the sockets in the internet api. ```lua --this is just a basic split function we'll use to split the messages function split(data, pat)

<pre> local ret = {}
for i in string.gmatch(data,pat) do
table.insert(ret,i)
end
return ret
</pre>
end --config local nickname = "myircbot" local channel = "#mybotchannel"

local net = require("internet") local con = net.open("irc.esper.net",6667) --define server / port here, this will connect to the server if(con) then

<pre> local line,png,linesplt,msgfrom = ""
while(true) do
line = con:read() --read a line from the socket
print(line)
linesplt = split(line,"[^:]+")
if #linesplt >= 2 and string.find(linesplt[2], "No Ident response") ~= nil then
print("JOIN")
con:write("USER " .. nickname .. " 0 * :" .. nickname .. "\r\n") --con:write(msg) is used to send messages, con:read() will read a line
con:write("NICK " .. nickname .. "\r\n") --for IRC, remember to append the \r\n on the end of all messages
con:write("JOIN :" .. channel .. "\r\n")
elseif linesplt[1] == "PING" or linesplt[1] == "PING " then
print("PING")
png = split(line,"[^:]+")
con:write("PONG :"..png[#png].."\r\n") --respond to pings so we don't get disconnected
elseif string.find(linesplt[1], "PRIVMSG #") ~= nil then
msgfrom = split(linesplt[1],"[^ ]+")
msgfrom = msgfrom[3]
con:write("PRIVMSG "..msgfrom.." :"..linesplt[2].."\r\n")
end
end
</pre>
else

<pre> print("Connection failed.")
</pre>
end ```

For a more advanced example, check out the IRC Client program available in the latest release of OpenComputers: [irc.lua](https://github.com/MightyPirates/OpenComputers/blob/master-MC1.7.10/src/main/resources/assets/opencomputers/loot/irc/usr/bin/irc.lua)

== Contents ==

{{:API/contents}}