MultipartFormData

open class MultipartFormData

Constructs multipart/form-data for uploads within an HTTP or HTTPS body. There are currently two ways to encode multipart form data. The first way is to encode the data directly in memory. This is very efficient, but can lead to memory issues if the dataset is too large. The second way is designed for larger datasets and will write all the data to a single file on disk with all the proper boundary segmentation. The second approach MUST be used for larger datasets such as video content, otherwise your app may run out of memory when trying to encode the dataset.

For more information on multipart/form-data in general, please refer to the RFC-2388 and RFC-2045 specs as well and the w3 form documentation.

Properties

  • The Content-Type header value containing the boundary used to generate the multipart/form-data.

    Declaration

    Swift

    open lazy var contentType: String { get set }

  • The content length of all body parts used to generate the multipart/form-data not including the boundaries.

    Declaration

    Swift

    public var contentLength: UInt64 { get }

  • The boundary used to separate the body parts in the encoded form data.

    Declaration

    Swift

    public var boundary: String

Lifecycle

  • Creates a multipart form data object.

    Declaration

    Swift

    public init()

    Return Value

    The multipart form data object.

Body Parts

  • Creates a body part from the data and appends it to the multipart form data object.

    The body part data will be encoded using the following format:

    • Content-Disposition: form-data; name=#{name} (HTTP Header)
    • Encoded data

    • Multipart form boundary

    Declaration

    Swift

    public func append(_ data: Data, withName name: String)

    Parameters

    data

    The data to encode into the multipart form data.
    name

    The name to associate with the data in the Content-Disposition HTTP header.

  • Creates a body part from the data and appends it to the multipart form data object.

    The body part data will be encoded using the following format:

    • Content-Disposition: form-data; name=#{name} (HTTP Header)
    • Content-Type: #{generated mimeType} (HTTP Header)
    • Encoded data

    • Multipart form boundary

    Declaration

    Swift

    public func append(_ data: Data, withName name: String, mimeType: String)

    Parameters

    data

    The data to encode into the multipart form data.
    name

    The name to associate with the data in the Content-Disposition HTTP header.
    mimeType

    The MIME type to associate with the data content type in the Content-Type HTTP header.

  • Creates a body part from the data and appends it to the multipart form data object.

    The body part data will be encoded using the following format:

    • Content-Disposition: form-data; name=#{name}; filename=#{filename} (HTTP Header)
    • Content-Type: #{mimeType} (HTTP Header)
    • Encoded file data

    • Multipart form boundary

    Declaration

    Swift

    public func append(_ data: Data, withName name: String, fileName: String, mimeType: String)

    Parameters

    data

    The data to encode into the multipart form data.
    name

    The name to associate with the data in the Content-Disposition HTTP header.
    fileName

    The filename to associate with the data in the Content-Disposition HTTP header.
    mimeType

    The MIME type to associate with the data in the Content-Type HTTP header.

  • Creates a body part from the file and appends it to the multipart form data object.

    The body part data will be encoded using the following format:

    • Content-Disposition: form-data; name=#{name}; filename=#{generated filename} (HTTP Header)
    • Content-Type: #{generated mimeType} (HTTP Header)
    • Encoded file data
    • Multipart form boundary

    The filename in the Content-Disposition HTTP header is generated from the last path component of the fileURL. The Content-Type HTTP header MIME type is generated by mapping the fileURL extension to the system associated MIME type.

    Declaration

    Swift

    public func append(_ fileURL: URL, withName name: String)

    Parameters

    fileURL

    The URL of the file whose content will be encoded into the multipart form data.
    name

    The name to associate with the file content in the Content-Disposition HTTP header.

  • Creates a body part from the file and appends it to the multipart form data object.

    The body part data will be encoded using the following format:

    • Content-Disposition: form-data; name=#{name}; filename=#{filename} (HTTP Header)
    • Content-Type: #{mimeType} (HTTP Header)
    • Encoded file data

    • Multipart form boundary

    Declaration

    Swift

    public func append(_ fileURL: URL, withName name: String, fileName: String, mimeType: String)

    Parameters

    fileURL

    The URL of the file whose content will be encoded into the multipart form data.
    name

    The name to associate with the file content in the Content-Disposition HTTP header.
    fileName

    The filename to associate with the file content in the Content-Disposition HTTP header.
    mimeType

    The MIME type to associate with the file content in the Content-Type HTTP header.

  • Creates a body part from the stream and appends it to the multipart form data object.

    The body part data will be encoded using the following format:

    • Content-Disposition: form-data; name=#{name}; filename=#{filename} (HTTP Header)
    • Content-Type: #{mimeType} (HTTP Header)
    • Encoded stream data

    • Multipart form boundary

    Declaration

    Swift

    public func append(
	_ stream: InputStream,
	withLength length: UInt64,
	name: String,
	fileName: String,
	mimeType: String)

    Parameters

    stream

    The input stream to encode in the multipart form data.
    length

    The content length of the stream.
    name

    The name to associate with the stream content in the Content-Disposition HTTP header.
    fileName

    The filename to associate with the stream content in the Content-Disposition HTTP header.
    mimeType

    The MIME type to associate with the stream content in the Content-Type HTTP header.

  • Creates a body part with the headers, stream and length and appends it to the multipart form data object.

    The body part data will be encoded using the following format:

    • HTTP headers
    • Encoded stream data

    • Multipart form boundary

    Declaration

    Swift

    public func append(_ stream: InputStream, withLength length: UInt64, headers: HTTPHeaders)

    Parameters

    stream

    The input stream to encode in the multipart form data.
    length

    The content length of the stream.
    headers

    The HTTP headers for the body part.

Data Encoding

  • Encodes all the appended body parts into a single Data value.

    It is important to note that this method will load all the appended body parts into memory all at the same time. This method should only be used when the encoded data will have a small memory footprint. For large data cases, please use the writeEncodedDataToDisk(fileURL:completionHandler:) method.

    Throws

    An AFError if encoding encounters an error.

    Declaration

    Swift

    public func encode() throws -> Data

    Return Value

    The encoded Data if encoding is successful.

  • Writes the appended body parts into the given file URL.

    This process is facilitated by reading and writing with input and output streams, respectively. Thus, this approach is very memory efficient and should be used for large body part data.

    Throws

    An AFError if encoding encounters an error.

    Declaration

    Swift

    public func writeEncodedData(to fileURL: URL) throws

    Parameters

    fileURL

    The file URL to write the multipart form data into.