rjmime.pas

Delphi开发webservice的一套例子

{ Copyright Ralf Junker <[e-mail]> 2000-2001
  http://www.zeitungsjunge.de/delphi/ }

unit rjMime;
{
Unit:           rjMime
Version:        1.50
Last Modified:  1. February 2001
Author:         Ralf Junker <[e-mail]>
Internet:       http://www.zeitungsjunge.de/delphi/

Description:    Ligtening fast Mime (Base64) Encoding and Decoding routines.
                More detailed descriptions follow the declarations of the
                procedures and functions below.

Legal:          This software is provided 'as-is', without any express or
                implied warranty. In no event will the author be held liable
                for any  damages arising from the use of this software.

                Permission is granted to anyone to use this software for any
                purpose, including commercial applications, and to alter it
                and redistribute it freely, subject to the following
                restrictions:

                1. The origin of this software must not be misrepresented,
                    you must not claim that you wrote the original software.
                    If you use this software in a product, an acknowledgment
                    in the product documentation would be appreciated but is
                    not required.

                2. Altered source versions must be plainly marked as such, and
                   must not be misrepresented as being the original software.

                3. This notice may not be removed or altered from any source
                   distribution.

History:

Version 1.50
------------
01.02.2000     Added support for line breaks (CRLF) during Mime encoding
               as required by RFC 1521. Since inserting line breaks is the
               default in RFC 1521, I changed the standard encoding functions
               to encode WITH line breaks. This may require changes to your
               code: Encoding without inserting line breaks is still provided
               by the ...NoCRLF procedures. There are now two sets of Mime
               encoding procedures and functions:

               Encoding WITH line breaks       | Encoding WITHOUT line breaks
               ("strict" RFC 1521)             | ("loose" RFC 1521)
               --------------------------------|--------------------------------
               MimeEncode                      | MimeEncodeNoCRLF
               MimeEncodeString                | MimeEncodeStringNoCRLF
               MimeEncodeStream                | MimeEncodeStreamNoCRLF
               MimeEncodedSize                 | MimeEncodedSizeNoCRLF

               If you migrate from rjMime 1.31 to rjMime 1.50, you might need to
               adjust your code depending on the required results. If you
               don't want to change any behaviour as compared to earlier
               versions of rjMime, simply add "NoCRLF" to all calls to Mime
               encoding functions.

               Please note that there is no MimeDecodeNoCRLF equivalent since
               the decoding routines skip line breaks and white space anyway.

               New DecodeHttpBasicAuthentication procedure according to
               RFC 1945. See description below for deatils.

               Version 1.50 also fixes a critical bug in MimeDecode
               (added missing @). This bug did not affect any of the other
               functions.

Version 1.31
------------
20.11.2000      Defined the OutputBuffer parameters as untyped "out"
                in the core encoding / decoding routines. This does not
                affect much but consistency in clarity.

Version 1.30
------------
17.11.2000      Changed the interface part to the core encoding and decoding
                routines from Pointer to Untyped. This way they no longer
                have to check if the pointers are not nil.

                Replaced all Integer types with Cardinal types
                where the sign was not needed (which was in all cases).

                Thanks to Robert Marqwart <[e-mail]>
                for pointing these issues out.

Version 1.20
------------
20.06.2000      Bugfix for MimeEncodeStream: Wrong BUFFER_SIZE resulted in
                additional bytes stuffed inbetween the OutBuffer.

                Changed the order of the variables in the MimeEncode interface
                (moved InputBytesCount from last to 2nd, just after InputBuffer).
                Sorry for the inconvenience, but this way it is more consistent
                with MimeDecode. Now MimeEncode has the following variable order:

                procedure MimeEncode (
                  const InputBuffer: Pointer;
                  const InputBytesCount: Integer;
                  const OutputBuffer: Pointer);

                MimeDecode: Interface chage to make it a function: It now returns
                the number of bytes written to the output buffer not as a var
                but as the result of a function. This way coding is made
                simpler since not OutputCount variable needs to be defined.

                Introduced two new functions mostly for internal use:

                * MimeDecodePartial: This is necessary to decode large
                  blocks of data in multiple parts. On initialization,
                  call MimeDecodePartial with ByteBuffer := 0 and
                  ByteBufferSpace := 4. Then repeatedly call it again
                  with new data loaded into the buffer. At the end of all data,
                * MimeDecodePartialEnd writes the remaining bytes from ByteBuffer
                  to the outputbuffer (see MimeDecodeStream for an example).

                MimeDecodePartial_ are necessary to decode inconsitent data
                (with linebreaks, tabs, whitespace) in multiple parts
                like in MimeDecodeStream.

Version 1.10
------------
19.04.2000      Fixed a small bug in MimeEncode which sometimes screwed up
                the very first bytes of the encoded output.

                Added the following wrapper functions:
                * MimeEncodeString & MimeDecodeString
                * MimeEncodeStream & MimeDecodeStream

Version 1.01
------------
09.04.2000      Fixed a bug in MIME_DECODE_TABLE which caused wrong results
                decoding binary files.

Version 1.00
------------
17.01.2000      Initial Public Release

Copyright (c) 2000 Ralf Junker
}

interface

uses
 Classes;

function MimeEncodeString (const s: AnsiString): AnsiString;
{ MimeEncodeString takes a string, encodes it, and returns the result as a string.
  To decode the result string, use MimeDecodeString. }

function MimeEncodeStringNoCRLF (const s: AnsiString): AnsiString;
{ MimeEncodeStringNoCRLF is just like MimeEncodeString, but does NOT insert line breaks. }

function MimeDecodeString (const s: AnsiString): AnsiString;
{ MimeDecodeString takes a a string, decodes it, and returns the result as a string.
Use MimeDecodeString to decode a string previously encoded with MimeEncodeString. }

procedure MimeEncodeStream (const InputStream: TStream; const OutputStream: TStream);
{ MimeEncodeStream encodes InputStream WITH inserting line breaks.
  Encoding starts at the InputStream's current position and continues until the end.
  Decoded output is written to OutputStream, again starting at the current position.
  When done, the function will not reset either stream's positions,
  but leave InputStream at the last read position (i.e. the end) and
  OutputStream at the last write position (which can, but most not be the end).
  To encode the entire InputStream from beginning to end, make sure
  that its offset is positioned at the beginning of the stream. You can
  force this by issuing

       InputStream.Seek (0, soFromBeginning);

  before calling this function. }

procedure MimeEncodeStreamNoCRLF (const InputStream: TStream; const OutputStream: TStream);
{ MimeEncodeStreamNoCRLF is just like MimeEncodeStream, but does NOT insert line breaks. }

procedure MimeDecodeStream (const InputStream: TStream; const OutputStream: TStream);
{ MimeDecodeStream decodes InputStream starting at the current position
  up to the end and writes the result to OutputStream, again starting at
  the current position. When done, it will not reset either stream's positions,
  but leave InputStream at the last read position (i.e. the end) and
  OutputStream at the last write position (which can, but most not be the end).
  To decode the entire InputStream from beginning to end, make sure
  that its offset is positioned at the beginning of the stream. You can
  force this by issuing Seek (0, soFromBeginning) before calling this function. }

function MimeEncodedSize (const i: Cardinal): Cardinal;
{ Calculates the output size of i MimeEncoded bytes, i.e. the memory required
  for all decoded data plus the line breaks. Use for MimeEncode only. }

function MimeEncodedSizeNoCRLF (const i: Cardinal): Cardinal;
{ Calculates the output size of i MimeEncodedNoCRLF bytes, i.e. the memory
  required for all decoded data. Use for MimeEncodedNoCRLF only. }

function MimeDecodedSize (const i: Cardinal): Cardinal;
{ Calculates the maximum output size of i MimeDecoded bytes.
  You may use it for MimeDecode to calculate the maximum amount of memory
  required for decoding in one single pass. }

procedure DecodeHttpBasicAuthentication (const BasicCredentials: AnsiString; out UserId, PassWord: AnsiString);
{ Decodes the UserID and Password for HTTP Basic Authentication. Pass the
  contents of the Authorization Header as BasicCredentials and DecodeHttpBasicAuthentication
  will return the unencoded UserID and Password. If either of the two can not be
  decoded or found, they will result in an empty string (''). This procedure is
  inspired by Shiv.

  The following quote from "Request for Comments (RFC) 1945: Hypertext Transfer
  Protocol -- HTTP/1.0" has the details:

  11.1  Basic Authentication Scheme

   The "basic" authentication scheme is based on the model that the user
   agent must authenticate itself with a user-ID and a password for each
   realm. The realm value should be considered an opaque string which
   can only be compared for equality with other realms on that server.
   The server will authorize the request only if it can validate the
   user-ID and password for the protection space of the Request-URI.
   There are no optional authentication parameters.

   Upon receipt of an unauthorized request for a URI within the
   protection space, the server should respond with a challenge like the
   following:

       WWW-Authenticate: Basic realm="WallyWorld"

   where "WallyWorld" is the string assigned by the server to identify
   the protection space of the Request-URI.

   To receive authorization, the client sends the user-ID and password,
   separated by a single colon (":") character, within a base64 [5]
   encoded string in the credentials.

       basic-credentials = "Basic" SP basic-cookie

       basic-cookie      = <base64 [5] encoding of userid-password,
                            except not limited to 76 char/line>

       userid-password   = [ token ] ":" *TEXT

   If the user agent wishes to send the user-ID "Aladdin" and password
   "open sesame", it would use the following header field:

       Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

   The basic authentication scheme is a non-secure method of filtering
   unauthorized access to resources on an HTTP server. It is based on
   the assumption that the connection between the client and the server
   can be regarded as a trusted carrier. As this is not generally true
   on an open network, the basic authentication scheme should be used
   accordingly. In spite of this, clients should implement the scheme in
   order to communicate with servers that use it. }

procedure MimeEncode (const InputBuffer; const InputByteCount: Cardinal; out OutputBuffer);
{ MimeEncode is the primary Mime encoding routine.
  Line breaks will be inserted after each full line.

  CAUTTION: OutputBuffer must have enough memory allocated to take all encoded output.
  MimeEncodedSize (InputBytesCount) calculates this amount in bytes. MimeEncode will
  then fill the entire OutputBuffer, so there is no OutputBytesCount result for
  this procedure. Preallocating all memory at once (as required by MimeEncode)
  avoids the time-cosuming process of reallocation.

  If not all data fits into memory at once, you can NOT use MimeEncode multiple times.
  Instead, use a combintion of MimeEncodeFullLines and MimeEncodeNoCRLF. }