-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Server-side WebSocket protocol handshake and communication.
--   
--   A library for creating WebSocket-capable servers, where the
--   implemented protocol is defined here: <a>http://is.gd/eSdLB</a>.
--   
--   This library is only tested with Chromium &gt;=7 and Firefox &gt;=4
--   and is a work in progress.
--   
--   How do you use this library? Here's how:
--   
--   <ul>
--   <li>Get a <a>Handle</a> to your connected client.</li>
--   <li>Perform the initial handshake with <a>shakeHands</a> (or
--   <a>getRequest</a> and <a>putResponse</a>).</li>
--   <li>Send and receive strict bytestrings with <a>putFrame</a> and
--   <a>getFrame</a>.</li>
--   </ul>
--   
--   And here's a short example of a server that accepts clients, greets
--   them with a welcome message, checks for disconnects and replies to all
--   messages by echoing them back with an appended meow:
--   
--   <pre>
--   import Network.WebSockets (shakeHands, getFrame, putFrame)
--   import Network (listenOn, PortID(PortNumber), accept, withSocketsDo)
--   import System.IO (Handle, hClose)
--   import qualified Data.ByteString as B (append, null)
--   import Data.ByteString.UTF8 (fromString) -- this is from utf8-string
--   import Control.Monad (forever)
--   import Control.Concurrent (forkIO)
--   
--   main :: IO ()
--   main = withSocketsDo $ do
--     socket &lt;- listenOn (PortNumber 12345)
--     putStrLn "Listening on port 12345."
--     forever $ do
--       (h, _, _) &lt;- accept socket
--       forkIO (talkTo h)
--   
--   
--   talkTo :: Handle -&gt; IO ()
--   talkTo h = do
--     request &lt;- shakeHands h
--     case request of
--       Left error -&gt; putStrLn error
--       Right rqst -&gt; do
--         putFrame h (fromString "滴水之恩当以涌泉相报")
--         putStrLn "Shook hands, sent welcome message."
--         talkLoop h
--   
--     hClose h
--     putStrLn "Client quit, closed handle."
--   
--   
--   talkLoop :: Handle -&gt; IO ()
--   talkLoop h = do
--     msg &lt;- getFrame h
--     if B.null msg
--        then return ()
--        else do
--          putFrame h $ B.append msg (fromString ", MEOW!")
--          talkLoop h
--   </pre>
--   
--   The example above will suffice if you wish to accept any
--   WebSocket-capable client, regardless of its origin or target. It won't
--   suffice if you have to filter the incoming clients by the contents of
--   their requests. For that, you can use <a>getRequest</a> and
--   <a>putResponse</a>, which allow you to inspect the request details
--   <i>before</i> you send back a response, if any.
--   
--   If you have any suggestions, bug reports and/or fixes, feel free to
--   send them to <a>mailto:sinisa@bidin.cc</a>.
@package websockets
@version 0.1.2.5

module Network.WebSockets

-- | Accept and perform a handshake, no matter the request contents.
--   
--   As long as the request is well-formed, the client will receive a
--   response saying, essentially, "proceed". Use this function if you
--   don't care who you're connected to, as long as that someone speaks the
--   WebSocket protocol.
--   
--   The function returns either a String in case of error, or a
--   <a>Request</a> on success. The <a>Request</a> is returned purely for
--   logging purposes, since the handshake has already been executed. Use
--   this function immediately after establishing the WebSocket connection.
--   
--   If you wish not to blindly accept requests but to filter them
--   according to their contents, use the <a>getRequest</a> and
--   <a>putResponse</a> functions.
shakeHands :: Handle -> IO (Either String Request)

-- | Reads the client's opening handshake and returns either a
--   <a>Request</a> based on its contents, or a String in case of an error.
getRequest :: Handle -> IO (Either String Request)

-- | Sends an accepting response based on the given <a>Request</a>, thus
--   accepting and ending the handshake.
putResponse :: Handle -> Request -> IO ()

-- | Receive a strict ByteString. Call this function only after having
--   performed the handshake. This function will block until an entire
--   frame is read. If the writing end of the handle is closed, the
--   function returns an empty ByteString.
getFrame :: Handle -> IO ByteString

-- | Send a strict ByteString. Call this function only after having
--   performed the handshake.
putFrame :: Handle -> ByteString -> IO ()

-- | Returns the requested host.
reqHost :: Request -> String

-- | Returns the requested path.
reqPath :: Request -> String

-- | Returns the origin of the request.
reqOrigin :: Request -> String

-- | Returns the requested location. Equal to <tt>(\r -&gt; "ws://" ++
--   reqHost r ++ reqPath r)</tt>.
reqLocation :: Request -> String

-- | Contains the request details, accessible via the <a>reqHost</a>,
--   <a>reqPath</a>, <a>reqOrigin</a> and <a>reqLocation</a> functions.
data Request
instance Show Request