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)  gsk_hook_untrap (_GSK_MIME_MULTIPART_DECODER_HOOK(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)   gsk_hook_block (_GSK_MIME_MULTIPART_DECODER_HOOK(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) gsk_hook_unblock (_GSK_MIME_MULTIPART_DECODER_HOOK(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.