gdritter repos ucspi-hs / bc631db
Documentation added Getty Ritter 6 years ago
2 changed file(s) with 46 addition(s) and 4 deletion(s). Collapse all Expand all
1 module Network.UCSPI where
1 module Network.UCSPI
2 ( UCSPIOptions(..)
3 , ucspiClient
4 , ucspiServer
5 ) where
26
37 import Control.Arrow (first)
48 import Data.List (stripPrefix)
5 import System.IO (Handle, hPutStrLn, stderr)
9 import System.IO (Handle, hClose, hPutStrLn, stderr)
610 import System.Posix.IO (fdToHandle)
711 import System.Posix.Types (Fd(..))
812 import System.Environment (getEnvironment)
913
14 -- | The @UCSPI@ spec indicates that applications will receive information
15 -- about their connection through environment variables. A 'UCSPIOptions'
16 -- value will contains all the relevant values filtered out. As most of
17 -- these (save for the protocol name) are prefixed with both the protocol
18 -- name and either @LOCAL@ or @REMOTE@, those values are stripped before
19 -- they are added to the respective lists: for example, if a @UCSPI@
20 -- application for the @TCP@ protocol passes in an environment variable
21 -- @TCPREMOTEPORT=7777@, then the value of 'ucspiProtocol' will be
22 -- @TCP@ and 'ucspiRemoteVars' will contain a pair @(\"PORT\","7777")@.
1023 data UCSPIOptions = UCSPIOptions
1124 { ucspiProtocol :: String
1225 , ucspiLocalVars :: [(String,String)]
2942 }
3043
3144
45 -- | A @UCSPI@ client is passed an options value, a handle which corresponds
46 -- to the reading end of a socket, and a handle which corresponds to the
47 -- writing end of a socket. For example, a sample @UCSPI@ client which
48 -- connects to a server, writes a line, and reads something back, regardless
49 -- of the underlying transport mechanism, would look like
50 --
51 -- > main :: IO ()
52 -- > main = ucspiClient $ \_ rdH wrH -> do
53 -- > hPutStrLn wrH "hello"
54 -- > ln <- hGetLine rdH
55 -- > putStrLn ln
3256 ucspiClient :: (UCSPIOptions -> Handle -> Handle -> IO ()) -> IO ()
3357 ucspiClient client = do
3458 opts <- gatherOptions `fmap` getEnvironment
3862 rdH <- fdToHandle (Fd 6)
3963 wrH <- fdToHandle (Fd 7)
4064 client opts' rdH wrH
65 hClose rdH
66 hClose wrH
4167
68 -- | A @UCSPI@ server is passed only an options value. In order to read from or
69 -- write to the connection, it just uses @stdin@ and @stdout@, which means that
70 -- a server which reads a single line from a client and echoes it back would
71 -- look like
72 --
73 -- > main :: IO ()
74 -- > main = ucspiServer $ \_ -> getLine >>= putStrLn
4275 ucspiServer :: (UCSPIOptions -> IO ()) -> IO ()
4376 ucspiServer server = do
4477 opts <- gatherOptions `fmap` getEnvironment
11 name: ucspi-hs
22 version: 0.1.0.0
3 synopsis: A small Haskell interface to writing @ucspi@-conformant applications
4 -- description:
3 synopsis: Haskell helpers for UCSPI applications
4 description: The @ucspi-hs@ package contains a few small helper functions for
5 writing clients and servers that are intended for use with the
6 <http://cr.yp.to/proto/ucspi.txt UCSPI interface>. This is a
7 Unix-oriented interface in which an external application manages
8 network connections and passes them off to another program which
9 is given the relevant sockets as typical Unix file descriptors.
10 This is a convenient way of building small servers without the
11 boilerplate of socket management, and allows a given application
12 to be trivially reused with different underlying network
13 interfaces.
514 license: BSD3
615 license-file: LICENSE
716 author: Getty Ritter