[Rt-commit] rt branch, 4.0/encode-and-decode-docs, created. rt-4.0.18-121-g0f93637

[Kevin Falcone]

The branch, 4.0/encode-and-decode-docs has been created
        at  0f93637d44310db621ccd0924dfae6814bee14e4 (commit)

- Log -----------------------------------------------------------------
commit bb61691247b980df105572ae2b8f12f3e3c4510b
Author: Kevin Falcone <falcone at bestpractical.com>
Date:   Mon Dec 16 16:09:42 2013 -0500

    Correct missing arguments in _EnclodeLOB docs
    
    6b12b8f added $Filename but didn't update the docs.
    This commit also added the special return condition without documenting
    it.

diff --git a/lib/RT/Record.pm b/lib/RT/Record.pm
index 66a6d65..0edc17f 100644
--- a/lib/RT/Record.pm
+++ b/lib/RT/Record.pm
@@ -729,9 +729,12 @@ sub _Accessible  {
 
 }
 
-=head2 _EncodeLOB BODY MIME_TYPE
+=head2 _EncodeLOB BODY MIME_TYPE FILENAME
 
-Takes a potentially large attachment. Returns (ContentEncoding, EncodedBody) based on system configuration and selected database
+Takes a potentially large attachment. Returns (ContentEncoding,
+EncodedBody, MimeType, Filename) based on system configuration and
+selected database.  Returns a special compatible error message if
+DropLongAttachments is enabled.
 
 =cut
 

commit 0f93637d44310db621ccd0924dfae6814bee14e4
Author: Kevin Falcone <falcone at bestpractical.com>
Date:   Mon Dec 16 16:11:20 2013 -0500

    Document _DecodeLOB.  Improve the _EncodeLOB docs
    
    In particular, call out their return and expected values in case you're
    trying to pass the return from _DecodeLOB back into _EncodeLOB, which
    RT::Migrate does.

diff --git a/lib/RT/Record.pm b/lib/RT/Record.pm
index 0edc17f..0bd25c4 100644
--- a/lib/RT/Record.pm
+++ b/lib/RT/Record.pm
@@ -736,6 +736,14 @@ EncodedBody, MimeType, Filename) based on system configuration and
 selected database.  Returns a special compatible error message if
 DropLongAttachments is enabled.
 
+Encodes your data as base64 or Quoted-Printable as needed based on your
+Databases's restrictions and the UTF-8ness of the data being passed in.  Since
+we are storing in columns marked UTF8, we must ensure that binary data is
+encoded on databases which are strict.
+
+This function expects to receive an octet string in order to properly
+evaluate and encode it.  It will return an octet string.
+
 =cut
 
 sub _EncodeLOB {
@@ -807,6 +815,27 @@ sub _EncodeLOB {
 
 }
 
+=head2 _DecodeLOB
+
+Unpacks data stored in the database, which may be base64 or QP encoded
+because of our need to store binary and badly encoded data in columns
+marked as UTF-8.  Databases such as PostgreSQL and Oracle care that you
+are feeding them invalid UTF-8 and will refuse the content.  This
+function handles unpacking the encoded data.
+
+It returns textual data as a UTF-8 string which has been processed by Encode's
+PERLQQ filter which will replace the invalid bytes with \x{HH} so you can see
+the invalid byte but won't run into problems treating the data as UTF-8 later.
+
+This is similar to how we filter all data coming in via the web UI in
+RT::Interface::Web::DecodeARGS. This filter should only end up being
+applied to old data from less UTF-8-safe versions of RT.
+
+Important Note - This function expects an octet string and returns a
+character string for non-binary data.
+
+=cut
+
 sub _DecodeLOB {
     my $self            = shift;
     my $ContentType     = shift || '';

-----------------------------------------------------------------------