Rednet (API)

From ComputerCraft Wiki
Revision as of 21:32, 1 June 2014 by MKlegoman357 (Talk | contribs) (API: Recreated using {{API table}} tag)

Jump to: navigation, search
This page needs some serious TLC, stat!
Please help us by cleaning it, fixing it up, or sparing it some love.
(Reason: Could use more information re protocols outside of the API section. - BB)
Please Note
Rednet no longer supports transmitting data through Bundled Cables. However, interacting with Bundled Cables is still available via the Redstone API.

The Rednet API allows computers to communicate between themselves without using redstone wires. In order to send and receive data, a modem is required. The data is received immediately after sending it, but only by computers within a certain range. That range depends on the altitude of the sending computer increasing with higher altitudes to a max of 384. NOTE: The distance variable that is sent/received through the Rednet API is based off of the computer location, not the modem location.

API

Returns Method name Description Min version
rednet.open(string side) Tells the computer that the side can be used for networking.
rednet.close(string side) Tells the computer that the side can no longer be used for networking.
rednet.announce() Broadcasts an empty rednet message. Removed from ComputerCraft by version ??? in favour of rednet.broadcast().
rednet.send(number receiverID, string message, [string protocol]) Sends a message "intended" for another system with a specific ID, using the currently opened sides. The receiver ID is the ID number (note - not a string) of the computer you're sending the message to. Later versions or ComputerCraft allow some other data types as the message.
rednet.broadcast(string message, [string protocol]) Sends the message to ALL connected and open computers.
number senderID, string message, number distance / string protocol rednet.receive([string protocolFilter], [number timeout]) Waits until it received a rednet message of the specified protocol has been received, or until timeout seconds have passed. Leave args empty to wait for any message indefinitely. If only a single, numerical argument is passed, will wait that many seconds for a message of any protocol. Versions of ComputerCraft prior to 1.6 may return the distance to the transmitting computer - 1.6 or later returns message protocols instead, though distance can still be obtained via direct use of the Modem API.
boolean isOpen rednet.isOpen(string side) Returns true if the wireless modem is open.
rednet.host(string protocol, string hostname) Registers hostname against protocol for the purposes of rednet.lookup(). 1.6
rednet.unhost(string protocol, string hostname) Unregisters hostname from protocol. 1.6
number ID1, number ID2, ... rednet.lookup(string protocol, string hostname) Searches the local network for systems registered with a matching name and/or protocol, and returns matching IDs found. 1.6
rednet.run() Internal use function - runs automatically and need not be called directly. Waits for modem_message events to appear within the event queue and generates corresponding rednet_message events for use with this API. Also responds to rednet.lookup() requests.


Grid disk.png  rednet (API)
Function Return values Description
rednet.open(string side) nil Tells the computer that the side can be used for networking.
rednet.close(string side) nil Tells the computer that the side can no longer be used for networking.
rednet.announce() nil Broadcasts an empty rednet message. Removed from ComputerCraft by version 1.5 in favor of rednet.broadcast()
rednet.send(number receiverID, string message, [string protocol]) nil Sends a message "intended" for another system with a specific ID, using the currently opened sides. The receiverID is the ID number (note - not a string) of the computer you're sending the message to. Later versions or ComputerCraft allow some other data types as the message.
rednet.broadcast(string message, [string protocol]) nil Sends the message to all connected and open computers.
rednet.receive([string protocolFilter[, number timeout]]) number senderID, string message, number distance / string protocol Waits until a rednet message of the specified protocol has been received, or until timeout seconds have passed. Leave all arguments empty to wait for any message indefinitely. If only a single, numerical argument is passed, will wait that many seconds for a message of any protocol. Versions of ComputerCraft prior to 1.6 may return the distance to the transmitting computer - 1.6 or later returns message protocols instead, though distance can still be obtained via direct use of the Modem API.
rednet.isOpen(string side) boolean isOpen Returns true if the wireless modem is open.
rednet.host(string protocol, string hostname) nil Registers hostname against protocol for the purposes of rednet.lookup(). Only available in ComputerCraft 1.6 and above.
rednet.unhost(string protocol, string hostname) nil Unregisters hostname from protocol. Only available in ComputerCraft 1.6 and above.
rednet.lookup(string protocol, string hostname) number ID1, number ID2, ... Searches the local network for systems registered with a matching hostname and/or protocol, and returns matching IDs found. Only available in ComputerCraft 1.6 and above.
rednet.run() nil Internal use function - runs automatically and does not need to be called directly. Waits for modem_message events to appear within the event queue and generates corresponding rednet_message events for use with this API. Also responds to rednet.lookup() requests.

Events

Event Name Description Parameters
rednet_message Fired when a rednet message is received (can be used as alternative for rednet.receive()) number senderId, string message, number distance / string protocol

History

Before the creation of the in-game wireless networking API, the term "Rednet" referred to a system created by one of the ComputerCraft users based on bundled cables from a popular Minecraft mod - RedPower. It also allowed communication between computers, but the data was transferred slowly - every bit was converted to redstone signal, that lasted about 0,05 seconds. On the release of ComputerCraft 1.3, the system became useless, as the wireless networking was officially implemented to the mod.

Security

ID Whitelists are useless, and messages sent by Rednet can be viewed by anyone, even if they are not the target computer.

Rednet alone is completely insecure. Any messages sent via rednet can actually be sniffed, contrary to popular belief, and people can pretend to be a certain computer and fool rednet easily.

Rednet simply utilizes the Modem API. A user can easily sniff and find out what messages a computer is receiving if he knows its ID. All he has to do is use the Modem API to listen, where the channel to listen on is the target computer's ID. Additionally, a malicious user can 'pretend' to be a certain computer by using the Modem API to send a message to the target computer's ID with the message, but using the ID of the computer to pretend to be for the reply channel parameter. If they do so, the computer receiving the message with rednet will be fooled into thinking it came from a different computer.

When using rednet for anything with security critical, be sure to implement your own security measures.

Technical Details

Overview: Rednet functions by having a modem listen on the channel of the computer's ID, and the rednet broadcast channel for messages. It uses the replyChannel parameter of the modem_message event as the sender computer's ID. It broadcasts by sending a simple modem message on the rednet broadcast channel, and receives by receiving a modem message on the broadcast channel or the channel of its computer's ID.

CHANNEL_BROADCAST: 65535

(local) tValidSides: Contains valid values of strings containing computer sides, used by open and close

rednet.open(sSide): Checks if sSide is a string, a valid side, and a side with a modem on it. Then it opens the modem on CHANNEL_BROADCAST and os.getComputerID()

rednet.close(sSide): Checks if sSide is a string, a valid side, and a side with a modem on it. Then it closes the modem on CHANNEL_BROADCAST and os.getComputerID()

rednet.isOpen(sSide): Checks if sSide is a string, a valid side, and a side with a modem on it. Then it returns true if the modem on sSide is open on both CHANNEL_BROADCAST and os.getComputerID()

rednet.send(nRecipient, sMessage): For each side sSide in rs.getSides(), it calls isOpen(sSide). If the result is true, it executes

peripheral.call( sSide, "transmit", nRecipient, os.getComputerID(), sMessage )

rednet.broadcast(sMessage): Calls send(CHANNEL_BROADCAST, sMessage)

rednet.receive(nTimeout): If nTimeout is there, it starts a timer for nTimeout seconds-stored in timer, and sets sFilter to nil. Otherwise, sFilter is set to "rednet_message". In a loop,

local e, p1, p2, p3, p4, p5 = os.pullEvent( sFilter )

is called. If e is "rednet_message" then it returns p1, p2, and p3, but if e is "timer", and p1 is timer then it returns nil.

(local) bRunning: false

rednet.run(): If bRunning is true, then it errors "rednet is already running". It then sets bRunning to true to indicate that it is running. Looping while bRunning, it pulls

local sEvent, sSide, sChannel, sReplyChannel, sMessage, nDistance = os.pullEventRaw( "modem_message" )

Then if sEvent is "modem_message", isOpen(sSide) is true, and sChannel is os.getComputerID() or it is CHANNEL_BROADCAST, then it queues

os.queueEvent( "rednet_message", sReplyChannel, sMessage, nDistance )