// Generated by Lisette bindgen
// Source: mime/multipart (Go stdlib)
// Go: 1.25.10
// Lisette: 0.2.1

import "go:io"
import "go:net/textproto"

/// FileContentDisposition returns the value of a Content-Disposition header
/// with the provided field name and file name.
pub fn FileContentDisposition(fieldname: string, filename: string) -> string

/// NewReader creates a new multipart [Reader] reading from r using the
/// given MIME boundary.
/// 
/// The boundary is usually obtained from the "boundary" parameter of
/// the message's "Content-Type" header. Use [mime.ParseMediaType] to
/// parse such headers.
pub fn NewReader(r: io.Reader, boundary: string) -> Ref<Reader>

/// NewWriter returns a new multipart [Writer] with a random boundary,
/// writing to w.
pub fn NewWriter(w: io.Writer) -> Ref<Writer>

/// File is an interface to access the file part of a multipart message.
/// Its contents may be either stored in memory or on disk.
/// If stored on disk, the File's underlying concrete type will be an *os.File.
pub interface File {
  fn Close() -> Result<(), error>
  fn Read(mut p: Slice<byte>) -> Partial<int, error>
  fn ReadAt(mut p: Slice<byte>, off: int64) -> Partial<int, error>
  fn Seek(offset: int64, whence: int) -> Result<int64, error>
}

/// A FileHeader describes a file part of a multipart request.
pub struct FileHeader {
  pub Filename: string,
  pub Header: textproto.MIMEHeader,
  pub Size: int64,
}

/// Form is a parsed multipart form.
/// Its File parts are stored either in memory or on disk,
/// and are accessible via the [*FileHeader]'s Open method.
/// Its Value parts are stored as strings.
/// Both are keyed by field name.
pub struct Form {
  pub Value: Map<string, Slice<string>>,
  pub File: Map<string, Slice<Option<Ref<FileHeader>>>>,
}

/// A Part represents a single part in a multipart body.
pub struct Part {
  pub Header: textproto.MIMEHeader,
}

/// Reader is an iterator over parts in a MIME multipart body.
/// Reader's underlying parser consumes its input as needed. Seeking
/// isn't supported.
pub type Reader

/// A Writer generates multipart messages.
pub type Writer

/// ErrMessageTooLarge is returned by ReadForm if the message form
/// data is too large to be processed.
pub var ErrMessageTooLarge: error

impl FileHeader {
  /// Open opens and returns the [FileHeader]'s associated File.
  fn Open(self: Ref<FileHeader>) -> Result<File, error>
}

impl Form {
  /// RemoveAll removes any temporary files associated with a [Form].
  fn RemoveAll(self: Ref<Form>) -> Result<(), error>
}

impl Part {
  #[allow(unused_result)]
  fn Close(self: Ref<Part>) -> Result<(), error>

  /// FileName returns the filename parameter of the [Part]'s Content-Disposition
  /// header. If not empty, the filename is passed through filepath.Base (which is
  /// platform dependent) before being returned.
  fn FileName(self: Ref<Part>) -> string

  /// FormName returns the name parameter if p has a Content-Disposition
  /// of type "form-data".  Otherwise it returns the empty string.
  fn FormName(self: Ref<Part>) -> string

  /// Read reads the body of a part, after its headers and before the
  /// next part (if any) begins.
  fn Read(self: Ref<Part>, mut d: Slice<byte>) -> Partial<int, error>
}

impl Reader {
  /// NextPart returns the next part in the multipart or an error.
  /// When there are no more parts, the error [io.EOF] is returned.
  /// 
  /// As a special case, if the "Content-Transfer-Encoding" header
  /// has a value of "quoted-printable", that header is instead
  /// hidden and the body is transparently decoded during Read calls.
  fn NextPart(self: Ref<Reader>) -> Result<Ref<Part>, error>

  /// NextRawPart returns the next part in the multipart or an error.
  /// When there are no more parts, the error [io.EOF] is returned.
  /// 
  /// Unlike [Reader.NextPart], it does not have special handling for
  /// "Content-Transfer-Encoding: quoted-printable".
  fn NextRawPart(self: Ref<Reader>) -> Result<Ref<Part>, error>

  /// ReadForm parses an entire multipart message whose parts have
  /// a Content-Disposition of "form-data".
  /// It stores up to maxMemory bytes + 10MB (reserved for non-file parts)
  /// in memory. File parts which can't be stored in memory will be stored on
  /// disk in temporary files.
  /// It returns [ErrMessageTooLarge] if all non-file parts can't be stored in
  /// memory.
  fn ReadForm(self: Ref<Reader>, maxMemory: int64) -> Result<Ref<Form>, error>
}

impl Writer {
  /// Boundary returns the [Writer]'s boundary.
  fn Boundary(self: Ref<Writer>) -> string

  /// Close finishes the multipart message and writes the trailing
  /// boundary end line to the output.
  #[allow(unused_result)]
  fn Close(self: Ref<Writer>) -> Result<(), error>

  /// CreateFormField calls [Writer.CreatePart] with a header using the
  /// given field name.
  fn CreateFormField(self: Ref<Writer>, fieldname: string) -> Result<io.Writer, error>

  /// CreateFormFile is a convenience wrapper around [Writer.CreatePart]. It creates
  /// a new form-data header with the provided field name and file name.
  fn CreateFormFile(self: Ref<Writer>, fieldname: string, filename: string) -> Result<io.Writer, error>

  /// CreatePart creates a new multipart section with the provided
  /// header. The body of the part should be written to the returned
  /// [Writer]. After calling CreatePart, any previous part may no longer
  /// be written to.
  fn CreatePart(self: Ref<Writer>, header: textproto.MIMEHeader) -> Result<io.Writer, error>

  /// FormDataContentType returns the Content-Type for an HTTP
  /// multipart/form-data with this [Writer]'s Boundary.
  fn FormDataContentType(self: Ref<Writer>) -> string

  /// SetBoundary overrides the [Writer]'s default randomly-generated
  /// boundary separator with an explicit value.
  /// 
  /// SetBoundary must be called before any parts are created, may only
  /// contain certain ASCII characters, and must be non-empty and
  /// at most 70 bytes long.
  fn SetBoundary(self: Ref<Writer>, boundary: string) -> Result<(), error>

  /// WriteField calls [Writer.CreateFormField] and then writes the given value.
  fn WriteField(self: Ref<Writer>, fieldname: string, value: string) -> Result<(), error>
}
