Network.SocketIO

Documentation

This library provides an implementation of Socket.io protocol (version 1). It builds on top of Engine.IO, allowing Socket.io to work with both long polling XHR requests, and seamlessly upgrading them to HTML 5 web sockets.

initialize :: MonadIO m => ServerAPI m -> StateT RoutingTable (ReaderT Socket m) a -> IO (m ())

This computation initializes a Socket.IO server and returns a computation that you should call whenever a request comes in to the socket.io path. For example, in a Snap application, you might do:

handler <- initialize snapAPI mkRoutes
quickHttpServe $ route [("/socket.io", handler)]

The second argument to this function is an action to build up the routing table, which determines what happens when clients emit events. It is also an action that is called every time a client connects, so you can mutate state by taking advantage of the MonadIO instance. You can build a routing table by using the convenience on family of functions.

Receiving events

data RoutingTable

A per-connection routing table. This table determines what actions to invoke when events are received.

on :: (MonadState RoutingTable m, OnArgs f (EventHandler a)) => Text -> f -> m ()

When an event with a given name is received, and its argument can be decoded by a FromJSON instance, run the associated function after decoding the event argument. Expects exactly one event argument.

on_ :: MonadState RoutingTable m => Text -> EventHandler a -> m ()

Deprecated: Use Network.SocketIO.on instead

When an event is received with a given name and no arguments, run the associated EventHandler.

onJSON :: MonadState RoutingTable m => Text -> (Array -> EventHandler a) -> m ()

When an event with a given name is received, call the associated function with the array of JSON arguments.

appendDisconnectHandler :: MonadState RoutingTable m => EventHandler () -> m ()

Run the given IO action when a client disconnects, along with any other previously register disconnect handlers.

Emitting Events

type EventHandler a = ReaderT Socket IO a

To One Client

emit :: (ToJSON a, MonadReader Socket m, MonadIO m) => Text -> a -> m ()

Emit an event and argument data to a Socket. If called from within on, this will be the client that emitted the original event.

emitJSON :: (MonadReader Socket m, MonadIO m) => Text -> Array -> m ()

Emit an event with a specific array of JSON arguments.

emitTo :: (ToJSON a, MonadIO m) => Socket -> Text -> a -> m ()

Emit an event to specific Socket.

emitJSONTo :: MonadIO m => Socket -> Text -> Array -> m ()

Emit an event with a specific array of JSON arguments to a specific Socket.

To Many Clients

broadcast :: (ToJSON a, MonadReader Socket m, MonadIO m) => Text -> a -> m ()

Broadcast an event to all other Sockets.

broadcastJSON :: (MonadReader Socket m, MonadIO m) => Text -> Array -> m ()

Broadcast an event with an array of JSON arguments to all other Sockets.

Sockets

data Socket

A Socket.IO socket (not to be confused with an Engine.IO Socket).

Instances

Eq Socket

Ord Socket

socketId :: Socket -> SocketId

Retrieve the Engine.IO SocketId for a Socket.

engineIOSocket :: Socket -> Socket

Retrieve the Engine.IO Socket that underlies this Socket.IO socket. This is a fairly low-level operation - you should take care when reading or writing directly to this socket, as it is possible to break invariants that Socket.io is expecting.

Protocol Types

Packet Types

data PacketType

Constructors

Connect

Disconnect

Event

Ack

Error

BinaryEvent

BinaryAck

Instances

Bounded PacketType

Enum PacketType

Eq PacketType

Read PacketType

Show PacketType

parsePacketType :: Parser PacketType

encodePacketType :: PacketType -> Builder

Packets

data Packet

Constructors

Packet !PacketType !(Maybe Int) !Text !(Maybe Int) !(Maybe Value)

Instances

Eq Packet

Show Packet

parsePacket :: Parser Packet

encodePacket :: Packet -> Builder