 |
Automation - Macro - Bot - Scripting system. |
Network Communication:
A network library to pass data from one MM instance to another, be it the same computer or others over LAN or WAN (Internet). The MM is not a general purpose network system; it is restricted to sending and receiving tables (over the TCP protocol).
Security: The MM network system has some basic checks to catch buffer overruns, corrupt packets, etc., but there can be major security issues still. It’s intended for use in small contained trusted environments, not for enterprise applications over the internet, etc.
There are three dynamic objects: server, client, and ClientConnection.
Server:
Create a new server object:
object, result = network.Server(address, [port], [cypherkey])
address: IP ASCII string address for clients to connect to.
port: Port number for clients to connect to. Valid range is 1024 to 65535, or 0 or nil to let the OS choose a port.
cypherkey: Text hex encoded cipher key. If supplied, turns on encryption of network traffic.
Two valid lengths 32 char (16 hex digits) for 128bit, or 64 chars (32 hex digits) for a 256bit key.
It’s best to avoid using encryption unless communicating over the internet, and, or, when extra security is needed, as it adds a bit of processing overhead.
Returns a new server connection object on success, or nil on failure, and returns a result string.
Methods:
count = server:Send(table, connection...) Send a table message to one or more client connections.
Returns a success count for successful sends.
The table to send can only contain basic Lua types: nil, boolean, number, string, and table.
Example:
-- Send a text message to two clients
server:Send({“Hello Client”}, aConnection[1], aConnection[2])
count = server:Broadcast(table) Send a table message packet to all connected clients.
Example:
-- Broadcast a message to all connected clients
server:Broadcast({OpCode =10, Data = “From server”})
| count = server:Disconnect(connection...) | Disconnect one or more client connections. Returns a success count. |
| count = server:ConnectionCount() | Returns client connection count. |
| socketid = server:GetSocket() | Returns the unique socket identifier for the server connection. |
| port = server:GetPort() | Returns server port number. |
| address = client:GetAddress() | Returns server IP address string. |
Example:
MyServer, szResult = network.Server("127.0.0.1", 4096, "0C03EA65238DD2C25EB87CE563868098")
Client:
Create a new client object:
object, result = network.Client(address, [port], [cypherkey])
address: IP ASCII string address of server to connect to.
port: Port number of server to connect to. Valid range is 1024 to 65535.
cypherkey: Text hex encoded cipher key. If supplied, turns on encryption of network traffic.
Two valid lengths 32 char (16 hex digits) for 128bit, or 64 chars (32 hex digits) for a 256bit key.
Returns client connection object on success, or nil on failure, and returns a result string.
Methods:
| bResult = client:Send(table) | Send a table message to the server. Returns true on success. |
| client:Disconnect() | Disconnect from server. |
| socketid = client:GetSocket() | Returns the unique socket identifier for the client connection. |
| port = client:GetPort() | Returns actual server port connection, or nil if not connected yet. |
| address = client:GetAddress() | Returns IP address string for the server the client is connected to. |
bResult, WaitTime = client:WaitForConnect([timeout]) Wait for connection to server after client create.
Optional time-out value (default two seconds), valid range 0.250 to 10 seconds.
Returns true on success, and approximate time taken to connect.
ClientConnection:
Each client connection made to a server are represented by this object.
These are passed by the network.EVENT_CONNECT event (see below).
A reference to these objects must be maintained (typically in a table) else the connection will automatically close once the object losses scope and is garbage collected.
Methods:
| socketid = :GetSocket() | Returns the unique socket identifier for the client connection. |
| port = :GetPort() | Returns the client connection port. |
| address = :GetAddress() | Returns IP address string for the client connection. |
Events:
The system uses a polling system to handle network events.
Therese are gathered through a single global function:
table = network.PollEvents()
Base table element:
.Event = Event code (see below)
.Timestamp = Timestamp when the event happened.
.Object = Network object.
.Errors = Result/status string.
Events by code:
network.EVENT_CONNECT Event to a server of an incoming client connection.
The .Object entry is a new ClientConnection object.
A reference of this object must be kept else it will be automatically closed on next garbage collection cycle.
network.EVENT_CONNECTED Event for client of connection result to server.
.Result = bool value, trueif connection was a success.
network.EVENT_RECEIVE Receive a table packet
.Packet{} = Data
network.EVENT_SERVER_CLOSE Event for client that server connection has closed.
network.EVENT_CLIENT_CLOSE Event for server that a client connection has closed.
network.EVENT_ERROR Event for a client or server connection that an error has occurred.
.Errors = Result/status string.
Warning: The internal network event queue has only space for 2000 events maximum.
After that it will wrap around loosing the oldest events.
The events should be polled at least once every few seconds at a minimum to avoid overflow.