TnyMimePart

TnyMimePart — A type that defines a mime part

Synopsis

                    TnyMimePart;
                    TnyMimePartIface;
const gchar*        tny_mime_part_get_content_type      (TnyMimePart *self);
gboolean            tny_mime_part_content_type_is       (TnyMimePart *self,
                                                         const gchar *type);
TnyStream*          tny_mime_part_get_stream            (TnyMimePart *self);
TnyStream*          tny_mime_part_get_decoded_stream    (TnyMimePart *self);
gssize              tny_mime_part_write_to_stream       (TnyMimePart *self,
                                                         TnyStream *stream,
                                                         GError **err);
gint                tny_mime_part_construct             (TnyMimePart *self,
                                                         TnyStream *stream,
                                                         const gchar *mime_type,
                                                         const gchar *transfer_encoding);
const gchar*        tny_mime_part_get_filename          (TnyMimePart *self);
const gchar*        tny_mime_part_get_content_id        (TnyMimePart *self);
const gchar*        tny_mime_part_get_description       (TnyMimePart *self);
const gchar*        tny_mime_part_get_content_location  (TnyMimePart *self);
gboolean            tny_mime_part_is_purged             (TnyMimePart *self);
void                tny_mime_part_set_content_location  (TnyMimePart *self,
                                                         const gchar *content_location);
void                tny_mime_part_set_description       (TnyMimePart *self,
                                                         const gchar *description);
void                tny_mime_part_set_content_id        (TnyMimePart *self,
                                                         const gchar *content_id);
void                tny_mime_part_set_filename          (TnyMimePart *self,
                                                         const gchar *filename);
void                tny_mime_part_set_content_type      (TnyMimePart *self,
                                                         const gchar *contenttype);
void                tny_mime_part_set_purged            (TnyMimePart *self);
gboolean            tny_mime_part_is_attachment         (TnyMimePart *self);
gssize              tny_mime_part_decode_to_stream      (TnyMimePart *self,
                                                         TnyStream *stream,
                                                         GError **err);
void                tny_mime_part_get_parts             (TnyMimePart *self,
                                                         TnyList *list);
gint                tny_mime_part_add_part              (TnyMimePart *self,
                                                         TnyMimePart *part);
void                tny_mime_part_del_part              (TnyMimePart *self,
                                                         TnyMimePart *part);
void                tny_mime_part_get_header_pairs      (TnyMimePart *self,
                                                         TnyList *list);
void                tny_mime_part_set_header_pair       (TnyMimePart *self,
                                                         const gchar *name,
                                                         const gchar *value);
void                tny_mime_part_decode_to_stream_async
                                                        (TnyMimePart *self,
                                                         TnyStream *stream,
                                                         TnyMimePartCallback callback,
                                                         TnyStatusCallback status_callback,
                                                         gpointer user_data);
const gchar*        tny_mime_part_get_transfer_encoding (TnyMimePart *self);
void                tny_mime_part_set_transfer_encoding (TnyMimePart *self,
                                                         const gchar *transfer_encoding);

Object Hierarchy

  GInterface
   +----TnyMimePart

Known Derived Interfaces

TnyMimePart is required by TnyMsg.

Known Implementations

TnyMimePart is implemented by TnyCamelMimePart, TnyCamelBsMsg, TnyCamelMsg and TnyCamelBsMimePart.

Description

A mime part is a part of a message. Like the body, an attachment or the PGP key of a message.

Details

TnyMimePart

typedef struct _TnyMimePart TnyMimePart;

A part of a message, like the text of the message or like an attachment

free-function: g_object_unref


TnyMimePartIface

typedef struct {
	GTypeInterface parent;

	const gchar* (*get_content_type) (TnyMimePart *self);
	gboolean (*content_type_is) (TnyMimePart *self, const gchar *content_type);
	TnyStream* (*get_stream) (TnyMimePart *self);
	TnyStream* (*get_decoded_stream) (TnyMimePart *self);
	gssize (*decode_to_stream) (TnyMimePart *self, TnyStream *stream, GError **err);
	gssize (*write_to_stream) (TnyMimePart *self, TnyStream *stream, GError **err);
	gint (*construct) (TnyMimePart *self, TnyStream *stream, const gchar *mime_type, const gchar *transfer_encoding);
	const gchar* (*get_filename) (TnyMimePart *self);
	const gchar* (*get_content_id) (TnyMimePart *self);
	const gchar* (*get_description) (TnyMimePart *self);
	const gchar* (*get_content_location) (TnyMimePart *self);
	gboolean (*is_purged) (TnyMimePart *self);
  
	void (*set_content_location) (TnyMimePart *self, const gchar *content_location); 
	void (*set_description) (TnyMimePart *self, const gchar *description); 
	void (*set_content_id) (TnyMimePart *self, const gchar *content_id); 
	void (*set_filename) (TnyMimePart *self, const gchar *filename);
	void (*set_content_type) (TnyMimePart *self, const gchar *contenttype);
	void (*set_purged) (TnyMimePart *self);
	gboolean (*is_attachment) (TnyMimePart *self);
	void (*get_parts) (TnyMimePart *self, TnyList *list);
	void (*del_part) (TnyMimePart *self, TnyMimePart *part);
	gint (*add_part) (TnyMimePart *self, TnyMimePart *part);
	void (*get_header_pairs) (TnyMimePart *self, TnyList *list);
	void (*set_header_pair) (TnyMimePart *self, const gchar *name, const gchar *value);
	void (*decode_to_stream_async) (TnyMimePart *self, TnyStream *stream, TnyMimePartCallback callback, TnyStatusCallback status_callback, gpointer user_data);
	const gchar* (*get_transfer_encoding) (TnyMimePart *self);
	void (*set_transfer_encoding) (TnyMimePart *self, const gchar *transfer_encoding);
} TnyMimePartIface;


tny_mime_part_get_content_type ()

const gchar*        tny_mime_part_get_content_type      (TnyMimePart *self);

Get the mime part type in the format "type/subtype". You shouldn't free the returned value. In case of NULL, the intended type is usually "text/plain".

self :

a TnyMimePart

Returns :

(null-ok): content-type of a message part as a read-only string or NULL

Since 1.0 audience: application-developer


tny_mime_part_content_type_is ()

gboolean            tny_mime_part_content_type_is       (TnyMimePart *self,
                                                         const gchar *type);

Efficiently checks whether self is of type type. You can use things like "type/ *" for matching. Only '*' works and stands for 'any'. It's not a regular expression nor is it like a regular expression.

Example:

TnyMsg *message = ...
TnyList *parts = tny_simple_list_new ();
tny_mime_part_get_parts (TNY_MIME_PART (message), parts);
iter = tny_list_create_iterator (parts);
while (!tny_iterator_is_done (iter))
{
     TnyMimePart *part = TNY_MIME_PART (tny_iterator_get_current (iter));
     if (tny_mime_part_content_type_is (part, "text/ *"))
             g_print ("Found an E-mail body\n");
     if (tny_mime_part_content_type_is (part, "text/html"))
             g_print ("Found an E-mail HTML body\n"); 
     g_object_unref (part);
     tny_iterator_next (iter);
}
g_object_unref (iter);
g_object_unref (parts);

self :

a TnyMimePart

type :

The content type in the string format "type/subtype"

Returns :

True if the part is the content type, else FALSE

Since 1.0 audience: application-developer


tny_mime_part_get_stream ()

TnyStream*          tny_mime_part_get_stream            (TnyMimePart *self);

Inefficiently get a stream for self. The entire data of the part will be kept in memory until the returned value is unreferenced.

self :

a TnyMimePart

Returns :

an in-memory stream

Since 1.0 audience: application-developer


tny_mime_part_get_decoded_stream ()

TnyStream*          tny_mime_part_get_decoded_stream    (TnyMimePart *self);

Inefficiently get a stream for self. The entire data of the part will be kept in memory until the returned value is unreferenced.

self :

a TnyMimePart

Returns :

an in-memory stream

Since 1.0 audience: application-developer


tny_mime_part_write_to_stream ()

gssize              tny_mime_part_write_to_stream       (TnyMimePart *self,
                                                         TnyStream *stream,
                                                         GError **err);

Efficiently write the content of self to stream. This will not read the data of the part in a memory buffer. In stead it will read the part data while already writing it to stream efficiently. Although there is no hard guarantee about the memory usage either (just that it's the most efficient way).

You probably want to utilise the tny_mime_part_decode_to_stream() method in stead of this one. This method will not attempt to decode the mime part. Mime parts are usually encoded in E-mails.

When the mime part was received in BINARY mode from an IMAP server, then this API has mostly the same effect as the tny_mime_part_decode_to_stream(): You will get a non-encoded version of the data. A small difference will be that the tny_mime_part_decode_to_stream() will decode certain special characters in TEXT mime parts (character set encoding) to UTF-8.

However. A larger difference happens with binary mime parts that where not retrieved using BINARY. For those this API will give you the encoded data as is. This means that you will get a stream spitting out for example BASE64 data.

Example:

int fd = open ("/tmp/attachment.png.base64", O_WRONLY|O_CREAT, S_IRUSR|S_IWUSR);
TnyMimePart *part = ...
if (fd != -1)
{
     TnyFsStream *stream = tny_fs_stream_new (fd);
     tny_mime_part_write_to_stream (part, TNY_STREAM (stream));
     g_object_unref (stream);
}

self :

a TnyMimePart

stream :

a TnyStream

err :

Returns :

Returns -1 on error, or the number of bytes succesfully copied.

Since 1.0 audience: application-developer


tny_mime_part_construct ()

gint                tny_mime_part_construct             (TnyMimePart *self,
                                                         TnyStream *stream,
                                                         const gchar *mime_type,
                                                         const gchar *transfer_encoding);

Set the stream from which the part will read its content

Valid values for transfer_encoding are "7bit", "8bit", "base64", "quoted-printable", "binary" and "x-uuencode"

Example:

int fd = open ("/tmp/attachment.png", ...);
TnyMimePart *part = ...
if (fd != -1)
{
     TnyFsStream *stream = tny_fs_stream_new (fd);
     tny_mime_part_construct (part, TNY_STREAM (stream), "text/html", "base64");
}

self :

a TnyMimePart

stream :

a TnyStream

mime_type :

the MIME type like "text/plain"

transfer_encoding :

the Content-Transfer-Encoding

Returns :

0 on success or -1 on failure

Since 1.0 audience: application-developer


tny_mime_part_get_filename ()

const gchar*        tny_mime_part_get_filename          (TnyMimePart *self);

Get the filename of self if it's an attachment or NULL otherwise. The returned value should not be freed.

self :

a TnyMimePart

Returns :

(null-ok): the filename of the part as a read-only string or NULL

Since 1.0 audience: application-developer


tny_mime_part_get_content_id ()

const gchar*        tny_mime_part_get_content_id        (TnyMimePart *self);

Get the content-id of self. The returned value should not be freed.

self :

a TnyMimePart

Returns :

(null-ok): the content-id of the part as a read-only string or NULL

Since 1.0 audience: application-developer


tny_mime_part_get_description ()

const gchar*        tny_mime_part_get_description       (TnyMimePart *self);

Get the description of self. The returned value should not be freed.

self :

a TnyMimePart

Returns :

(null-ok): the description of the part as a read-only string or NULL

Since 1.0 audience: application-developer


tny_mime_part_get_content_location ()

const gchar*        tny_mime_part_get_content_location  (TnyMimePart *self);

Get the content location of self. The returned value should not be freed.

self :

a TnyMimePart

Returns :

(null-ok): the content-location of the part as a read-only string or NULL

Since 1.0 audience: application-developer


tny_mime_part_is_purged ()

gboolean            tny_mime_part_is_purged             (TnyMimePart *self);

Get if this attachment has been purged from cache.

self :

a TnyMimePart

Returns :

if purged TRUE, else FALSE

Since 1.0 audience: application-developer


tny_mime_part_set_content_location ()

void                tny_mime_part_set_content_location  (TnyMimePart *self,
                                                         const gchar *content_location);

Set the content location of self or NULL to unset it.

Note that not all TnyMimePart instances are writable. Only when creating a new message will the instance be guaranteed to be writable. This is a writing operation.

self :

a TnyMimePart

content_location :

(null-ok): the location or NULL

Since 1.0 audience: application-developer


tny_mime_part_set_description ()

void                tny_mime_part_set_description       (TnyMimePart *self,
                                                         const gchar *description);

Set the description of self or NULL to unset it.

Note that not all TnyMimePart instances are writable. Only when creating a new message will the instance be guaranteed to be writable. This is a writing operation.

self :

a TnyMimePart

description :

(null-ok): the description or NULL

Since 1.0 audience: application-developer


tny_mime_part_set_content_id ()

void                tny_mime_part_set_content_id        (TnyMimePart *self,
                                                         const gchar *content_id);

Set the content id of self or NULL to unset it.

Note that not all TnyMimePart instances are writable. Only when creating a new message will the instance be guaranteed to be writable. This is a writing operation.

self :

a TnyMimePart

content_id :

(null-ok): the content id or NULL

Since 1.0 audience: application-developer


tny_mime_part_set_filename ()

void                tny_mime_part_set_filename          (TnyMimePart *self,
                                                         const gchar *filename);

Set the filename of self or NULL to unset it.

Note that not all TnyMimePart instances are writable. Only when creating a new message will the instance be guaranteed to be writable. This is a writing operation.

self :

a TnyMimePart

filename :

(null-ok): the filename or NULL

Since 1.0 audience: application-developer


tny_mime_part_set_content_type ()

void                tny_mime_part_set_content_type      (TnyMimePart *self,
                                                         const gchar *contenttype);

Set the content type of self, Formatted as "type/subtype" or NULL to unset it (will default to text/plain then).

Note that not all TnyMimePart instances are writable. Only when creating a new message will the instance be guaranteed to be writable. This is a writing operation.

self :

a TnyMimePart

contenttype :

(null-ok): the content_type or NULL

Since 1.0 audience: application-developer


tny_mime_part_set_purged ()

void                tny_mime_part_set_purged            (TnyMimePart *self);

Set the message as purged in cache.

This is not a writing operation. Although it might change the content of a message for a user who's not connected with the server where self originates from.

Using the tny_msg_rewrite_cache() API on a message's instance will rewrite its purged mime parts with an empty body (saving storage space). The storage space is recovered after using tny_msg_rewrite_cache(). Only setting a mime part to purged might not completely remove it locally.

There is no guarantee about what happens with a purged mime part internally (it might get destroyed or become unuseable more early than the call to tny_msg_rewrite_cache).

self :

a TnyMimePart

Since 1.0 audience: application-developer


tny_mime_part_is_attachment ()

gboolean            tny_mime_part_is_attachment         (TnyMimePart *self);

Figures out whether or not a mime part is an attachment. An attachment is typically something with a original filename. Examples are attached files. An example that will return FALSE is a PGP signatures.

The algorithm that figures out whether self is indeed an attachment might not return its result according to your personal definition of what an attachment really is. There are many personal opinions on that.

For example the Content-Disposition and the availability of a filename header are used to determine this.

Example:

TnyMsg *message = ...
TnyList *parts = tny_simple_list_new ();
tny_mime_part_get_parts (TNY_MIME_PART (message), parts);
iter = tny_list_create_iterator (parts);
while (!tny_iterator_is_done (iter))
{
     TnyMimePart *part = TNY_MIME_PART (tny_iterator_get_current (iter));
     if (tny_mime_part_is_attachment (part))
     {
         g_print ("Found an attachment (%s)\n",
              tny_mime_part_get_filename (part));
     }
     g_object_unref (part);
     tny_iterator_next (iter);
}
g_object_unref (iter);
g_object_unref (parts);

self :

a TnyMimePart

Returns :

TRUE if it's an attachment, else FALSE

Since 1.0 audience: application-developer


tny_mime_part_decode_to_stream ()

gssize              tny_mime_part_decode_to_stream      (TnyMimePart *self,
                                                         TnyStream *stream,
                                                         GError **err);

Efficiently decode self to stream. This will not read the data of the part in a memory buffer. In stead it will read the part data while already writing it to the stream efficiently. Although there is no hard guarantee about the memory usage either (just that it's the most efficient way).

You will always get the decoded version of the data of self. When your part got received in BINARY from an IMAP server, then nothing will really happen with your data (it will be streamed to you the way it got received). If we received using FETCH BODY and the data is encoded in a known encoding (like BASE 64, QUOTED-PRINTED, UUENCODED, etc), the data will be decoded before delivered to stream. TEXT mime parts will also enjoy character set decoding.

In short will this API prepare the cookie and deliver it to your stream. It's therefore most likely the one that you want to use. If you are planning to nevertheless use the tny_mime_part_write_to_stream() API, then please know and understand what you are doing.

It's possible that this API receives information from the service. If you don't want to block on this, use tny_mime_part_decode_to_stream_async().

Example:

int fd = open ("/tmp/attachment.png", O_WRONLY|O_CREAT, S_IRUSR|S_IWUSR);
TnyMimePart *part = ...
if (fd != -1)
{
     TnyFsStream *stream = tny_fs_stream_new (fd);
     tny_mime_part_decode_to_stream (part, TNY_STREAM (stream));
     g_object_unref (G_OBJECT (stream));
}

self :

a TnyMimePart object

stream :

a TnyMsgStream stream

err :

Returns :

Returns -1 on error, or the number of bytes succesfully copied.

Since 1.0 audience: application-developer


tny_mime_part_get_parts ()

void                tny_mime_part_get_parts             (TnyMimePart *self,
                                                         TnyList *list);

Get a read-only list of child MIME parts in self.

Example:

TnyMsg *message = ...
TnyList *parts = tny_simple_list_new ();
tny_mime_part_get_parts (TNY_MIME_PART (message), parts);
iter = tny_list_create_iterator (parts);
while (!tny_iterator_is_done (iter))
{
     TnyMimePart *part = TNY_MIME_PART (tny_iterator_get_current (iter));
     g_object_unref (part);
     tny_iterator_next (iter);
}
g_object_unref (iter);
g_object_unref (parts);

self :

a TnyMimePart

list :

a TnyList to which the parts will be prepended

Since 1.0 audience: application-developer


tny_mime_part_add_part ()

gint                tny_mime_part_add_part              (TnyMimePart *self,
                                                         TnyMimePart *part);

Add a mime-part to self. It's not guaranteed that once the part is added to self, when getting a list of parts in self with tny_mime_part_get_parts(), that the same instance for the part will be the one you just added. Therefore it's recommended to unreference part after using this API.

Likewise it's recommended to alter part completely the way you want to alter it before adding it to self. Not after you added it.

Note that not all TnyMimePart instances are writable. Only when creating a new message will the instance be guaranteed to be writable. This is a writing operation.

self :

a TnyMimePart object

part :

a TnyMimePart to add to self

Returns :

The id of the added mime-part

Since 1.0 audience: application-developer


tny_mime_part_del_part ()

void                tny_mime_part_del_part              (TnyMimePart *self,
                                                         TnyMimePart *part);

Delete a mime-part from self. You should only attempt to remove parts that you got from self using the tny_mime_part_get_parts() API.

Note that not all TnyMimePart instances are writable. Only when creating a new message will the instance be guaranteed to be writable. This is a writing operation.

self :

a TnyMimePart

part :

a TnyMimePart to delete

Since 1.0 audience: application-developer


tny_mime_part_get_header_pairs ()

void                tny_mime_part_get_header_pairs      (TnyMimePart *self,
                                                         TnyList *list);

Get a read-only list of header pairs in self.

Example:

TnyMsg *message = ...
TnyList *pairs = tny_simple_list_new ();
tny_mime_part_get_header_pairs (TNY_MIME_PART (message), pairs);
iter = tny_list_create_iterator (pairs);
while (!tny_iterator_is_done (iter))
{
     TnyPair *pair = TNY_PAIR (tny_iterator_get_current (iter));
     g_print (%s: %s", tny_pair_get_name (pair), 
          tny_pair_get_value (pair));
     g_object_unref (pair);
     tny_iterator_next (iter);
}
g_object_unref (iter);
g_object_unref (pairs);

self :

a TnyMimePart

list :

a TnyList to which the header pairs will be prepended

Since 1.0 audience: application-developer


tny_mime_part_set_header_pair ()

void                tny_mime_part_set_header_pair       (TnyMimePart *self,
                                                         const gchar *name,
                                                         const gchar *value);

Set a header pair (name: value) or delete a header (use NULL as value).

Note that not all TnyMimePart instances are writable. Only when creating a new message will the instance be guaranteed to be writable. This is a writing operation.

Example:

TnyMsg *message = ...
tny_mime_part_set_header_pair (TNY_MIME_PART (message),
       "X-MS-Has-Attach", "yes");

self :

a TnyMimePart

name :

the name of the header

value :

(null-ok): the value of the header or NULL to unset

Since 1.0 audience: application-developer


tny_mime_part_decode_to_stream_async ()

void                tny_mime_part_decode_to_stream_async
                                                        (TnyMimePart *self,
                                                         TnyStream *stream,
                                                         TnyMimePartCallback callback,
                                                         TnyStatusCallback status_callback,
                                                         gpointer user_data);

This method does the same as tny_mime_part_decode_to_stream(). It just does everything asynchronous and callsback when finished.

self :

a TnyMimePart object

stream :

a TnyMsgStream stream

callback :

(null-ok): a TnyMimePartCallback or NULL

status_callback :

(null-ok): a TnyStatusCallback or NULL

user_data :

(null-ok): user data that will be passed to the callbacks

Since 1.0 audience: application-developer


tny_mime_part_get_transfer_encoding ()

const gchar*        tny_mime_part_get_transfer_encoding (TnyMimePart *self);

Get the transfer encoding of self or NULL if default transfer encoding 7bit.

self :

a TnyMimePart

Returns :

(null-ok): transfer encoding

Since 1.0 audience: application-developer


tny_mime_part_set_transfer_encoding ()

void                tny_mime_part_set_transfer_encoding (TnyMimePart *self,
                                                         const gchar *transfer_encoding);

Set the transfer encoding

self :

a TnyMimePart

transfer_encoding :

the Content-Transfer-Encoding

Since 1.0 audience: application-developer

See Also

TnyMsg, TnyCamelMimePart