net

_G.net

Overview

Functions

Signature	Return	Description
`getHWAddr()`	`string`	Gets the computer's hardware address (hex string)
`getIPV()`	`string`	Gets the type of address the computer uses (currently IPV4)
`ipFormat(ip)`	`string`	Format a numeric IPV4 in the the standard format
`ipToNumber(ip)`	`NetAddress`	Turns an IP string into a numerical IP address
`getIP()`	`NetAddress`	Gets the current IP of the computer (numeric)
`getIPMask()`	`number`	Get the address mask of the local network (numeric)
`getMsgId()`	`number`	Get the current message ID
`useMsgId()`	`number`	Increment and return the current message ID
`realizeHostname(hostname)`	`NetAddress`	Gets the IP address associated with a given hostname
`getModem(side)`	`table?`	Get a modem on side, and add network functions
`getHostname()`	`string`	Returns the network hostname of the computer
`setHostname(new)`	`boolean`	Sets the network hostname of the computer
`isSetup()`	`boolean`	If the network module has been setup
`getCModem()`	`table?`	Gets the currently used modem
`setup(mdm, ip)`	`boolean`	Setup the network module, returns false on a failure
`send(port, dest, msgType, body)`	`number`	Send a message with a type header
`sendSync(port, dest, msgType, body, timeout?)`	`NetMessage\|string`	Send a message with a type header, and waits for the reply
`sendAdv(port, dest, head, body)`	`number`	Send a message with a custom header
`sendAdvSync(port, dest, head, body, timeout?)`	`NetMessage\|string`	Send a message with a custom header, and waits for the reply
`reply(port, old, head, body)`	`number`	Reply to a message
`waitForMsg(port, time)`	`NetMessage\|string`	Waits for a message on a particular port, with a timeout
`waitForMsgAdv(port, time, check)`	`NetMessage\|string`	Waits for a message on a particular port, with a timeout
`waitForMsgAll(check, time)`	`NetMessage\|string`	Waits for a message based on the check function, or a timeout
`validMsg(port, message)`	`boolean`	Checks is a modem message is a valid network message
`registerMsgHandler(func)`	`number`	Register a message handler
`unregisterMsgHandler(id)`	`nil`	Unregister a message handler
`getCIDofNetHandlers()`	`number`	Get the id of the next message handler
`multicastSubscribe(ip, handler)`	`integer`	Subscribe to a multicast group
`multicastUnsubscribe(ip, id)`	`nil`	Remove a multicast subscription, uses ID from subscription
`stringMessage(msg)`	`string`	Returns a string version of the message for debug and logging
`open(port)`	`nil`	Open the modem on port
`ping(dest)`	`nil`	Ping destination and print time
`splitUrl(url)`	`string?, string, string`	Split a url string
`setLogVerbose(vb)`	`nil`	Sets if the net module should log all messages

Variables

Variable	Description
`standardPorts: table`	Standard Networking ports
`ignoreMsgOnDecryptFail: boolean = true`	If messages that can not be decrypted should be ignored
`DEFAULT_TIMEOUT: number = 5`	Default message wait time out in seconds

Classes

NetMessage

NetAddress

Sub-Modules

sockets

encrypt

certificate

Detail

Functions

`getHWAddr`

net.getHWAddr():string

Gets the computer's hardware address (hex string)

Returns

hwAddress: string - Hardware address as hex string

`getIPV`

net.getIPV():string

Gets the type of address the computer uses (currently IPV4)

Returns

version: string - Gets the IP version used by the module

`ipFormat`

net.ipFormat(ip: NetAddress): string

Format a numeric IPV4 in the the standard format

Parameters

ip: NetAddress - IP address either as number, or hardware address

Returns

ip: string - IP address formatted in IPV4 x.x.x.x

`ipToNumber`

net.ipToNumber(ip: string|NetAddress): NetAddress

Turns an IP string into a numerical IP address

Parameters

ip: string|NetAddress - IP Address as x.x.x.x

Returns

ip: NetAddress - Address as number

`getIP`

net.getIP(): NetAddress

Gets the current IP of the computer (numeric)

Returns

ip: NetAddress - The numeric IP of the computer

`getIPMask`

net.getIPMask(): number

Get the address mask of the local network (numeric)

Returns

mask: number - Numeric IP subnet mask (ie. 0xff00 for 255.255.0.0)

`getMsgId`

net.getMsgId(): number

Get the current message ID

Returns

id: number - Id for last message

`useMsgId`

net.useMsgId(): number

Increment and return the current message ID

Returns

id: number - Id for next message

`realizeHostname`

net.realizeHostname(hostname: string|NetAddress): NetAddress

Gets the IP address associated with a given hostname

Parameters

hostname: string|NetAddress - Hostname, IP address, or HW address

Returns

ip: NetAddress - Numeric IP address or HW address

`getModem`

net.getModem(side: 'front'|'back'|'left'|'right'|'top'|'bottom'): table?

Get a modem on side, and add network functions

Parameters

side: 'front'|'back'|'left'|'right'|'top'|'bottom' - Side of computer

Returns

modem: table? - Modem handle

`getHostname`

net.getHostname(): string

Returns the network hostname of the computer

Returns

hostname: string - Current hostname (defaults to "")

`setHostname`

net.setHostname(new: string): boolean

Sets the network hostname of the computer. Returns if setting the hostname succeeded

Important

Requires Super User

Parameters

new: string - New hostname

Returns

suc: boolean - If the hostname was set successfully

`isSetup`

net.isSetup(): boolean

If the network module has been setup

Returns

setup: boolean - If module is setup

`getCModem`

net.getCModem(): table?

Gets the currently used modem

Returns

modem: table? - Current primary modem

`setup`

net.setup(mdm?: table, ip?: number): boolean

Setup the network module, returns false on a failure

Parameters

mdm?: table - (Optional) Primary modem
ip?: number - (Optional) Numeric IP address

Returns

setup: boolean - If the module is not setup

`send`

net.send(port: number, dest: string|NetAddress, msgType: string, body: nil|table|string): number

Send a message with a type header

Parameters

port: number - Network port for message (see net.standardPorts)
dest: string|NetAddress - Destination IP address, HW address, or hostname
msgType: string - Message type
body: nil|table|string - Message body

Returns

id: number - Message ID or -1 on error

`sendSync`

net.sendSync(port: number, dest: string|NetAddress, msgType: string, body: nil|table|string, timeout?: number): NetMessage|string

Send a message with a type header, and waits for the reply. Returns the message, "setup_fail", "sent_fail", or "timeout" after timeout

Parameters

port: number - Network port for message (see net.standardPorts)
dest: number|string - Destination IP address, HW address, or hostname
msgType: string - Message type
body: nil|table|string - Message body
timeout?: number - (Optional) Reply timeout in seconds (default is net.DEFAULT_TIMEOUT seconds, set to -1 to disable)

Returns

rsp: NetMessage|string - Response message, or error string

`sendAdv`

net.sendAdv(port: number, dest: NetAddress|string, head: NetMessage.Header, body: nil|table|string): number

Send a message with a custom header

Parameters

port: number - Network port for message (see net.standardPorts)
dest: NetAddress|string - Destination IP address, HW address, or hostname
head: NetMessage.Header - Message header, should include type parameter
body: nil|table|string - Message body

Returns

id: number - Message ID or -1 on error

`sendAdvSync`

net.sendAdvSync(port: number, dest: NetAddress|string, head: NetMessage.Header, body: nil|table|string, timeout?: number): NetMessage|string

Send a message with a custom header, and waits for the reply. Returns the message, "setup_fail", "send_fail", or "timeout" after timeout

Parameters

port: number - Network port for message (see net.standardPorts)
dest: NetAddress|string - Destination IP address, HW address, or hostname
head: NetMessage.Header - Message header, should include type parameter
body: nil|table|string - Message body
timeout?: number - (Optional) Reply timeout in seconds (default is net.DEFAULT_TIMEOUT seconds, set to -1 to disable)

Returns

rsp: NetMessage|string - Response message, or error string

`reply`

net.reply(port: number, old: NetMessage, head: NetMessage.Header, body: nil|table|string): number

Reply to a message

Parameters

port: number - Network port for reply (see net.standardPorts)
old: NetMessage - Message object to reply to
head: NetMessage.Header - Reply header, should include type field
body: nil|table|string - Reply body

Returns

id: number - Reply message id

`waitForMsg`

net.waitForMsg(port: number, time: number): NetMessage|string

Waits for a message on a particular port, with a timeout.

Parameters

port: number - Network port to listen on (-1 for any)
time?: number - (Optional) Timeout in seconds (default is net.DEFAULT_TIMEOUT seconds, set to -1 to disable)

Returns

rsp: NetMessage|string - Message or error string

`waitForMsgAdv`

net.waitForMsgAdv(port: number, time: number, check: fun(msg: NetMessage): boolean): NetMessage|string

Waits for a message on a particular port, with a timeout.

Check function should return true on the message you want, and takes the message as a parameter.

Parameters

port: number - Network port to listen on (-1 for any)
time: number - Timeout in seconds
check: fun(msg: NetMessage): boolean - Message check function, takes message as parameter, and returns continue waiting

Returns

rsp: NetMessage|string - Message or error string

Example

-- Wait for the next RTTP message
local rsp = net.waitForMsgAdv(net.standardPorts.rttp, nil, function(message)
    if message.header.type == 'rttp' then
        return false
    end
    return true -- Not RTTP, so keep waiting
end)

`waitForMsgAll`

net.waitForMsgAll(check: fun(port: number, msg: NetMessage): boolean, time: number?): NetMessage|string

Waits for a message based on the check function, or a timeout.

Check function takes the port and message.

Parameters

check: fun(port: number, msg: NetMessage): boolean - Message check function, takes message as parameter, and returns continue waiting
time: number? - Timeout in seconds (default is net.DEFAULT_TIMEOUT seconds, set to -1 to disable)

Returns

rsp: string|NetMessage - Message or error string

Example

-- Wait for the next message from 0.0.0.0
local rsp = net.waitForMsgAdv(net.standardPorts.rttp, nil, function(port, message)
    if message.header.origin == 0 then -- From 0.0.0.0
        return false
    end
    return true -- Not from correct IP, so keep waiting
end)

`validMsg`

net.validMsg(port: number, message: table): boolean

Checks is a modem message is a valid network message

Parameters

port: number - Network port of message
message: table - Message to validate

Returns

valid: boolean Message is valid

`registerMsgHandler`

net.registerMsgHandler(func: fun(msg: NetMessage)): number

Register a message handler

Parameters

func: fun(msg: NetMessage) - Handler function, takes a message object

Returns

id: number - Handler Id, used to un-register handlers

Example

-- Count every message for myProtocol that this computer receives without blocking
local count = 0
local id = net.registerMsgHandler(function(message)
    if message.header.type == 'myProtocol' then
        count = count + 1
    end
end)

`unregisterMsgHandler`

net.unregisterMsgHandler(id: number): nil

Un-register a message handler

Parameters

id number - Handler Id

`getCIDofNetHandlers`

net.getCIDofNetHandlers(): number

Get the id of the next message handler

Returns

id: number - Next handler id

`multicastSubscribe`

net.multicastSubscribe(ip: number, handler: fun(ip: number, msg: NetMessage)): integer

v1.8

Subscribe to a multicast group. IP must be between 224.0.0.0 (0xe0000000) and 239.255.255.255 (0xefffffff).

Parameters

ip: number - Multicast group IP
handler: fun(ip: number, msg: NetMessage) - Multicast message handler

Returns

id: integer - Handler Id, used to unregister subscriber

`multicastUnsubscribe`

net.multicastUnsubscribe(ip: number, id: integer): nil

v1.8

Remove a multicast subscription, uses ID from subscription

Parameters

ip: number - Multicast group IP
id: integer - Handler Id, from net.multicastSubscribe(ip, handler)

`stringMessage`

net.stringMessage(msg: NetMessage): string

Returns a string version of the message for debug and logging. Includes: origin, destination, port, id, connection Id, type, and serialized body

Parameters

msg: NetMessage - Message to string

Returns

message: string - String version of message

`open`

net.open(port: number): nil

Open the modem on port

Parameters

port: number - Network port to open (see net.standardPorts)

`ping`

net.ping(dest: NetAddress|String): nil

Ping destination and print time

Parameters

dest: NetAddress|string - Destination hostname, IP address, HW address

`splitUrl(url)`

net.splitUrl(url: string): string?, string, string

Split a url string

Parameters

url: string - URL string: protocol://domain/path

Returns

protocol: string? * Protocol string (if provided, else nil)
domain: string - Domain, including sub domains
path: string - Path with no leading /

Example

local proto, domain, path = net.splitUrl('rttp://xyz.com/abc/def')
print(proto)
print(domain)
print(path)

Prints

rttp
xyz.com
abc/def

`setLogVerbose(vb)`

net.setLogVerbose(vb: boolean): nil

Sets if the net module should log all messages

Parameters

vb: boolean - If all messages should be logged

Variables

`standardPorts`

Name	Value	Description
`network`	`10000`	Network control messages
`rttp`	`10080`	Redstone Text Transfer Protocol (in-game HTTP) messages
`rttps`	`10081`	Redstone Text Transfer Protocol Secure (in-game HTTPS) messages
`ftp`	`10021`	File Transfer Protocol messages
`rmail`	`10025`	RMail messages
`remoteUser`	`10234`	Remote user system

Classes

NetMessage

Networking message struct

Field	Description
`origin: NetAddress`	Origin IP or HW of the message
`dest: NetAddress`	Destination IP or HW of message
`port: number`	Networking port for message
`header: NetMessage.Header`	Header table
`body: nil\|table\|string`	Message body
`msgid: number`	Message ID
`reply: fun(self, port: number, head: NetMessage.Header, body: nil\|table\|string)`	Reply to this message (equivalent to `net.reply()`)

NetMessage.Header

Networking message header table

Field	Description
`type: string`	Net message type
`encrypted: boolean?`	If the message body is encrypted
`publicKey: byteArray?`	Body encryption public key
`domain: string?`	Destination domain name
`conId: number?`	NAT connection ID
`destConId: number?`	Destination NAT connection ID
`originDomain: string?`	REPLY ONLY Domain the request was sent to
`certificate: net.Certificate?`	Certificate

NetAddress

Alias for number|string, represents an IP or HW address that can be used to send a message to another computer

Home

Help / Information

FAQ

Getting Started

Networking

Documentation