Network.Metaverse.Circuit

This module provides the low-level interface for communicating with a metaverse server. It handles the details of packet encoding, accounting, handshaking, and so on.

In general, you should try to use the higher-level functions in the Network.Metaverse module as often as possible, and fall down to this level only when there is no other option.

Documentation

data Circuit

A Circuit is a connection to a metaverse server. One connects to the server using the information given from the login server, via circuitConnect. Messages are then sent and received by operating on the circuit, until it is closed with circuitClose or by a network timeout.

circuitConnect

Arguments

:: MVToken

Token of circuit info obtained from login server

-> IO Circuit

Connects to a circuit, using connection information given in the login token provided. This sets up all the accounting and other data structures associated with the circuit and gets it all started.

circuitAgentID :: Circuit -> UUID

Gives the agent UUID associated with this circuit.

circuitSessionID :: Circuit -> UUID

Gives the session UUID associated with this circuit.

circuitCode :: Circuit -> Word32

Gives the circuit code, a 32-bit integer, associated with this circuit. This is only rarely used, but it occasionally needed.

circuitSend

Arguments

:: Circuit

The circuit to send on

-> Bool

Whether to send reliably. While this function never waits for a response, a value of True here will cause the system to at least look for acknowledgement and retry a few times, greatly increasing the chance of the message getting through. On the other hand, False here gives a much cheaper packet.

-> PacketBody

The packet contents to send

-> IO ()

Sends a packet to the server, but does not wait for a response.

circuitSendSync :: Circuit -> PacketBody -> IO Bool

Sends a packet to the server, and waits for acknowledgement.

circuitIncoming :: Circuit -> Chan (Maybe PacketBody)

Gives the channel used to provide incoming packets from the server. In general it is not used directly, but rather in conjunction with dupChan so that each piece of the client can operate independently with respect to all of the others.

When the circuit is closed, Nothing is written to this channel.

circuitClose

Arguments

:: Circuit

The circuit to close

-> IO ()

Closes a circuit, terminating its threads, closing its network resources, and cleaning up after it.

circuitIsClosed :: Circuit -> IO Bool