## GskMimeMultipartDecoder

GskMimeMultipartDecoder — read Content-Type multipart/*.

## Synopsis

    gboolean            (*GskMimeMultipartDecoderHook)      (GskMimeMultipartDecoder *multipart_decoder);
    enum                GskMimeMultipartDecoderMode;
                        GskMimeMultipartDecoderClass;
                        GskMimeMultipartDecoder;
    GskMimeMultipartDecoder * gsk_mime_multipart_decoder_new
                                                            (char **kv_pairs);
    void                gsk_mime_multipart_decoder_set_mode (GskMimeMultipartDecoder *decoder,
                                                             GskMimeMultipartDecoderMode mode);
    GskMimeMultipartPiece * gsk_mime_multipart_decoder_get_piece
                                                            (GskMimeMultipartDecoder *decoder);
    #define             gsk_mime_multipart_decoder_trap     (multipart_decoder, func, shutdown, data, destroy)
    #define             gsk_mime_multipart_decoder_untrap   (multipart_decoder)
    #define             gsk_mime_multipart_decoder_block    (multipart_decoder)
    #define             gsk_mime_multipart_decoder_unblock  (multipart_decoder)

## Description

This code implements the MIME multipart encapsulation format, which is defined in "RFC 2046, Section 5: MIME MultipartDecoder Media Types". This format is often encountered parsing form data from webpages.

## Details

### GskMimeMultipartDecoderHook ()

    gboolean            (*GskMimeMultipartDecoderHook)      (GskMimeMultipartDecoder *multipart_decoder);

Function to invoke when a new piece is available.

`multipart_decoder` : | the decoder which can be read from.
Returns : | whether to continue being notified of the availability of un-retrieved pieces.

### enum GskMimeMultipartDecoderMode

    typedef enum
    {
      GSK_MIME_MULTIPART_DECODER_MODE_DEFAULT,
      GSK_MIME_MULTIPART_DECODER_MODE_ALWAYS_MEMORY,
      GSK_MIME_MULTIPART_DECODER_MODE_ALWAYS_STREAM
    } GskMimeMultipartDecoderMode;

Multipart pieces may be streaming or a memory buffer. This gives the user control over which format to use.

(Note: currently GSK_MIME_MULTIPART_DECODER_MODE_DEFAULT acts like GSK_MIME_MULTIPART_DECODER_MODE_ALWAYS_STREAM.)

`GSK_MIME_MULTIPART_DECODER_MODE_DEFAULT` | The pieces may be either streaming, or pure memory, whichever is easier.
`GSK_MIME_MULTIPART_DECODER_MODE_ALWAYS_MEMORY` | The pieces must be memory slabs. They will not be available until all there data has been received and parsed.
`GSK_MIME_MULTIPART_DECODER_MODE_ALWAYS_STREAM` | The pieces must be streams, even if that means allocating a stream for just a few bytes. This is can be slightly inconvenient.

### GskMimeMultipartDecoderClass

    typedef struct {
      GskStreamClass base_class;

      gboolean (*set_poll_new_part) (GskMimeMultipartDecoder *decoder,
    				 gboolean do_polling);
      void     (*shutdown_new_part) (GskMimeMultipartDecoder *decoder);
    } GskMimeMultipartDecoderClass;

### GskMimeMultipartDecoder

    typedef struct {
      GskStream      base_instance;

      /* these are parsed out of the initial key-value pairs. */
      char *type;		/* 3.1: type of the body */
      char *start;		/* 3.2: content-id of root part */
      char *start_info;	/* 3.3: random application information */
    } GskMimeMultipartDecoder;

### gsk_mime_multipart_decoder_new ()

    GskMimeMultipartDecoder * gsk_mime_multipart_decoder_new
                                                            (char **kv_pairs);

Allocate a new MIME multipart decoder, which is a write-only GskStream that converts to a stream of individual pieces.

`kv_pairs` : | key,value pairs of auxillary information parsed along with the Content-Type field.
Returns : |

### gsk_mime_multipart_decoder_set_mode ()

    void                gsk_mime_multipart_decoder_set_mode (GskMimeMultipartDecoder *decoder,
                                                             GskMimeMultipartDecoderMode mode);

Set whether to force the decoder to convert everything to memory or a stream, or it may specify to use whatever the MultipartDecoder internals prefer.

This function should only be called immediately after construction.

`decoder` : | the multipart decoder to affect.
`mode` : | the operating mode of the decoder.

### gsk_mime_multipart_decoder_get_piece ()

    GskMimeMultipartPiece * gsk_mime_multipart_decoder_get_piece
                                                            (GskMimeMultipartDecoder *decoder);

Retrieve a piece of multipart content. Pieces will be retrieve in the order they are received.

`decoder` : | the multipart decoder to retrieve the part.
Returns : | a piece that the caller must `gsk_mime_multipart_piece_unref()`, or NULL if there is no remaining piece.

### gsk_mime_multipart_decoder_trap()

    #define             gsk_mime_multipart_decoder_trap(multipart_decoder, func, shutdown, data, destroy)

Get notification when a MIME piece is available.

`multipart_decoder` : | the decoder to watch.
`func` : | function to invoke when a piece is available. (It will be invoked repeatedly until all the pieces have been dequeued)
`shutdown` : | function to invoke when no more pieces will ever be available.
`data` : | data to pass to `func`, `shutdown` and `destroy`.
`destroy` : | data to call when the trap is destroyed.

### gsk_mime_multipart_decoder_untrap()

    #define             gsk_mime_multipart_decoder_untrap(multipart_decoder)

Untrap the new-piece-available hook. Its destroy method will be run.

`multipart_decoder` : | the decoder to stop watching.

### gsk_mime_multipart_decoder_block()

    #define             gsk_mime_multipart_decoder_block(multipart_decoder)

Stop notifying about new MIME piece availability, if we are currently notifying. Invocations to this function may be stacked; it is undone with `gsk_mime_multipart_decoder_unblock()`.

`multipart_decoder` : | the GskMimeMultipartDecoder to watch.

### gsk_mime_multipart_decoder_unblock()

    #define             gsk_mime_multipart_decoder_unblock(multipart_decoder)

Resume notifying about new MIME piece availability, if we are currently notifying and if this is the last blocker. It undones one invocation of `gsk_mime_multipart_decoder_block()`.

`multipart_decoder` : | the GskMimeMultipartDecoder to stop watching.