ComputerCraft Wiki - User contributions [en]

OS (API)

2014-01-05T11:29:52Z

LBPHacker: os.pullEvenRaw accepts the target-event parameter, just like os.pullEvent.

The Operating System API allows for interfacing with the Lua based Operating System itself.

{{API table|Os|image=Grid disk.png|2=

{{API table/row
|[[os.version]]()|{{type|string}} version
|Returns the version of the OS the computer is running, which (for CraftOS) also contains the version of ComputerCraft.
|odd}}

{{API table/row
|[[os.getComputerID]]()|{{type|number}} id
|Returns the unique ID of this computer. [[os.computerID]]() also behaves exactly the same as [[os.getComputerID]]().
|}}

{{API table/row
|[[os.getComputerLabel]]()|{{type|string}} label
|Returns the label of this computer. [[os.computerLabel]]() also behaves exactly the same as [[os.getComputerLabel]](). 
|odd}}

{{API table/row
|[[os.setComputerLabel]]({{type|string}} label)|{{type|nil}}
|Set the label of this computer.
|}}

{{API table/row
|[[os.run]]({{type|table}} environment, {{type|string}} program path [, {{type|string}} arguments])|{{type|nil}}
|An advanced way of starting programs. A started program will have a given <var>environment</var> table which determines what functions it has available, as well as any variables it will be able to access by default. You may prefer to use the [[Shell (API)]] unless you need to do something special.
|odd}}

{{API table/row
|[[#APIs|os.loadAPI]]({{type|string}} name)|{{type|nil}}
|Loads a Lua script as an API in its own namespace (see example). It will be available to '''all''' programs that run on the terminal.
|}}

{{API table/row
|[[#APIs|os.unloadAPI]]({{type|string}} name)|{{type|nil}}
|Unloads a previously loaded API.
|odd}}

{{API table/row
|[[Os.pullEvent|os.pullEvent]]({{type|string}}/{{type|nil}} target-event)|any
|Blocks until the computer receives an event, or if <var>target-event</var> is specified, will block until an instance of <var>target-event</var> occurs. [[Os.pullEvent|os.pullEvent]](target-event) returns the event and any parameters the event may have. If a <var>target-event</var> is specified, the computer will not break for any other events (except termination).
|}}

{{API table/row
|[[#pullEvent|os.pullEventRaw]]({{type|string}}/{{type|nil}} target-event)|any
|Advanced version of pullEvent(). Blocks until the computer receives an event, or if <var>target-event</var> is specified, will block until an instance of <var>target-event</var> occurs. [[#pullEvent|os.pullEventRaw]](target-event) returns the event and any parameters the event may have. Unlike [[Os.pullEvent|os.pullEvent]](target-event), this function will not raise an error if a 'terminate' event is received.
|odd}}

{{API table/row
|[[os.queueEvent]]({{type|string}} event, param1, param2, ...)|{{type|nil}}
|Adds an event to the event queue with the name <var>event</var> and the given parameters
|}}

{{API table/row
|[[os.clock]]()|{{type|number}} time
|Returns the amount of time since the computer was started.
|odd}}

{{API table/row
|[[os.startTimer]]({{Type|number}} timeout)|{{type|number}} timerID
|Queues an event to be triggered after a number of seconds (<var>timeout</var>). The ID of the timer is returned from this function to differentiate multiple timers. Timers are one-shot; once they have fired an event you will need to start another one if you need a recurring timer.
|}}

{{API table/row
|[[os.time]]()|{{type|number}} time
|Returns the current in-game time.
|odd}}

{{API table/row
|[[os.sleep]]({{Type|number}} time)|{{type|nil}}
|Makes the system wait a number of seconds before continuing in the program. [[os.sleep]](time) may also be used as simply "sleep(time)".
|}}

{{API table/row
|[[os.day]]()|{{type|number}} day
|Return the current in-game day (the number of days since the world was created).
|odd}}

{{API table/row
|[[os.setAlarm]]({{type|number}} time)|{{type|number}} alarmID
|Queues an event to be triggered at the specified in-game <var>time</var>.
|}}

{{API table/row
|[[os.shutdown]]()|{{type|nil}}
|Turns off the computer.
|odd}}

{{API table/row
|[[os.reboot]]()|{{type|nil}}
|Reboots the computer.
|}}

}}

[[Category:APIs]]

== APIs ==

APIs are Lua files which are loaded into the OS itself, and expose functions which other programs may use. The stock [[:Category:APIs|APIs]] that ship with ComputerCraft are loaded in this way, and may be replaced by a computer’s user or programs.

The following is an example of a valid implementation of an API, and its usage after being registered:
<code>
-- "apiTest" file
function foo(bar)
print(bar)
end

-- "program" file
os.loadAPI("apiTest")
apiTest.foo("this is a test")
</code>

== <div id="pullEvent">os.pullEvent()</div> ==

os.pullEvent() causes the current program to pause, retrieving the next event from the computer's queue of events. If there is no event to read, then the program will stall until such an event becomes available. Note that if a program has not attempted to pull an event in the past ten seconds, it will be forcefully terminated to prevent CPU waste in SMP environments.

os.pullEvent() returns the name of the event that was read, as well as up to five parameters:
<code>
local event, p1, p2, p3, p4, p5 = os.pullEvent()
</code>

os.pullEvent() is usually run inside a 'while true do' loop.

An advanced version of this method <code>os.pullEventRaw</code> bypasses the normal handling of events from the OS. You may use this to act on the "Terminate" event (triggered when holding Ctrl-T) for custom termination logic.

Modem.isOpen

2014-01-05T11:22:27Z

LBPHacker: Added " |returns={{type|bool}} isOpen " line.

{{Function
|name=modem.isOpen
|args={{type|int}} channel
|returns={{type|bool}} isOpen
|api=Modem
|addon=ComputerCraft
|desc=Checks whether or not a certain channel is open.
|examples=
{{Example
|desc=Checks whether the computer is listening on this channel.
|code=modem.isOpen(1)
}}
}}

Computer (API)

2013-09-08T13:37:43Z

LBPHacker: Stating that computer.getID returns nothing if the observed computer/turtle is not running.

'''''computer'' stands for the variable you wrapped the computer to.'''
''Example:'' computer = peripheral.wrap( "top" )

{| class="wikitable"
!Method name
!Description
|-
|computer.turnOn()
|Turns on the Computer or Turtle.
|-
|computer.shutdown()
|Shuts off the Computer or Turtle.
|-
|computer.reboot()
|Reboots the Computer or Turtle.
|-
|computer.getID()
|Gets the ID of the Computer or Turtle if it is running, otherwise returns nothing.
|}

[[Category: Peripheral APIs]]

Rednet (API)

2013-09-04T07:40:05Z

LBPHacker: Some grammar (like "its" vs. "it's")

{{msgbox
|title=Please Note
|text=As of ComputerCraft 1.5, [[Modem_(API)|channels]] have been added, and no longer supports<br>transmitting data through Bundled Cables. However interacting with Bundled Cables is still available via the [[Redstone_(API)|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.

<table style="width: 100%; border: solid 1px black; margin: 2px; border-spacing: 0px;">
<tr><td colspan="2" style="font-weight: bold; font-size: large; padding-bottom: .3em; border-bottom: solid #C9C9C9 1px; background: #D3FFC2; line-height:28px;">
[[File:Grid_disk.png|24px]]  
Rednet (API)
</td></tr>

<tr><td style="width: 350px; background: #E0E0E0; padding: .4em; font-weight:bold;">Method Name</td><td style="background: #E0E0E0; padding: .4em; font-weight:bold;">Description</td></tr>

<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[rednet.open]]({{type|string}} side)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Tells the computer that the side can be used for networking.</td></tr>

<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[rednet.close]]({{type|string}} side)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Tells the computer that the side can no longer be used for networking.</td></tr>

<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[rednet.announce]]()</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Broadcasts an empty rednet message.</td></tr>

<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[rednet.send]]({{type|number}} receiverID, {{type|string}} message)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Sends a message to the computer using the opened sides. The receiver ID is the ID (number, not string) of the computer you're sending the message to. ID as nil will do the same as a broadcast. The message must be a string to send across rednet, if you are wanting to send a table see [[textutils.serialize]]</td></tr>

<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[rednet.broadcast]]({{type|string}} message)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Sends the message to ALL connected and open computers.</td></tr>

<tr style="background-color: #E8E8E8;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[rednet.receive]]({{type|number}} timeout)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Waits until it received a rednet message or <var>timeout</var> has passed. Leave args empty to wait for a message forever.</td></tr>

<tr style="background-color: #FFFFFF;"><td style="border-top: solid #C9C9C9 1px; padding: .4em;">[[rednet.isOpen]]({{type|string}} side)</td>
<td style="border-top: solid #C9C9C9 1px; padding: .4em;">Returns true if the wireless modem is open.</td></tr>
</table>

==Events==
{| class="wikitable" width="100%"
! colspan="1" | Event Name
! colspan="1" | Description
! colspan="1" | Parameters
|-
! scope="row" | rednet_message
|Fired when a rednet message is received (can be used as alternative for rednet.receive())
|{{type|number}} senderId, {{type|string}} message, {{type|number}} distance
|}

==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)|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 )

[[Category:APIs]]

Os.setAlarm

2013-07-27T03:43:38Z

LBPHacker: Replacing os.startAlarm with os.setAlarm in the example.

{{lowercase}}
{{Function
|name=os.setAlarm
|args={{type|number}} time
|api=OS
|returns={{type|table}} alarmID
|addon=ComputerCraft
|desc=Adds an alarm which will fire an "alarm" event at the specified Minecraft world time. The returned table acts as a unique ID for the alarm.
|examples=
}}
== Explanation ==
([http://www.computercraft.info/forums2/index.php?/topic/5599-ossetalarm/page__view__findpost__p__46168 Forum Post] by jag_e_nummer_ett:)

<code>
--(( Basic format ))--
os.setAlarm(time)
--(( Will timeout when it's 18 o'clock in the world ))--
os.setAlarm(18.00)
--(( Will timeout 2 (in-game) hours later ))--
os.setAlarm(os.time()+2)
--(( Basic event layout ))--
local ev,p1 = os.pullEvent("alarm")
--(( Event output ))--
Name: alarm
Parameter 1: A table that acts like it's unique ID
</code>

== Example ==
([http://www.computercraft.info/forums2/index.php?/topic/5599-ossetalarm/page__view__findpost__p__46167 Forum Post] by MysticT):

<code>
local alarm = os.setAlarm(5)
while true do
local evt, arg = os.pullEvent("alarm")
if arg == alarm then
print("It's 5:00, wake up!")
end
end
</code>

[[Category:Lua_Core_Functions]]

Talk:Coroutine.yield

2012-12-03T09:16:21Z

LBPHacker: Created page with "So it says 'coroutine.yield(coroutine, var1, var2, ...)' stops the coroutine ''coroutine'', while the Coroutine API page says coroutine.yield() can only stop the running corou..."

So it says 'coroutine.yield(coroutine, var1, var2, ...)' stops the coroutine ''coroutine'', while the Coroutine API page says coroutine.yield() can only stop the running coroutine. Anyways, I have one question. Can I yield a coroutine from another coroutine?

LBPHacker