Difference between revisions of "Modem (API)"
From ComputerCraft Wiki
(Added peripheral API message) |
MKlegoman357 (Talk | contribs) m (Recreated method function table using {{API table}} tag, event table uning {{Event}} tag, linked functions in examples) |
||
| Line 3: | Line 3: | ||
{{PeripheralAPI}} | {{PeripheralAPI}} | ||
| − | Modem channels are essentially networks which can be opened, closed and listened on by any | + | Modem channels are essentially networks which can be [[modem.open|opened]], [[modem.close|closed]] and [[modem_message_(event)|listened]] on by any [[Computer]] within range, without need of independant computer IDs. To interact with channels, one must [[peripheral.wrap|wrap]] or interact directly with the peripheral as opposed to the previous interaction with the [[Rednet_(API)|Rednet API]]. |
| − | + | This is not an actual API called "modem". This is the API for [[peripheral.wrap|wrapped]] modem peripherals. | |
| − | + | {{API table|Modem|image=Grid disk.png|2= | |
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | {{API table/row | |
| + | |[[modem.isOpen|''modem''.isOpen]]({{type|number}} channel) | ||
| + | |{{type|boolean}} isChannelOpen | ||
| + | |Checks to see if ''channel'' is open. | ||
| + | |odd}} | ||
| − | + | {{API table/row | |
| − | + | |[[modem.open|''modem''.open]]({{type|number}} channel) | |
| + | |{{type|nil}} | ||
| + | |Opens ''channel'' to allow for listening. The channel specified must be larger than 0 and less than 65535.}} | ||
| − | + | {{API table/row | |
| − | + | |[[modem.close|''modem''.close]]({{type|number}} channel) | |
| + | |{{type|nil}} | ||
| + | |Closes an open channel to disallow listening. | ||
| + | |odd}} | ||
| − | + | {{API table/row | |
| − | + | |[[modem.closeAll|''modem''.closeAll]]() | |
| + | |{{type|nil}} | ||
| + | |Closes all open channels.}} | ||
| − | + | {{API table/row | |
| − | + | |[[modem.transmit|''modem''.transmit]]({{type|number}} channel, {{type|number}} replyChannel, {{type|string}} message) | |
| + | |{{type|nil}} | ||
| + | |Transmits a message on the specified channel. | ||
| + | |odd}} | ||
| − | + | {{API table/row | |
| − | + | |[[modem.isWireless|''modem''.isWireless]]() | |
| + | |{{type|bollean}} isWireless | ||
| + | |Returns if the modem is wireless or wired.}} | ||
| − | + | }} | |
| − | + | ||
| − | + | {{Event | |
| − | { | + | |name=modem_message |
| − | + | |return1={{type|string}} modemSide | |
| − | + | |return2={{type|number}} senderChannel | |
| − | + | |return3={{type|number}} replyChannel | |
| − | | | + | |return4={{type|string}} message |
| − | + | |return5={{type|number}} distance | |
| − | + | |desc=Fired when a modem message is received.}} | |
| − | + | ||
| − | |} | + | |
==Sending Messages== | ==Sending Messages== | ||
Sending messages is simple and does not require that you open any channels. Simply use the transmit function like so: | Sending messages is simple and does not require that you open any channels. Simply use the transmit function like so: | ||
| − | local modem = peripheral.wrap("right") --Wraps the modem on the right side. | + | local modem = [[peripheral.wrap]]("right") --Wraps the modem on the right side. |
| − | modem.transmit(3, 1, "Hello world!") | + | |
| − | peripheral.call("right", "transmit", 3, 1, "This will also work!") | + | [[modem.transmit]](3, 1, "Hello world!") |
| + | [[peripheral.call]]("right", "transmit", 3, 1, "This will also work!") | ||
| − | What did that do? First I wrapped the peripheral in order to interact with it. Second, I used modem.transmit(channel, replyChannel, message) in order to send my message. In case you were wondering, the reply channel is captured by the listening computer and suggests which channel they should reply on. | + | What did that do? First I wrapped the peripheral in order to interact with it. Second, I used [[modem.transmit]](channel, replyChannel, message) in order to send my message. In case you were wondering, the reply channel is captured by the listening computer and suggests which channel they should reply on. |
==Receiving Messages== | ==Receiving Messages== | ||
Receiving messages requires that you be familiar with events. As of this moment, there is no API which cuts out events from the process. Here is an example of how to receive messages: | Receiving messages requires that you be familiar with events. As of this moment, there is no API which cuts out events from the process. Here is an example of how to receive messages: | ||
| − | local modem = peripheral.wrap("left") | + | local modem = [[peripheral.wrap]]("left") |
| − | modem.open(3)--Open channel 3 so that we can listen on it | + | [[modem.open]](3)--Open channel 3 so that we can listen on it |
local event, modemSide, senderChannel, | local event, modemSide, senderChannel, | ||
| − | replyChannel, message, senderDistance = os.pullEvent("modem_message") | + | replyChannel, message, senderDistance = [[os.pullEvent]]("modem_message") |
| + | |||
print("I just received a message from: "..senderChannel) | print("I just received a message from: "..senderChannel) | ||
print("I should apparently reply on: "..replyChannel) | print("I should apparently reply on: "..replyChannel) | ||
| Line 63: | Line 75: | ||
print("The sender is: "..senderDistance.." blocks away from me.") | print("The sender is: "..senderDistance.." blocks away from me.") | ||
| − | So what did I do? Quite simply, I called os.pullEvent() with the string argument "modem_message", which blocks all other events from being returned. When the "modem_message" event is captured, it returns the arguments: event, modemSide, senderChannel, replyChannel, message, senderDistance. I captured these and then printed them out. | + | So what did I do? Quite simply, I called [[os.pullEvent]]() with the string argument "modem_message", which blocks all other events from being returned. When the "modem_message" event is captured, it returns the arguments: event, modemSide, senderChannel, replyChannel, message, senderDistance. I captured these and then printed them out. |
== Modem Limitations == | == Modem Limitations == | ||
Revision as of 15:15, 9 April 2014
- This page is for the modem API. For the blocks, see Modem.
| This API requires the use of a wrapped peripheral! This API does not behave like a regular API, to use it you must first wrap the peripheral and call the methods on the wrapped object. For more information see this page.
|
Modem channels are essentially networks which can be opened, closed and listened on by any Computer within range, without need of independant computer IDs. To interact with channels, one must wrap or interact directly with the peripheral as opposed to the previous interaction with the Rednet API.
This is not an actual API called "modem". This is the API for wrapped modem peripherals.
 Modem (API) | ||
|---|---|---|
| Function | Return values | Description |
| modem.isOpen(number channel) | boolean isChannelOpen | Checks to see if channel is open. |
| modem.open(number channel) | nil | Opens channel to allow for listening. The channel specified must be larger than 0 and less than 65535. |
| modem.close(number channel) | nil | Closes an open channel to disallow listening. |
| modem.closeAll() | nil | Closes all open channels. |
| modem.transmit(number channel, number replyChannel, string message) | nil | Transmits a message on the specified channel. |
| modem.isWireless() | bollean isWireless | Returns if the modem is wireless or wired. |
 Event modem_message | |
| Fired when a modem message is received. | |
| Returned Object 1 | string modemSide |
| Returned Object 2 | number senderChannel |
| Returned Object 3 | number replyChannel |
| Returned Object 4 | string message |
| Returned Object 5 | number distance |
Sending Messages
Sending messages is simple and does not require that you open any channels. Simply use the transmit function like so:
local modem = peripheral.wrap("right") --Wraps the modem on the right side. modem.transmit(3, 1, "Hello world!") peripheral.call("right", "transmit", 3, 1, "This will also work!")
What did that do? First I wrapped the peripheral in order to interact with it. Second, I used modem.transmit(channel, replyChannel, message) in order to send my message. In case you were wondering, the reply channel is captured by the listening computer and suggests which channel they should reply on.
Receiving Messages
Receiving messages requires that you be familiar with events. As of this moment, there is no API which cuts out events from the process. Here is an example of how to receive messages:
local modem = peripheral.wrap("left") modem.open(3)--Open channel 3 so that we can listen on it local event, modemSide, senderChannel, replyChannel, message, senderDistance = os.pullEvent("modem_message") print("I just received a message from: "..senderChannel) print("I should apparently reply on: "..replyChannel) print("The modem receiving this is located on the "..modemSide.." side") print("The message was: "..message) print("The sender is: "..senderDistance.." blocks away from me.")
So what did I do? Quite simply, I called os.pullEvent() with the string argument "modem_message", which blocks all other events from being returned. When the "modem_message" event is captured, it returns the arguments: event, modemSide, senderChannel, replyChannel, message, senderDistance. I captured these and then printed them out.
Modem Limitations
- You can only open 128 channels at any given time.
- The maximum channel you can open is 65535.
- You can listen on more than one channel at a time. For example, if the modem has channel 3 and channel 5 open, and somebody sends a message on channel 5, the modem will receive it. If a message is sent on channel 3, the modem will also receive the message.
- Sending messages does not require you to open any channels prior to sending it.
- If you aren't receiving a message when you think you should, check to make sure that you have opened the channel first.
- Modems and channels are not secure - if you are sending a message using the Modem API, messages are still available to any computer listening on the sent channel.
