docs/reference/changes-2.0.sgml

   1 <refentry id="gmime-changes-2-0" revision="1 Feb 2003">
   2   <refmeta>
   3     <refentrytitle>Changes from 1.0 to 2.0</refentrytitle>
   4     <manvolnum>3</manvolnum>
   5     <refmiscinfo>Changes from 1.0 to 2.0</refmiscinfo>
   6   </refmeta>
   7   <refnamediv>
   8     <refname>Changes from 1.0 to 2.0</refname>
   9     <refpurpose>
  10 Incompatible changes made between version 1.0 and version 2.0
  11 </refpurpose>
  12   </refnamediv>
  13   <refsect1>
  14     <title>Incompatible changes from 1.0 to 2.0</title>
  15     <para>
  16 See also the PORTING document in the toplevel GMime source directory.
  17 </para>
  18     <para>
  19 The major change here is that I've dropped my own base object class
  20 and have replaced it with GObject from glib-2.0. This should be a
  21 pleasant change since you (the developer) will now be able to do many
  22 more things such as setting arbitrary data on all GMime objects. For
  23 additional information about GObject, please see the GObject Reference
  24 Manual at http://developer.gnome.org/doc/API/2.0/gobject/
  25 </para>
  26     <itemizedlist>
  27       <listitem>
  28         <para>
  29 The first thing you need to know is that any function returning a
  30 non-const pointer to any object /must/ be unref'd when you are done
  31 with it. Since all objects in GMime now subclass GObject, you may
  32 safely use <function>g_object_unref()</function>
  33 (<structname>GMimeStream</structname>'s may also be unref'd using
  34 <function>g_mime_stream_unref()</function>, but either way is fine).
  35
  36 Don't forget that
  37 <function>g_mime_part_get_content_object()</function> returns a
  38 ref-counted <structname>GMimeDataWrapper</structname> object now, and
  39 so you /must/ unref it when you have finished using it. You must also
  40 remember to unref any GMimeDataWrapper object that you /set/ on a
  41 GMimePart using <function>g_mime_part_set_content_object()</function>
  42 as the GMimePart will now ref the content object that you set on it.
  43 </para>
  44       </listitem>
  45       <listitem>
  46         <para><structname>GMimeMultipart</structname> is a new class which is to be
  47 used for all multipart MIME parts rather than GMimePart (as in
  48 1.0). There are also some subclasses of GMimeMultipart for other
  49 things.
  50 </para>
  51       </listitem>
  52       <listitem>
  53         <para><function>g_mime_part_[g,s]et_boundary()</function> have been removed
  54 (see above). You must now create a GMimeMultipart object and use
  55 <function>g_mime_multipart_[g,s]et_boundary()</function>.
  56 </para>
  57       </listitem>
  58       <listitem>
  59         <para><function>g_mime_part_add_subpart()</function> has been replaced with
  60 <function>g_mime_multipart_add_part()</function>.
  61 </para>
  62       </listitem>
  63       <listitem>
  64         <para><function>g_mime_part_foreach()</function> has been replaced with
  65 <function>g_mime_multipart_foreach()</function> and/or
  66 <function>g_mime_message_foreach_part()</function>.
  67 </para>
  68       </listitem>
  69       <listitem>
  70         <para><function>g_mime_part_get_subpart_from_content_id()</function> has
  71 been replaced with
  72 <function>g_mime_multipart_get_subpart_from_content_id()</function>.
  73 </para>
  74       </listitem>
  75       <listitem>
  76         <para>
  77 Another new class is <structname>GMimeMessagePart</structname> which
  78 is to be used for all MIME parts containing an rfc822 message. All 1.0
  79 GMimePart's representing message/rfc822 parts (as well as message/news
  80 parts?)  need to be migrated over to be GMimeMessagePart objects.
  81 </para>
  82       </listitem>
  83       <listitem>
  84         <para><structname>GMimeMessagePartial</structname> is another class meant
  85 for handling the message/partial MIME type. All 1.0 GMimePart's
  86 holding data of this type should be replaced with GMimeMessagePartial
  87 objects.
  88 </para>
  89       </listitem>
  90       <listitem>
  91         <para><function>g_mime_message_write_to_stream()</function> and
  92 <function>g_mime_part_write_to_stream()</function> functions have been
  93 consolidated into a virtual method. Replace calls to these functions
  94 with <function>g_mime_object_write_to_stream()</function>. Note: while
  95 <function>g_mime_part_write_to_stream()</function> and
  96 <function>g_mime_message_write_to_stream()</function> still exist, it
  97 is suggested you migrate to
  98 <function>g_mime_object_write_to_stream()</function>. Same goes for
  99 <function>g_mime_part_to_string()</function> and
 100 <function>g_mime_message_to_string()</function>.
 101 </para>
 102       </listitem>
 103       <listitem>
 104         <para><structname>GMimeMessage</structname>'s structure has changed a
 105 bit. You will not be able to do <literal>message-&gt;header</literal>,
 106 instead you want to do <literal>((GMimeObject *)
 107 message)-&gt;header</literal>.
 108 </para>
 109       </listitem>
 110       <listitem>
 111         <para><function>g_mime_message_set_message_id()</function> now takes a
 112 message_id argument without the encapsulating &lt; and &gt;'s (it now
 113 just takes the addr-spec portion of the msg-id).
 114 </para>
 115       </listitem>
 116       <listitem>
 117         <para><structname>GMimeFilterFrom</structname> has changed slightly, you
 118 will want to replace all calls to
 119 <function>g_mime_filter_from_new()</function> with
 120 <function>g_mime_filter_from_new
 121 (GMIME_FILTER_FROM_MODE_DEFAULT)</function>
 122 (<literal>GMIME_FILTER_FROM_MODE_DEFAULT</literal> is equivalent to (<type>int</type>) 0).
 123 </para>
 124       </listitem>
 125       <listitem>
 126         <para><structname>GMimeParser</structname> is a brand new class and
 127 <filename>gmime-parser.h</filename> has had a number of API additions.
 128 <function>g_mime_parser_construct_part()</function> and
 129 <function>g_mime_parser_construct_message()</function> still exist,
 130 however they no longer take a GMimeStream argument. Instead, they take
 131 a GMimeParser object.
 132 </para>
 133       </listitem>
 134     </itemizedlist>
 135   </refsect1>
 136 </refentry>