classDocs / Network

Network

classsharedsource

Object → Network

A named two-way channel between the server and the clients built on top of the engine net library, without its 64 KiB message limit.

Data up to 8 KiB is usually sent as a single reliable message, larger data is split into segments and streamed over the unreliable channel with acknowledgements, retransmission, congestion control and a CRC32 check of the whole data.

Transfers to the same peer are queued, one runs at a time per network.

The network must be created on the server first, the client can only open networks the server has registered. Creating a network with the name of an existing one returns the existing object.

On the server, every client is limited in strikes, concurrent transfers and bytes, protocol violations accumulate strikes and kick the client.

Constructor

Network(name: string, can_receive: boolean?): Network

Fields

Name	Type	Description
`id`	`integer`	The engine ID of the network, read-only.
`name`	`string`	The name of the network without the internal prefix, read-only.
`receiver`	`boolean`	`true` if the network accepts incoming messages, `false` by default.
`timeout`	`number`	The number of seconds without any progress after which a transfer is aborted, `15` by default, at least `1`.
`window`	`integer`	The maximum number of segments in flight, `64` by default, clamped to `[1, 256]`.
`segment`	`integer`	The size of outgoing segments in bytes, by default fits into a 1 KiB message, at least `256` and at most what fits into one message.
`limit`	`integer`	The maximum size of an incoming message in bytes, `64` MiB by default, `0` rejects everything.

Methods

`abort`	Cancels the outgoing transmission to the target and all queued ones.
`attach`	Attaches a handler that is called when a message is fully received.
`await`	Waits for the next fully received message.
`clear`	Removes every receive handler.
`detach`	Detaches a previously attached receive handler.
`isReceiving`	Checks if the network is receiving data from the sender.
`isSending`	Checks if the network is sending data to the target.
`once`	Attaches a handler that automatically detaches itself right before being invoked, so it only ever runs once.
`send`	Sends the data to the target.
`stream`	Attaches a handler that receives incoming data in order, chunk by chunk, while it arrives.
`transmit`	Builds the data with a binary writer and sends it to the target.
`unstream`	Detaches a previously attached stream handler.
`unwatch`	Detaches a previously attached progress handler.
`watch`	Attaches a handler that is called on every transfer progress, both incoming and outgoing.

#Network:abort

sharedsource

function Network:abort(target?: garrysmod.Player): boolean

Cancels the outgoing transmission to the target and all queued ones.

Parameters

Name	Type	Description
`target`optional	`garrysmod.Player`	The target player, required on the server, ignored on the client.

Returns

Type	Name	Description
`boolean`	`cancelled`	`true` if anything was cancelled.

#Network:attach

sharedsource

function Network:attach(handler: Network.ReceiveFn | Hook | Event)

Attaches a handler that is called when a message is fully received.

If the handler is already attached, it will not be attached twice.

Parameters

Name	Type	Description
`handler`	`Network.ReceiveFn \| Hook \| Event`	The callback or callable object.

#Network:await

sharedasyncsource

async function Network:await(): Network, BinaryReader, garrysmod.Player | nil

Waits for the next fully received message.

Returns

Type	Name	Description
`Network`	`network`	The network.
`BinaryReader`	`reader`	The reader of the message.
`garrysmod.Player \| nil`	`sender`	The sender, `nil` on the client.

#Network:clear

sharedsource

function Network:clear()

Removes every receive handler.

#Network:detach

sharedsource

function Network:detach(handler: Network.ReceiveFn | Hook | Event): boolean

Detaches a previously attached receive handler.

Parameters

Name	Type	Description
`handler`	`Network.ReceiveFn \| Hook \| Event`	The exact handler reference.

Returns

Type	Name	Description
`boolean`	`removed`	`true` if the handler was attached.

#Network:isReceiving

sharednodiscardsource

function Network:isReceiving(sender?: garrysmod.Player): boolean

Checks if the network is receiving data from the sender.

Parameters

Name	Type	Description
`sender`optional	`garrysmod.Player`	The sender player, required on the server, ignored on the client.

Returns

Type	Name	Description
`boolean`	`is_receiving`	`true` if a transmission from the sender is running.

#Network:isSending

sharednodiscardsource

function Network:isSending(target?: garrysmod.Player): boolean

Checks if the network is sending data to the target.

Parameters

Name	Type	Description
`target`optional	`garrysmod.Player`	The target player, required on the server, ignored on the client.

Returns

Type	Name	Description
`boolean`	`is_sending`	`true` if a transmission to the target is running.

#Network:once

sharedsource

function Network:once(handler: Network.ReceiveFn | Hook | Event)

Attaches a handler that automatically detaches itself right before being invoked, so it only ever runs once.

Parameters

Name	Type	Description
`handler`	`Network.ReceiveFn \| Hook \| Event`	The callback or callable object.

#Network:send

sharedsource

function Network:send(data: string, target?: ( garrysmod.Player | garrysmod.Player[] )?, callback?: Network.FinishFn)

Sends the data to the target.

Small data is sent as a single reliable message, larger data is split into segments and streamed with acknowledgements.

If the target is already receiving a transmission from this network, the data is queued behind it.

Parameters

Name	Type	Description
`data`	`string`	The data to send.
`target`optional	`( garrysmod.Player \| garrysmod.Player[] )?`	The target player(s), required on the server, ignored on the client.
`callback`optional	`Network.FinishFn`	The callback that is called when the transmission is finished or failed.

#Network:stream

sharedsource

function Network:stream(handler: Network.StreamFn | Hook | Event)

Attaches a handler that receives incoming data in order, chunk by chunk, while it arrives.

chunk is the data starting at the zero-based byte offset, after the last chunk the handler is called once more with chunk = nil and success, success is false if the transfer failed ( timed out, cancelled or checksum mismatch ), the chunks received before it should be discarded then.

If a network has only stream handlers, the received data is not kept in memory.

Parameters

Name	Type	Description
`handler`	`Network.StreamFn \| Hook \| Event`	The callback or callable object.

#Network:transmit

sharedsource

function Network:transmit(fn: fun( network: Network, writer: BinaryWriter ), target?: ( garrysmod.Player | garrysmod.Player[] )?, callback?: Network.FinishFn)

Builds the data with a binary writer and sends it to the target.

Parameters

Name	Type	Description
`fn`	`fun( network: Network, writer: BinaryWriter )`	The function that writes the data.
`target`optional	`( garrysmod.Player \| garrysmod.Player[] )?`	The target player(s), required on the server, ignored on the client.
`callback`optional	`Network.FinishFn`	The callback that is called when the transmission is finished or failed.

#Network:unstream

sharedsource

function Network:unstream(handler: Network.StreamFn | Hook | Event): boolean

Detaches a previously attached stream handler.

Parameters

Name	Type	Description
`handler`	`Network.StreamFn \| Hook \| Event`	The exact handler reference.

Returns

Type	Name	Description
`boolean`	`removed`	`true` if the handler was attached.

#Network:unwatch

sharedsource

function Network:unwatch(handler: Network.ProgressFn | Hook | Event): boolean

Detaches a previously attached progress handler.

Parameters

Name	Type	Description
`handler`	`Network.ProgressFn \| Hook \| Event`	The exact handler reference.

Returns

Type	Name	Description
`boolean`	`removed`	`true` if the handler was attached.

#Network:watch

sharedsource

function Network:watch(handler: Network.ProgressFn | Hook | Event)

Attaches a handler that is called on every transfer progress, both incoming and outgoing.

Parameters

Name	Type	Description
`handler`	`Network.ProgressFn \| Hook \| Event`	The callback or callable object.