Created Component/Modem (markdown)

Component-Modem.md

@@ -0,0 +1,43 @@
+This component is provided by [[network cards|Items#network-card]]. Wireless network cards behave much like normal network cards, but additionally send the message as a wireless "packet" when a strength is set.
+
+Component name: `modem`.  
+Callbacks:
+- `isWireless(): boolean`  
+  Returns whether this modem is capable of sending wireless messages.
+- `isOpen(port: number): boolean`  
+  Returns whether the specified "port" is currently being listened on. Messages only trigger signals when they arrive on a port that is open.
+- `open(port: number): boolean`  
+  Opens the specified port number for listening. Returns `true` if the port was opened, `false` if it was already open.
+- `send(address: string, port: number[, ...]): boolean`  
+  Sends a network message to the specified address. Returns `true` if the message was sent. This does *not* mean the message was received, only that it was sent. No port-sniffing for you.  
+  Any additional arguments are passed along as data. These arguments must be basic types: nil, boolean, number and string values are supported, tables and functions are not. See [[the text API|API/Text]] for serialization of tables.
+- `broadcast(port: number, ...): boolean`  
+  Sends a broadcast message. This message is delivered to all reachable network cards. Returns `true` if the message was sent. Note that broadcast messages are *not* delivered to the modem that sent the message.  
+  All additional arguments are passed along as data. See `send`.
+- `getStrength(): number`  
+  The current signal strength to apply when sending messages.  
+  *Wireless network cards only.*
+- `setStrength(value: number): number`  
+  Sets the signal strength. If this is set to a value larger than zero, sending a message will also generate a wireless message. The higher the signal strength the more energy is required to send messages, though.  
+  *Wireless network cards only.*
+
+This component generates a signal named `modem_message` if a message from another network card is received. It has the signature `localAddress: string, remoteAddress: string, port: number, distance: number, ...`.
+- `localAddress` is the address of the modem component the message was received by.
+- `remoteAddress` is the address of the network card the message was sent from.
+- `port` is the port number the message was delivered to.
+- `distance` is the distance to the modem that sent the message. This is only set for wireless messages. For normal messages this is always 0.
+- All further values are values passed along by the sender (i.e. the `...` in `send` and `broadcast`).
+
+*A note on HTTP requests*: if enabled in the configuration, wireless modems can be used to make HTTP requests. For this, call `send` with a URL instead of a component address. The recommended way of doing this is via the [[HTTP API|API/HTTP]], however.
+
+Example use:
+```lua
+local m = component.modem -- get primary modem component
+m.open(123)
+print(m.isOpen(123)) -- true
+-- Send some message.
+m.broadcast(321, "this is a test")
+-- Wait for a message from another network card.
+local _, from, port, _, message = event.pull("modem_message")
+print("Got a message from " .. from .. " on port " .. port .. ": " .. tostring(message))
+```