PORTING

   1 It is my intention to make migrating code using one version of GMime
   2 to another as easy as I can and so for the most part, I will try not
   3 to break API/ABI compatability between versions, however this isn't
   4 always easy to do.
   5
   6 This document is intended to help developers port their application(s)
   7 from one version of GMime to another. For each new major release, I
   8 will attempt to list the main things to watch out for when migrating
   9 to the new release from the prior version.
  10
  11
  12 Porting from GMime 2.4 to GMime 2.6
  13 -----------------------------------
  14
  15 After releasing GMime 2.4, it was discovered that
  16 g_mime_stream_length() still returned ssize_t which, on 32bit systems,
  17 meant that the function was useless if the actual stream was larger
  18 than 2GB (which could happen if GMime was built with large file
  19 support).
  20
  21 As I fixed this, I also found some API inconsistencies which I felt I
  22 might as well fix up since I had to break API/ABI compatibility with
  23 2.4 anyway.
  24
  25 Most notable in GMime 2.6 is the lack of GMimeSession which has been
  26 dropped in favor of a much simpler callback
  27 mechanism. GMimeCipherContexts constructors now take a
  28 password_request callback function rather than forcing you to subclass
  29 GMimeSession to get this functionality.
  30
  31 Other API changes include:
  32
  33 - GMimeBestEncoding has been renamed to GMimeEncodingConstraint
  34
  35 - GMimeSignatureValidity has been dropped in favor of
  36   GMimeSignatureList which is simply a collection of signatures.
  37
  38 - GMimeSigner has been replaced by GMimeSignature and GMimeCertificate
  39   which added a number of new fields and accessors making it much more
  40   complete.
  41
  42 - GMimeCipherContext has been renamed to GMimeCryptoContext and the
  43   method names for this class have also been renamed in a similar
  44   fashion.
  45
  46 - g_mime_crypto_context_encrypt() now takes a digest algorithm
  47   argument which is used when the 'sign' argument is TRUE.
  48
  49 - g_mime_multipart_encrypted_encrypt() also now takes a digest
  50   algorithm argument which it passes along to
  51   g_mime_crypto_context_encrypt().
  52
  53 - g_mime_crypto_context_decrypt() now returns a GMimeDecryptResult
  54   which contains a list of signatures (if signed), a list of
  55   recipients that the stream had been encrypted to, and also the
  56   cipher and digest algorithms used.
  57
  58 - g_mime_multipart_encrypted_decrypt() no longer caches the decrypted
  59   part and also now takes a GMimeSignatureList** output argument
  60   which it sets in place of having to call
  61   g_mime_multipart_encrypted_get_signature_validity() afterward.
  62
  63 For convenience, GMime 2.6 source packages include a shell-script to
  64 aid in porting applications using GMime 2.4 to the 2.6 API. You can
  65 find this script under the tools/ directory, named
  66 `gmime-port-2-4-to-2-6.sh'.
  67
  68
  69 Porting from GMime 2.2 to GMime 2.4
  70 -----------------------------------
  71
  72 GMime 2.4 has had a number of API changes since GMime 2.2. To start,
  73 ALL public APIs that used to use off_t in GMime 2.2 now use gint64 so
  74 that the API and ABI do not change based on whether or not large file
  75 support is enabled.
  76
  77 In addition, all of the functions marked as deprecated in 2.0 and 2.2
  78 were removed (usually they had equivalent functionality in a parent
  79 class).
  80
  81 Many functions have also been renamed for better clarity and/or
  82 consistency. For convenience, GMime 2.4 source packages include a
  83 shell-script to aid in porting applications using GMime 2.2 (should
  84 work for most GMime 2.0 applications as well) to the 2.4 API. You can
  85 find this script under the tools/ directory, named
  86 `gmime-port-2-2-to-2-4.sh'.
  87
  88 This script won't fix everything, but it should help quite a bit.
  89
  90 Beyond that, a few methods have changed in other ways:
  91
  92 - g_mime_cipher_context_sign() still returns int, but if the value
  93   isn't -1 (failure), then it will represent a GMimeCipherHash that it
  94   used for signing. This is useful, for example, when the requested
  95   hash was GMIME_CIPHER_HASH_DEFAULT.
  96
  97 - g_mime_cipher_context_decrypt() now returns a GMimeSignatureValidty
  98   on success and NULL on failure. This is needed in case the encrypted
  99   stream was also signed.
 100
 101 - g_mime_multipart_encrypted_encrypt() now takes a boolean 'sign'
 102   argument to allow the caller to request encrypting and signing in a
 103   single pass.
 104
 105 Several structs have also been rewritten to subclass GObject like
 106 GMimeContentType and GMimeContentDisposition as well as
 107 InternetAddress and InternetAddressList.
 108
 109 Not only have InternetAddress and InternetAddressList been ported to
 110 GObject, but they have also undergone other design
 111 changes. InternetAddress is now a base class for
 112 InternetAddressMailbox and InternetAddressGroup, meaning that
 113 InternetAddress no longer contains a union for group/addr fields.
 114
 115 All functions that return a GObject have been changed to not add a ref
 116 to the object returned, meaning that it is no longer necessary to call
 117 g_object_unref() on MIME parts returned from functions like
 118 g_mime_message_get_mime_part() or g_mime_multipart_get_part(). This
 119 was done to be more consistent with the Gtk+ API.
 120
 121
 122 Porting from GMime 2.0 to GMime 2.2
 123 -----------------------------------
 124
 125 Note: GMime 2.2 is both API and ABI compatible with GMime 2.0 meaning
 126 that any program written for GMime 2.0 will compile fine with GMime
 127 2.2 and any program linked against GMime 2.0's libraries will also
 128 work with GMime 2.2's libraries.
 129
 130 Most of the changes made between 2.0 and 2.2 were internal but there
 131 are a few API changes you should be aware of (as these interfaces will
 132 be deprecated in some future version, probably 3.0).
 133
 134 - g_mime_utils_8bit_header_decode() has been split into 2
 135 functions. We now have g_mime_utils_header_decode_text() and
 136 g_mime_utils_header_decode_phrase(). header_decode_text() no longer
 137 requires encoded-words to be rfc822 atoms. header_decode_phrase() is
 138 still strict in that encoded-words MUST be valid rfc822 atoms.
 139
 140 - g_mime_utils_8bit_header_encode() has been renamed to
 141 g_mime_utils_header_encode_text() to be more clear as to what type of
 142 header this is supposed to encode. If you haven't guessed, this
 143 function is for encoding rfc822 'text' headers (such as Subject).
 144
 145 - g_mime_utils_8bit_header_encode_phrase() has been renamed to
 146 g_mime_utils_header_encode_phrase() mostly for consistancy with the
 147 previous 2 changes.
 148
 149 - g_mime_charset_name() has been renamed to
 150 g_mime_charset_iconv_name() for clarity.
 151
 152 - g_mime_charset_locale_name() has been renamed to
 153 g_mime_locale_charset(). Hmmm, was this a bad rename?
 154
 155 - g_mime_cipher_context_verify() no longer returns a
 156 GMimeCipherValidity, instead it returns a GMimeSignatureValidity which
 157 is far more useful. Never fear, you may still use the
 158 GMimeCipherValidity APIs for the time being - they work fine given a
 159 GMimeSignatureValidity structure.
 160
 161 - g_mime_multipart_signed_verify() also now returns a
 162 GMimeSignatureValidity structure rather than a GMimeCipherValidity
 163 structure. See changes to g_mime_cipher_context_verify() for details.
 164
 165
 166 Porting from GMime 1.0 to GMime 2.0
 167 -----------------------------------
 168
 169 The major change here is that I've dropped my own base object class
 170 and have replaced it with GObject from glib-2.0. This should be a
 171 pleasant change since you (the developer) will now be able to do many
 172 more things such as setting arbitrary data on all GMime objects. For
 173 additional information about GObject, please see the GObject Reference
 174 Manual at http://developer.gnome.org/doc/API/2.0/gobject/
 175
 176 - The first thing you need to know is that any function returning a
 177 non-const pointer to any object /must/ be unref'd when you are done
 178 with it. Since all objects in GMime now subclass GObject, you may
 179 safely use g_object_unref() (GMimeStream's may also be unref'd
 180 using g_mime_stream_unref(), but either way is fine).
 181
 182 Don't forget that g_mime_part_get_content_object() returns a
 183 ref-counted GMimeDataWrapper object now, and so you /must/ unref it
 184 when you have finished using it. You must also remember to unref any
 185 GMimeDataWrapper object that you /set/ on a GMimePart using
 186 g_mime_part_set_content_object() as the GMimePart will now ref the
 187 content object that you set on it.
 188
 189 - GMimeMultipart is a new class which is to be used for all multipart
 190 MIME parts rather than GMimePart (as in 1.0). There are also some
 191 subclasses of GMimeMultipart for other things.
 192
 193 - g_mime_part_[g,s]et_boundary() have been removed (see above). You
 194 must now create a GMimeMultipart object and use
 195 g_mime_multipart_[g,s]et_boundary().
 196
 197 - g_mime_part_add_subpart() has been replaced with
 198 g_mime_multipart_add_part().
 199
 200 - g_mime_part_foreach() has been replaced with
 201 g_mime_multipart_foreach() and/or g_mime_message_foreach_part().
 202
 203 - g_mime_part_get_subpart_from_content_id() has been replaced with
 204 g_mime_multipart_get_subpart_from_content_id().
 205
 206 - Another new class is GMimeMessagePart which is to be used for all
 207 MIME parts containing an rfc822 message. All 1.0 GMimePart's
 208 representing message/rfc822 parts (as well as message/news parts?)
 209 need to be migrated over to be GMimeMessagePart objects.
 210
 211 - GMimeMessagePartial is another class meant for handling the
 212 message/partial MIME type. All 1.0 GMimePart's holding data of this
 213 type should be replaced with GMimeMessagePartial objects.
 214
 215 - g_mime_message_write_to_stream() and g_mime_part_write_to_stream()
 216 functions have been consolidated into a virtual method. Replace calls
 217 to these functions with g_mime_object_write_to_stream(). Note: while
 218 g_mime_part_write_to_stream() and g_mime_message_write_to_stream()
 219 still exist, it is suggested you migrate to
 220 g_mime_object_write_to_stream(). Same goes for g_mime_part_to_string()
 221 and g_mime_message_to_string().
 222
 223 - GMimeMessage's structure has changed a bit. You will not be able to
 224 do message->header, instead you want to do ((GMimeObject *)
 225 message)->header.
 226
 227 - g_mime_message_set_message_id() now takes a message_id argument
 228 without the encapsulating <>'s (it now just takes the addr-spec
 229 portion of the msg-id).
 230
 231 - GMimeFilterFrom has changed slightly, you will want to replace all
 232 calls to g_mime_filter_from_new () with g_mime_filter_from_new
 233 (GMIME_FILTER_FROM_MODE_DEFAULT) (GMIME_FILTER_FROM_MODE_DEFAULT is
 234 equivalent to (int) 0).
 235
 236 - GMimeParser has had a number of API additions, but
 237 g_mime_parser_construct_part() and g_mime_parser_construct_message()
 238 still exist, however they no longer take a GMimeStream
 239 argument. Instead, they take a GMimeParser object.
 240
 241
 242
 243 If you find more trouble spots when porting your code from one version
 244 of GMime to a later version, please feel free to send me additional
 245 notes to add to this porting document.
 246
 247                                         -- fejj@gnome.org