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.