The Networking event is one which will be triggered by any incoming network traffic, and is linked to the Network Functions. This event generates a special ds_map (more commonly known as a "dictionary") that is exclusive to this event and is stored in the special variable async_load. This ds_map will contain different information depending on the type of network event that generated it.
The following keys are common to all received network functions and will always be present in the async_load map:
- "type": This will have one of the constants listed below as its return value, and designates the network event type.
- "id": The socket id (a real number, as returned by the network_create_server or network_create_socket function) that is receiving the event. In most cases the socket ID returned is the ID of TCP or UDP socket that triggered the event, however if the event is triggered in a server and it's a Data Event (see below) then the socket ID is that of the client that sent the data.
- "ip": The IP address of the socket (as a string).
- "port": The port associated with the IP address (useful when working with UDP).
The possible return values for the "type" key can be any of the three constants listed below:
|network_type_connect||The event was triggered by a connection.|
|network_type_disconnect||The event was triggered by a disconnection.|
|network_type_data||The event was triggered by incoming data.|
|network_type_non_blocking_connect||The event was triggered by a connection configured as non-blocking (you can use the function network_set_config() for this).|
When you have an event of the type network_type_connect, network_type_non_blocking_connect or network_type_disconnect, the async_load map will have the following additional keys:
- "socket": This key will hold the connecting/disconnecting socket id.
- "succeeded": This key will be either 0 or 1, where 0 means the connection timed out and 1 means it succeeded and the socket is ready to use.
It is worth noting that the Networking Event does not get
triggered in clients when the server disconnects, and
that neither of the network_type_* events will be triggered in
clients when the server they are connected to disconnects, even if
the connection is TCP based.
When you have a network_type_data type event, which signifies that your network has received data, the map created will have the following keys:
- "buffer": This is the unique "buffer id" which is generated by the event. A "grow" type buffer, byte aligned to 1, is created to hold the id should be stored in a variable and used for all further function calls to the buffer in this event. Just like the async_load map, the buffer created is automatically removed from memory at the end of this event. For more information on buffers, please see Reference - Buffers
- "size": This is the size (in bytes) of the buffer data that is being received.
NOTE: The map held in the async_load variable
is only valid in these events, as the ds_map that is points to is
created at the start of the event, then deleted again at the end,
with this variable being reset to a value of -1 in all other
events. If you have received data, then the same will happen with
the buffer created - it is only available in this event and will be
freed when the event is over.