| Safe Haskell | Safe-Infered |
|---|
OpenSSL.BIO
Contents
Description
A BIO is an I/O abstraction, it hides many of the underlying I/O details from an application, if you are writing a pure C application...
I know, we are hacking on Haskell so BIO components like BIO_s_file are hardly needed. But for filter BIOs, such as BIO_f_base64 and BIO_f_cipher, they should be useful too to us.
- data BIO
- data BIO_
- wrapBioPtr :: Ptr BIO_ -> IO BIO
- withBioPtr :: BIO -> (Ptr BIO_ -> IO a) -> IO a
- withBioPtr' :: Maybe BIO -> (Ptr BIO_ -> IO a) -> IO a
- bioPush :: BIO -> BIO -> IO ()
- (==>) :: BIO -> BIO -> IO ()
- (<==) :: BIO -> BIO -> IO ()
- bioJoin :: [BIO] -> IO ()
- bioFlush :: BIO -> IO ()
- bioReset :: BIO -> IO ()
- bioEOF :: BIO -> IO Bool
- bioRead :: BIO -> IO String
- bioReadBS :: BIO -> Int -> IO ByteString
- bioReadLBS :: BIO -> IO ByteString
- bioGets :: BIO -> Int -> IO String
- bioGetsBS :: BIO -> Int -> IO ByteString
- bioGetsLBS :: BIO -> Int -> IO ByteString
- bioWrite :: BIO -> String -> IO ()
- bioWriteBS :: BIO -> ByteString -> IO ()
- bioWriteLBS :: BIO -> ByteString -> IO ()
- newBase64 :: Bool -> IO BIO
- newBuffer :: Maybe Int -> IO BIO
- newMem :: IO BIO
- newConstMem :: String -> IO BIO
- newConstMemBS :: ByteString -> IO BIO
- newConstMemLBS :: ByteString -> IO BIO
- newNullBIO :: IO BIO
Type
BIO chaning
bioPush :: BIO -> BIO -> IO ()Source
Computation of connects bioPush a bb behind a.
Example:
do b64 <- newBase64 True
mem <- newMem
bioPush b64 mem
-- Encode some text in Base64 and write the result to the
-- memory buffer.
bioWrite b64 "Hello, world!"
bioFlush b64
-- Then dump the memory buffer.
bioRead mem >>= putStrLn
BIO control operations
bioFlush :: BIO -> IO ()Source
normally writes out any internally buffered data,
in some cases it is used to signal EOF and that no more data will
be written.
bioFlush bio
bioEOF :: BIO -> IO BoolSource
returns 1 if bioEOF biobio has read EOF, the precise
meaning of EOF varies according to the BIO type.
BIO I/O functions
bioReadBS :: BIO -> Int -> IO ByteStringSource
attempts to read bioReadBS bio lenlen bytes from bio,
then return a ByteString. The actual length of result may be less
than len.
bioReadLBS :: BIO -> IO ByteStringSource
lazily reads all data in bioReadLBS biobio, then return a
LazyByteString.
bioGetsLBS :: BIO -> Int -> IO ByteStringSource
bioGetsLBS does the same as bioGets but returns
LazyByteString.
bioWrite :: BIO -> String -> IO ()Source
lazily writes entire bioWrite bio strstr to bio. The
string doesn't necessarily have to be finite.
bioWriteBS :: BIO -> ByteString -> IO ()Source
writes bioWriteBS bio bsbs to bio.
bioWriteLBS :: BIO -> ByteString -> IO ()Source
lazily writes entire bioWriteLBS bio lbslbs to bio. The
string doesn't necessarily have to be finite.
Base64 BIO filter
newBase64 :: Bool -> IO BIOSource
creates a Base64 BIO filter. This is a filter
bio that base64 encodes any data written through it and decodes any
data read through it.
newBase64 noNL
If noNL flag is True, the filter encodes the data all on one line
or expects the data to be all on one line.
Base64 BIOs do not support bioGets.
bioFlush on a Base64 BIO that is being written through is used to
signal that no more data is to be encoded: this is used to flush
the final block through the BIO.
Buffering BIO filter
creates a buffering BIO filter. Data
written to a buffering BIO is buffered and periodically written to
the next BIO in the chain. Data read from a buffering BIO comes
from the next BIO in the chain.
newBuffer mBufSize
Buffering BIOs support bioGets.
Calling bioReset on a buffering BIO clears any buffered data.
Question: When I created a BIO chain like this and attempted to read from the buf, the buffering BIO weirdly behaved: BIO_read() returned nothing, but both BIO_eof() and BIO_should_retry() returned zero. I tried to examine the source code of crypto/bio/bf_buff.c but it was too complicated to understand. Does anyone know why this happens? The version of OpenSSL was 0.9.7l.
main = withOpenSSL $
do mem <- newConstMem "Hello, world!"
buf <- newBuffer Nothing
mem ==> buf
bioRead buf >>= putStrLn -- This fails, but why?
I am being depressed for this unaccountable failure.
Memory BIO sink/source
creates a memory BIO sink/source. Any data written to
a memory BIO can be recalled by reading from it. Unless the memory
BIO is read only any data read from it is deleted from the BIO.
newMem
Memory BIOs support bioGets.
Calling bioReset on a read write memory BIO clears any data in
it. On a read only BIO it restores the BIO to its original state
and the read only data can be read again.
bioEOF is true if no data is in the BIO.
Every read from a read write memory BIO will remove the data just
read with an internal copy operation, if a BIO contains a lots of
data and it is read in small chunks the operation can be very
slow. The use of a read only memory BIO avoids this problem. If the
BIO must be read write then adding a buffering BIO (newBuffer) to
the chain will speed up the process.
newConstMem :: String -> IO BIOSource
creates a read-only memory BIO source.
newConstMem str
newConstMemBS :: ByteString -> IO BIOSource
is like newConstMemBS bsnewConstMem but takes a ByteString.
newConstMemLBS :: ByteString -> IO BIOSource
is like newConstMemLBS lbsnewConstMem but takes a
LazyByteString.
Null data BIO sink/source
creates a null BIO sink/source. Data written to
the null sink is discarded, reads return EOF.
newNullBIO
A null sink is useful if, for example, an application wishes to digest some data by writing through a digest bio but not send the digested data anywhere. Since a BIO chain must normally include a source/sink BIO this can be achieved by adding a null sink BIO to the end of the chain.