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


-- | Create WebSocket servers
--   
--   A library for creating WebSocket-capable servers, where the
--   implemented protocol is defined here: <a>http://is.gd/eSdLB</a>.
--   
--   This library is tested with Chromium &gt;=7, Opera &gt;=11 and Firefox
--   &gt;=4 and is a work in progress. (Note: many of these newest browsers
--   have recently stopped shipping with websockets enabled by default, due
--   to security issues which are yet to be resolved.)
--   
--   An example of usage can be found in the Network.WebSockets module
--   documentation.
@package websockets
@version 0.3.0.0


-- | 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)
--   
--   -- Accepts clients, spawns a single handler for each one.
--   main :: IO ()
--   main = withSocketsDo $ do
--     socket &lt;- listenOn (PortNumber 8088)
--     putStrLn "Listening on port 8088."
--     forever $ do
--       (h, _, _) &lt;- accept socket
--       forkIO (talkTo h)
--   
--   -- Shakes hands with client. If no error, starts talking.
--   talkTo :: Handle -&gt; IO ()
--   talkTo h = do
--     request &lt;- shakeHands h
--     case request of
--       Left err -&gt; print err
--       Right  _ -&gt; do
--         putFrame h (fromString "Do you read me, Lieutenant Bowie?")
--         putStrLn "Shook hands, sent welcome message."
--         talkLoop h
--   
--   -- Talks to the client (by echoing messages back) until EOF.
--   talkLoop :: Handle -&gt; IO ()
--   talkLoop h = do
--     msg &lt;- getFrame h
--     if B.null msg
--        then do
--          putStrLn "EOF encountered. Closing handle."
--          hClose h
--        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>. Thanks!
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 <a>HandshakeError</a> 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 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 HandshakeError Request)

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

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

-- | Returns an accepting response based on the given <a>Request</a>.
--   <a>putResponse</a> uses this function internally.
createResponse :: Request -> ByteString

-- | 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 ()

-- | Constructs the response token by using the two security keys the and
--   eight-byte token given in the request, as defined by the protocol.
createToken :: Request -> ByteString

-- | Contains the request details.
data Request
Request :: String -> String -> String -> String -> String -> String -> Request

-- | The requested host.
reqHost :: Request -> String

-- | The requested path.
reqPath :: Request -> String

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

-- | The first security key.
reqKey1 :: Request -> String

-- | The second security key.
reqKey2 :: Request -> String

-- | The given eight-byte token.
reqToken :: Request -> String

-- | Error in case of failed handshake.
data HandshakeError
HsIOError :: String -> HandshakeError
HsInvalidGETRequest :: String -> HandshakeError
HsInvalidHeaderLine :: String -> HandshakeError
HsMissingHeaderKeys :: String -> HandshakeError
HsBadFirstSecurityKey :: String -> HandshakeError
HsBadSecondSecurityKey :: String -> HandshakeError
instance Show HandshakeError
instance Show Request