![]() |
![]() |
![]() |
Reference Manual of the tinymail framework | ![]() |
---|---|---|---|---|
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); 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);
TnyMimePart is implemented by TnyCamelMimePart, TnyCamelBsMsg, TnyCamelMsg and TnyCamelBsMimePart.
A mime part is a part of a message. Like the body, an attachment or the PGP key of a message.
typedef struct _TnyMimePart TnyMimePart;
A part of a message, like the text of the message or like an attachment
free-function: g_object_unref
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;
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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