http-client-0.7.14: An HTTP client engine

Safe Haskell | Safe-Inferred
Language | Haskell2010

Network.HTTP.Client.MultipartFormData

Contents

- Part type
- Constructing parts
- Headers
- Building form data
- Boundary
- Misc

Description

This module handles building multipart/form-data. Example usage:

    {-# LANGUAGE OverloadedStrings #-}
    import Network
    import Network.HTTP.Client
    import Network.HTTP.Client.MultipartFormData

    import Data.Text.Encoding as TE

    import Control.Monad

    main = void $ withManager defaultManagerSettings $ \m -> do
        req1 <- parseRequest "http://random-cat-photo.net/cat.jpg"
        res <- httpLbs req1 m
        req2 <- parseRequest "http://example.org/~friedrich/blog/addPost.hs"
        flip httpLbs m =<<
            (formDataBody [partBS "title" "Bleaurgh"
                          ,partBS "text" $ TE.encodeUtf8 "矢田矢田矢田矢田矢田"
                          ,partFileSource "file1" "/home/friedrich/Photos/MyLittlePony.jpg"
                          ,partFileRequestBody "file2" "cat.jpg" $ RequestBodyLBS $ responseBody res]
                req2)

Synopsis

- type Part = PartM IO
- data PartM m
- partName :: PartM m -> Text
- partFilename :: PartM m -> Maybe String
- partContentType :: PartM m -> Maybe MimeType
- partHeaders :: PartM m -> [Header]
- partGetBody :: PartM m -> m RequestBody
- partBS :: Applicative m => Text -> ByteString -> PartM m
- partLBS :: Applicative m => Text -> ByteString -> PartM m
- partFile :: Text -> FilePath -> Part
- partFileSource :: Text -> FilePath -> Part
- partFileSourceChunked :: Text -> FilePath -> Part
- partFileRequestBody :: Applicative m => Text -> FilePath -> RequestBody -> PartM m
- partFileRequestBodyM :: Text -> FilePath -> m RequestBody -> PartM m
- addPartHeaders :: PartM m -> [Header] -> PartM m
- formDataBody :: MonadIO m => [Part] -> Request -> m Request
- formDataBodyWithBoundary :: Applicative m => ByteString -> [PartM m] -> Request -> m Request
- webkitBoundary :: IO ByteString
- webkitBoundaryPure :: RandomGen g => g -> (ByteString, g)
- renderParts :: Applicative m => ByteString -> [PartM m] -> m RequestBody
- renderPart :: Functor m => ByteString -> PartM m -> m RequestBody

# Part type

type Part = PartM IO #

data PartM m #

A single part of a multipart message.

#### Instances

Instances details

Show (PartM m) # |
Instance details Defined in Network.HTTP.Client.MultipartFormData Methods showsPrec :: Int -> PartM m -> ShowS show :: PartM m -> String showList :: [PartM m] -> ShowS

partName :: PartM m -> Text #

Name of the corresponding <input>

partFilename :: PartM m -> Maybe String #

A file name, if this is an attached file

partContentType :: PartM m -> Maybe MimeType #

Content type

partHeaders :: PartM m -> [Header] #

List of additional headers

partGetBody :: PartM m -> m RequestBody #

Action in m which returns the body of a message.

# Constructing parts

partBS #

Arguments

:: Applicative m |
=> Text | Name of the corresponding <input>.
-> ByteString | The body for this `Part`.
-> PartM m |

Make a `Part` whose content is a strict `ByteString`.

The `Part` does not have a file name or content type associated with it.

partLBS #

Arguments

:: Applicative m |
=> Text | Name of the corresponding <input>.
-> ByteString | The body for this `Part`.
-> PartM m |

Make a `Part` whose content is a lazy `ByteString`.

The `Part` does not have a file name or content type associated with it.

partFile #

Arguments

:: Text | Name of the corresponding <input>.
-> FilePath | The name of the local file to upload.
-> Part |

Make a `Part` from a file.

The entire file will reside in memory at once. If you want constant memory usage, use `partFileSource`.

The `FilePath` supplied will be used as the file name of the `Part`. If you do not want to reveal this name to the server, you must remove it prior to uploading.

The `Part` does not have a content type associated with it.

partFileSource #

Arguments

:: Text | Name of the corresponding <input>.
-> FilePath | The name of the local file to upload.
-> Part |

Stream a `Part` from a file.

The `FilePath` supplied will be used as the file name of the `Part`. If you do not want to reveal this name to the server, you must remove it prior to uploading.

The `Part` does not have a content type associated with it.

partFileSourceChunked :: Text -> FilePath -> Part #

`partFileSourceChunked` will read a file and send it in chunks.

Note that not all servers support this. Only use `partFileSourceChunked` if you know the server you're sending to supports chunked request bodies.

The `FilePath` supplied will be used as the file name of the `Part`. If you do not want to reveal this name to the server, you must remove it prior to uploading.

The `Part` does not have a content type associated with it.

partFileRequestBody #

Arguments

:: Applicative m |
=> Text | Name of the corresponding <input>.
-> FilePath | File name to supply to the server.
-> RequestBody | Data to upload.
-> PartM m |

Construct a `Part` from form name, filepath and a `RequestBody`

    partFileRequestBody "who_calls" "caller.json" $ RequestBodyBS "{\"caller\":\"Jason J Jason\"}"

    -- empty upload form
    partFileRequestBody "file" mempty mempty

The `Part` does not have a content type associated with it.

partFileRequestBodyM #

Arguments

:: Text | Name of the corresponding <input>.
-> FilePath | File name to supply to the server.
-> m RequestBody | Action that will supply data to upload.
-> PartM m |

Construct a `Part` from action returning the `RequestBody`

    partFileRequestBodyM "cat_photo" "haskell-the-cat.jpg" $ do
        size <- fromInteger <$> withBinaryFile "haskell-the-cat.jpg" ReadMode hFileSize
        return $ RequestBodySource size $ CB.sourceFile "haskell-the-cat.jpg" $= CL.map fromByteString

The `Part` does not have a content type associated with it.

# Headers

addPartHeaders :: PartM m -> [Header] -> PartM m #

Add a list of additional headers to this `Part`.

# Building form data

formDataBody :: MonadIO m => [Part] -> Request -> m Request #

Add form data to the `Request`.

This sets a new `requestBody`, adds a content-type request header and changes the method to POST.

formDataBodyWithBoundary :: Applicative m => ByteString -> [PartM m] -> Request -> m Request #

Add form data with supplied boundary

# Boundary

webkitBoundary :: IO ByteString #

Generate a boundary simillar to those generated by WebKit-based browsers.

webkitBoundaryPure :: RandomGen g => g -> (ByteString, g) #

# Misc

renderParts #

Arguments

:: Applicative m |
=> ByteString | Boundary between parts.
-> [PartM m] |
-> m RequestBody |

Combine the `Part`s to form multipart/form-data body

renderPart #

Arguments

:: Functor m |
=> ByteString | Boundary between parts.
-> PartM m |
-> m RequestBody |