Difference between revisions of "Rednet (API)"

From ComputerCraft Wiki
Jump to: navigation, search
m
(Events)
Line 78: Line 78:
 
! colspan="1" | Parameters
 
! colspan="1" | Parameters
 
|-
 
|-
! scope="row" | rednet_message
+
! scope="row" | [[Rednet_message_(event)|rednet_message]]
 
|Fired when a rednet message is received (can be used as alternative for rednet.receive())
 
|Fired when a rednet message is received (can be used as alternative for rednet.receive())
|{{type|number}} senderId, {{type|string}} message, {{type|number}} distance
+
|{{type|number}} senderId, {{type|string}} message, {{type|number}} distance / {{type|string}} protocol
 
|}
 
|}
  

Revision as of 05:21, 29 March 2014

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
Varies rednet.lookup(string protocol, string hostname) Searches the local network for systems registered with a matching name and/or protocol, and returns information including (but not always limited to) their IDs. 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.

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 )