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.