Network Functions

MicroMacro uses an AES256 Rijndael encryption algorithm for secure transfer of potentially sensitive data. All information sent by MicroMacro will automatically be encrypted using this system. It is recommended that you change your 'default' encryption key located in lib/net.lua once you have obtained your copy of MicroMacro.

netPushKey

netPushKey(name, key)

Registers an encryption key for use with networking functions. This function *MUST* be called from lib/net.lua, otherwise it will be useless. This is provided as a security measure. The key will be truncated if longer than 255 characters.

Example

-- "myKey" will now be a valid encryption key for network connections
netPushKey("myKey", "AbCDefGhIjKLMnoPQrStuvWXyZ");

netOpenCon

netcon netOpenCon(binding, keyname) netcon netOpenCon(keyname)

Opens and returns a connection handle. If running on the server, you should specify "0.0.0.0" as the binding (to accept connections from anybody), otherwise a binding should not be specified (client mode). The 'keyname' should be the encryption key you wish to use. Encryption keys will be available in your lib/net.lua config file. MicroMacro also provides a default encryption key: "default".

The client and server side must be using the same encryption key, otherwise information transfer will be made impossible. Make sure you save the return result in a variable, as you will need this to continue work on this network connection.

Example - as server

listen = netOpenCon("0.0.0.0", "default");

Example - as client

server = netOpenCon("default");

netListen

int netListen(netcon)

Starts the listen process for a specified connection handle. Typically, the server should listen, and poll listen, to check if there are any incomming connections. netListen() should only be called on the server. You will only want to call this once.

Returns 0 on success, and non-zero on failure.

Example - as server

if( netListen(listen) ~= 0 ) then
  printf("Error making connection listen.\n");
end

netPollListen

netcon netPollListen(netcon)

Checks if there any any new incomming connections, and returns a connection handle to the new client if there is. If there are no new connections, netPollListen() returns nil. You must have called netListen() on the connection handle first.

Example - as server

if( netListen(listen) ~= 0 ) then
  printf("Error making connection listen.\n");
end

print("Waiting for a client...");

-- Lets wait until a client joins our server.
client = netPollListen(listen);
while( client == nil ) do
  client = netPollListen(listen);
  rest(100);
end

-- If we got to this point, that means client now
-- contains a proper netcon handle to our client!

netConnect

int netConnect(netcon, address)

Pepares the connection handle for a full connection to the server. This should only be called on the client. Address should be a string specifying the hostname or IP address of the server. You should check the network connection status before assuming that the connection has taken place by using netConnectStatus().

Returns 0 on success, non-zero on failure.

Example - as client

if( netConnect(server, "192.168.1.100") ~= 0 ) then
  print("Error initializing connection.");
end

netConnectStatus

int netConnect(netcon)

Returns the status of a network connection. The returned value will be 0 if a connection has not yet taken place. If the returned value is negitive, then the connection has failed. If the returned value is positive, then the connection was successful. You must call netConnect() first.

Example - as client

print("Attempting connection...");

-- We wait until our connection status is either an error, or a successful connection
status = netConnectStatus(server);
while( status == 0 ) do
  status = netConnectStatus(server);
end

if( status > 0 )then
  print("Connection success!");
else
  print("Connection failed!");
end

netPollMessages

bool netPollMessages(netcon)

Returns true if there are messages to process on the network connection, otherwise returns false. This should be used on both client and server. You should always poll messages before trying to read them.

Example

if( netPollMessages(netcon) ) then
  -- There are messages to process!
  -- We should read them from the message queue using netGetMessages().
end

netSendMessage

int netSendMessage(netcon, ...)

Sends a message across the network connection. All data is encrypted before sending with the encryption key that was specified when calling netOpenCon(). All information will be stored and sent in the same order it is pushed into netSendMessage(). You may format the data any way you would like, however, it is suggested that you precede the data with an integer specifying a message ID.

Returns 0 on success, and non-zero on failure. If a failure occurs, you may have been disconnected, or the opposite side of the connection may have a full message queue.

Example

-- Lets send the other side a text message.
-- We will use the ID of 12 (we just make this up) to mean that
-- we want to send a text message.

if( netSendMessage(netcon, 12, "Hello, my name is John Doe.") ~= 0 ) then
  print("You have been disconnected.");
end

netGetMessage

table netGetMessage(netcon)

Returns a table containing all of the data that was received. All data is encrypted before sending with the encryption key that was specified when calling netOpenCon(). The data will be in the same order as it was sent. You should use netPollMessages() to check if new messages are waiting to be processed.

Example

while( netPollMessages(netcon) ) do
  -- remember, in our example, we sent: 12, "Hello my name is John Doe."
  local message = netGetMessage(netcon);
  local messId = message[1];

  if( messId == 12 ) then
    -- It looks like they sent us a text message.
    -- It is safe to assume that the next data type is the message.

    local messText = message[2];
    printf("Received message: %s\n", messText);
  end
end

-- ^ For our example, this message will have been printed to our screen:
-- Received message: Hello my name is John Doe.

netGetAddress

string netGetAddress(netcon)

Returns a string containing the remote connections' address.

Example:

local otherIP = netGetAddress(netcon);
-- otherIP should now be something like: "127.0.0.1"

netCloseCon

netCloseCon(netcon)

Closes a network connection handle. It is proper to send a message to the server which represents your disconnection before actually close the connection.

Example

netCloseCon(netcon);