CamelDataWrapper

## CamelDataWrapper CamelDataWrapper |

## Synopsis

    struct              CamelDataWrapper;
    CamelDataWrapper *  camel_data_wrapper_new              (void);
    GByteArray *        camel_data_wrapper_get_byte_array   (CamelDataWrapper *data_wrapper);
    void                camel_data_wrapper_set_mime_type    (CamelDataWrapper *data_wrapper,
                                                             const gchar *mime_type);
    gchar *             camel_data_wrapper_get_mime_type    (CamelDataWrapper *data_wrapper);
    CamelContentType *  camel_data_wrapper_get_mime_type_field
                                                            (CamelDataWrapper *data_wrapper);
    void                camel_data_wrapper_set_mime_type_field
                                                            (CamelDataWrapper *data_wrapper,
                                                             CamelContentType *mime_type);
    gboolean            camel_data_wrapper_is_offline       (CamelDataWrapper *data_wrapper);
    gssize              camel_data_wrapper_write_to_stream_sync
                                                            (CamelDataWrapper *data_wrapper,
                                                             CamelStream *stream,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                camel_data_wrapper_write_to_stream  (CamelDataWrapper *data_wrapper,
                                                             CamelStream *stream,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gssize              camel_data_wrapper_write_to_stream_finish
                                                            (CamelDataWrapper *data_wrapper,
                                                             GAsyncResult *result,
                                                             GError **error);
    gssize              camel_data_wrapper_decode_to_stream_sync
                                                            (CamelDataWrapper *data_wrapper,
                                                             CamelStream *stream,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                camel_data_wrapper_decode_to_stream (CamelDataWrapper *data_wrapper,
                                                             CamelStream *stream,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gssize              camel_data_wrapper_decode_to_stream_finish
                                                            (CamelDataWrapper *data_wrapper,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            camel_data_wrapper_construct_from_stream_sync
                                                            (CamelDataWrapper *data_wrapper,
                                                             CamelStream *stream,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                camel_data_wrapper_construct_from_stream
                                                            (CamelDataWrapper *data_wrapper,
                                                             CamelStream *stream,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            camel_data_wrapper_construct_from_stream_finish
                                                            (CamelDataWrapper *data_wrapper,
                                                             GAsyncResult *result,
                                                             GError **error);
    enum                CamelDataWrapperLock;
    void                camel_data_wrapper_lock             (CamelDataWrapper *data_wrapper,
                                                             CamelDataWrapperLock lock);
    void                camel_data_wrapper_unlock           (CamelDataWrapper *data_wrapper,
                                                             CamelDataWrapperLock lock);

## Object Hierarchy

      GObject
       +----CamelObject
             +----CamelDataWrapper
                   +----CamelMedium
                   +----CamelMultipart

## Description

## Details

### struct CamelDataWrapper

    struct CamelDataWrapper;

### camel_data_wrapper_new ()

    CamelDataWrapper *  camel_data_wrapper_new              (void);

Create a new CamelDataWrapper object.

Returns : | a new CamelDataWrapper object

### camel_data_wrapper_get_byte_array ()

    GByteArray *        camel_data_wrapper_get_byte_array   (CamelDataWrapper *data_wrapper);

Returns the GByteArray being used to hold the contents of `data_wrapper`.

Note, it's up to the caller to use this in a thread-safe manner.

`data_wrapper` : | a CamelDataWrapper
Returns : | the GByteArray for `data_wrapper`

Since 3.2

### camel_data_wrapper_set_mime_type ()

    void                camel_data_wrapper_set_mime_type    (CamelDataWrapper *data_wrapper,
                                                             const gchar *mime_type);

This sets the data wrapper's MIME type.

It might fail, but you won't know. It will allow you to set Content-Type parameters on the data wrapper, which are meaningless. You should not be allowed to change the MIME type of a data wrapper that contains data, or at least, if you do, it should invalidate the data.

`data_wrapper` : | a CamelDataWrapper
`mime_type` : | a MIME type

### camel_data_wrapper_get_mime_type ()

    gchar *             camel_data_wrapper_get_mime_type    (CamelDataWrapper *data_wrapper);

`data_wrapper` : | a CamelDataWrapper
Returns : | the MIME type which must be freed by the caller

### camel_data_wrapper_get_mime_type_field ()

    CamelContentType *  camel_data_wrapper_get_mime_type_field
                                                            (CamelDataWrapper *data_wrapper);

`data_wrapper` : | a CamelDataWrapper
Returns : | the parsed form of the data wrapper's MIME type

### camel_data_wrapper_set_mime_type_field ()

    void                camel_data_wrapper_set_mime_type_field
                                                            (CamelDataWrapper *data_wrapper,
                                                             CamelContentType *mime_type);

This sets the data wrapper's MIME type. It suffers from the same flaws as `camel_data_wrapper_set_mime_type()`.

`data_wrapper` : | a CamelDataWrapper
`mime_type` : | a CamelContentType

### camel_data_wrapper_is_offline ()

    gboolean            camel_data_wrapper_is_offline       (CamelDataWrapper *data_wrapper);

`data_wrapper` : | a CamelDataWrapper
Returns : | whether `data_wrapper` is "offline" (data stored remotely) or not. Some optional code paths may choose to not operate on offline data.

### camel_data_wrapper_write_to_stream_sync ()

    gssize              camel_data_wrapper_write_to_stream_sync
                                                            (CamelDataWrapper *data_wrapper,
                                                             CamelStream *stream,
                                                             GCancellable *cancellable,
                                                             GError **error);

Writes the content of `data_wrapper` to `stream` in a machine-independent format appropriate for the data. It should be possible to construct an equivalent data wrapper object later by passing this stream to `camel_data_wrapper_construct_from_stream_sync()`.

### Note

This function may block even if the given output stream does not. For example, the content may have to be fetched across a network before it can be written to `stream`.

`data_wrapper` : | a CamelDataWrapper
`stream` : | a CamelStream for output
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | the number of bytes written, or `-1` on error

Since 3.0

### camel_data_wrapper_write_to_stream ()

    void                camel_data_wrapper_write_to_stream  (CamelDataWrapper *data_wrapper,
                                                             CamelStream *stream,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously writes the content of `data_wrapper` to `stream` in a machine-independent format appropriate for the data. It should be possible to construct an equivalent data wrapper object later by passing this stream to `camel_data_wrapper_construct_from_stream()`.

When the operation is finished, `callback` will be called. You can then call `camel_data_wrapper_write_to_stream_finish()` to get the result of the operation.

`data_wrapper` : | a CamelDataWrapper
`stream` : | a CamelStream for writed data to be written to
`io_priority` : | the I/O priority of the request
`cancellable` : | optional GCancellable object, or `NULL`
`callback` : | a GAsyncReadyCallback to call when the request is satisfied
`user_data` : | data to pass to the callback function

Since 3.0

### camel_data_wrapper_write_to_stream_finish ()

    gssize              camel_data_wrapper_write_to_stream_finish
                                                            (CamelDataWrapper *data_wrapper,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes the operation started with `camel_data_wrapper_write_to_stream()`.

`data_wrapper` : | a CamelDataWrapper
`result` : | a GAsyncResult
`error` : | return location for a GError, or `NULL`
Returns : | the number of bytes written, or `-1` or error

Since 3.0

### camel_data_wrapper_decode_to_stream_sync ()

    gssize              camel_data_wrapper_decode_to_stream_sync
                                                            (CamelDataWrapper *data_wrapper,
                                                             CamelStream *stream,
                                                             GCancellable *cancellable,
                                                             GError **error);

Writes the decoded data content to `stream`.

### Note

This function may block even if the given output stream does not. For example, the content may have to be fetched across a network before it can be written to `stream`.

`data_wrapper` : | a CamelDataWrapper
`stream` : | a CamelStream for decoded data to be written to
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | the number of bytes written, or `-1` on error

Since 3.0

### camel_data_wrapper_decode_to_stream ()

    void                camel_data_wrapper_decode_to_stream (CamelDataWrapper *data_wrapper,
                                                             CamelStream *stream,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously writes the decoded data content to `stream`.

When the operation is finished, `callback` will be called. You can then call `camel_data_wrapper_decode_to_stream_finish()` to get the result of the operation.

`data_wrapper` : | a CamelDataWrapper
`stream` : | a CamelStream for decoded data to be written to
`io_priority` : | the I/O priority of the request
`cancellable` : | optional GCancellable object, or `NULL`
`callback` : | a GAsyncReadyCallback to call when the request is satisfied
`user_data` : | data to pass to the callback function

Since 3.0

### camel_data_wrapper_decode_to_stream_finish ()

    gssize              camel_data_wrapper_decode_to_stream_finish
                                                            (CamelDataWrapper *data_wrapper,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes the operation started with `camel_data_wrapper_decode_to_stream()`.

`data_wrapper` : | a CamelDataWrapper
`result` : | a GAsyncResult
`error` : | return location for a GError, or `NULL`
Returns : | the number of bytes written, or `-1` on error

Since 3.0

### camel_data_wrapper_construct_from_stream_sync ()

    gboolean            camel_data_wrapper_construct_from_stream_sync
                                                            (CamelDataWrapper *data_wrapper,
                                                             CamelStream *stream,
                                                             GCancellable *cancellable,
                                                             GError **error);

Constructs the content of `data_wrapper` from the given `stream`.

`data_wrapper` : | a CamelDataWrapper
`stream` : | an input CamelStream
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on error

Since 3.0

### camel_data_wrapper_construct_from_stream ()

    void                camel_data_wrapper_construct_from_stream
                                                            (CamelDataWrapper *data_wrapper,
                                                             CamelStream *stream,
                                                             gint io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously constructs the content of `data_wrapper` from the given `stream`.

When the operation is finished, `callback` will be called. You can then call `camel_data_wrapper_construct_from_stream_finish()` to get the result of the operation.

`data_wrapper` : | a CamelDataWrapper
`stream` : | an input CamelStream
`io_priority` : | the I/O priority of the request
`cancellable` : | optional GCancellable object, or `NULL`
`callback` : | a GAsyncReadyCallback to call when the request is satisfied
`user_data` : | data to pass to the callback function

Since 3.0

### camel_data_wrapper_construct_from_stream_finish ()

    gboolean            camel_data_wrapper_construct_from_stream_finish
                                                            (CamelDataWrapper *data_wrapper,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes the operation started with `camel_data_wrapper_construct_from_stream()`.

`data_wrapper` : | a CamelDataWrapper
`result` : | a GAsyncResult
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on error

Since 3.0

### enum CamelDataWrapperLock

    typedef enum {
    	CAMEL_DATA_WRAPPER_STREAM_LOCK
    } CamelDataWrapperLock;

Since 2.32

### camel_data_wrapper_lock ()

    void                camel_data_wrapper_lock             (CamelDataWrapper *data_wrapper,
                                                             CamelDataWrapperLock lock);

Locks `data_wrapper`'s `lock`. Unlock it with `camel_data_wrapper_unlock()`.

`data_wrapper` : | a CamelDataWrapper
`lock` : | lock type to lock

Since 2.32

### camel_data_wrapper_unlock ()

    void                camel_data_wrapper_unlock           (CamelDataWrapper *data_wrapper,
                                                             CamelDataWrapperLock lock);

Unlocks `data_wrapper`'s `lock`, previously locked with `camel_data_wrapper_lock()`.

`data_wrapper` : | a CamelDataWrapper
`lock` : | lock type to unlock

Since 2.32