|
| Network.Browser | | Portability | non-portable (not tested) | | Stability | experimental | | Maintainer | Sigbjorn Finne <sigbjorn.finne@gmail.com> |
|
|
|
| Description |
Session-level interactions over HTTP.
The Network.Browser goes beyond the basic Network.HTTP functionality in
providing support for more involved, and real, request/response interactions over
HTTP. Additional features supported are:
- HTTP Authentication handling
- Transparent handling of redirects
- Cookie stores + transmission.
- Transaction logging
- Proxy-mediated connections.
Example use:
do
rsp <- Network.Browser.browse $ do
setAllowRedirects True -- handle HTTP redirects
request $ getRequest "http://google.com/"
fmap (take 100) (getResponseBody rsp)
|
|
| Synopsis |
|
|
|
| Documentation |
|
| data BrowserState connection |
| BrowserState is the (large) record type tracking the current
settings of the browser.
|  Instances | |
|
|
| data BrowserAction conn a |
| BrowserAction is the IO monad, but carrying along a BrowserState.
| | Instances | |
|
|
| data Proxy |
| Proxy specifies if a proxy should be used for the request.
| | Constructors | |
|
|
| browse :: BrowserAction conn a -> IO a |
| browse act is the toplevel action to perform a BrowserAction.
Example use: browse (request (getRequest yourURL)).
|
|
| request :: HStream ty => Request ty -> BrowserAction (HandleStream ty) (URI, Response ty) |
| request httpRequest tries to submit the Request httpRequest
to some HTTP server (possibly going via a proxy, see setProxy.)
Upon successful delivery, the URL where the response was fetched from
is returned along with the Response itself.
|
|
| getBrowserState :: BrowserAction t (BrowserState t) |
| getBrowserState returns the current browser config. Useful
for restoring state across BrowserActions.
|
|
| withBrowserState :: BrowserState t -> BrowserAction t a -> BrowserAction t a |
| withBrowserAction st act performs act with BrowserState st.
|
|
| setAllowRedirects :: Bool -> BrowserAction t () |
| setAllowRedirects onOff toggles the willingness to
follow redirects (HTTP responses with 3xx status codes).
|
|
| getAllowRedirects :: BrowserAction t Bool |
| getAllowRedirects returns current setting of the do-chase-redirects flag.
|
|
| setMaxRedirects :: Maybe Int -> BrowserAction t () |
| setMaxRedirects maxCount sets the maxiumum number of forwarding hops
we are willing to jump through. A no-op if the count is negative; if zero,
the max is set to whatever default applies. Notice that setting the max
redirects count does not enable following of redirects itself; use
setAllowRedirects to do so.
|
|
| getMaxRedirects :: BrowserAction t (Maybe Int) |
| getMaxRedirects returns the current setting for the max-redirect count.
If Nothing, the Network.Browser's default is used.
|
|
| data Authority |
| Authority specifies the HTTP Authentication method to use for
a given domain/realm; Basic or Digest.
| | Constructors | |
|
|
| getAuthorities :: BrowserAction t [Authority] |
| getAuthorities return the current set of Authoritys known
to the browser.
|
|
| setAuthorities :: [Authority] -> BrowserAction t () |
|
| addAuthority :: Authority -> BrowserAction t () |
|
| data Challenge |
|
|
| data Qop |
| Constructors | | | Instances | |
|
|
| data Algorithm |
| Algorithm controls the digest algorithm to, MD5 or MD5Session.
| | Constructors | | | Instances | |
|
|
| getAuthorityGen :: BrowserAction t (URI -> String -> IO (Maybe (String, String))) |
| getAuthorityGen returns the current authority generator
|
|
| setAuthorityGen :: (URI -> String -> IO (Maybe (String, String))) -> BrowserAction t () |
| setAuthorityGen genAct sets the auth generator to genAct.
|
|
| setAllowBasicAuth :: Bool -> BrowserAction t () |
| setAllowBasicAuth onOff enables/disables HTTP Basic Authentication.
|
|
| setMaxErrorRetries :: Maybe Int -> BrowserAction t () |
| setMaxErrorRetries mbMax sets the maximum number of attempts at
transmitting a request. If Nothing, rever to default max.
|
|
| getMaxErrorRetries :: BrowserAction t (Maybe Int) |
| getMaxErrorRetries returns the current max number of error retries.
|
|
| setMaxAuthAttempts :: Maybe Int -> BrowserAction t () |
| setMaxAuthAttempts mbMax sets the maximum number of authentication attempts
to do. If Nothing, rever to default max.
|
|
| getMaxAuthAttempts :: BrowserAction t (Maybe Int) |
| getMaxAuthAttempts returns the current max auth attempts. If Nothing,
the browser's default is used.
|
|
| setCookieFilter :: (URI -> Cookie -> IO Bool) -> BrowserAction t () |
| setCookieFilter fn sets the cookie acceptance filter to fn.
|
|
| getCookieFilter :: BrowserAction t (URI -> Cookie -> IO Bool) |
| getCookieFilter returns the current cookie acceptance filter.
|
|
| defaultCookieFilter :: URI -> Cookie -> IO Bool |
| defaultCookieFilter is the initial cookie acceptance filter.
It welcomes them all into the store :-)
|
|
| userCookieFilter :: URI -> Cookie -> IO Bool |
| userCookieFilter is a handy acceptance filter, asking the
user if he/she is willing to accept an incoming cookie before
adding it to the store.
|
|
| data Cookie |
| Cookie is the Haskell representation of HTTP cookie values.
See its relevant specs for authoritative details.
| | Constructors | | | Instances | |
|
|
| getCookies :: BrowserAction t [Cookie] |
| getCookies returns the current set of cookies known to
the browser.
|
|
| setCookies :: [Cookie] -> BrowserAction t () |
| setCookies cookies replaces the set of cookies known to
the browser to cookies. Useful when wanting to restore cookies
used across browse invocations.
|
|
| addCookie :: Cookie -> BrowserAction t () |
| addCookie c adds a cookie to the browser state, removing duplicates.
|
|
| setErrHandler :: (String -> IO ()) -> BrowserAction t () |
| setErrHandler sets the IO action to call when
the browser reports running errors. To disable any
such, set it to const (return ()).
|
|
| setOutHandler :: (String -> IO ()) -> BrowserAction t () |
| setErrHandler sets the IO action to call when
the browser chatters info on its running. To disable any
such, set it to const (return ()).
|
|
| setEventHandler :: Maybe (BrowserEvent ty -> BrowserAction ty ()) -> BrowserAction ty () |
| setEventHandler onBrowserEvent configures event handling.
If onBrowserEvent is Nothing, event handling is turned off;
setting it to Just onEv causes the onEv IO action to be
notified of browser events during the processing of a request
by the Browser pipeline.
|
|
| data BrowserEvent ty |
| BrowserEvent is the event record type that a user-defined handler, set
via setEventHandler, will be passed. It indicates various state changes
encountered in the processing of a given RequestID, along with timestamps
at which they occurred.
| | Constructors | |
|
|
| data BrowserEventType ty |
| BrowserEventType is the enumerated list of events that the browser
internals will report to a user-defined event handler.
| | Constructors | | OpenConnection | | | ReuseConnection | | | RequestSent | | | ResponseEnd ResponseData | | | ResponseFinish | |
|
|
|
| type RequestID = Int |
|
| setProxy :: Proxy -> BrowserAction t () |
| setProxy p will disable proxy usage if p is NoProxy.
If p is Proxy proxyURL mbAuth, then proxyURL is interpreted
as the URL of the proxy to use, possibly authenticating via
Authority information in mbAuth.
|
|
| getProxy :: BrowserAction t Proxy |
| getProxy returns the current proxy settings.
|
|
| setDebugLog :: Maybe String -> BrowserAction t () |
| setDebugLog mbFile turns off debug logging iff mbFile
is Nothing. If set to Just fStem, logs of browser activity
is appended to files of the form fStem-url-authority, i.e.,
fStem is just the prefix for a set of log files, one per host/authority.
|
|
| out :: String -> BrowserAction t () |
|
| err :: String -> BrowserAction t () |
|
| ioAction :: IO a -> BrowserAction t a |
| Lifts an IO action into the BrowserAction monad.
|
|
| defaultGETRequest :: URI -> Request_String |
|
| defaultGETRequest_ :: BufferType a => URI -> Request a |
|
| formToRequest :: Form -> Request_String |
|
| uriDefaultTo :: URI -> URI -> URI |
| uriDefaultTo a b returns a URI that is consistent with the first
argument URI a when read in the context of the second URI b.
If the second argument is not sufficient context for determining
a full URI then anarchy reins.
|
|
| data Form |
|
|
| type FormVar = (String, String) |
|
| Produced by Haddock version 2.4.2 |
