path: root/fpcdocs/base64.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<fpdoc-descriptions>
<package name="fcl">

<!--
  ====================================================================
    base64
  ====================================================================
-->

<module name="base64">
<short>Unit implementing base64 encoding</short>
<descr>
<p>
<file>base64</file> implements base64 encoding (as used for instance in MIME
encoding) based on streams.
It implements 2 streams which encode or decode anything written or read from
it. The source or the destination of the encoded data is another stream.
2 classes are implemented for this: <link id="TBase64EncodingStream"/> for
encoding, and <link id="TBase64DecodingStream"/> for decoding.
</p>
<p>
The streams are designed as plug-in streams, which can be placed between
other streams, to provide base64 encoding and decoding on-the-fly...
</p>
</descr>

<!-- unresolved type reference Visibility: default -->
<element name="classes">
<short>Stream support</short>
</element>

<element name="TBase64DecodingMode">
<short>Decoding mode for stream</short>
<descr>
<p><var>TBase64DecodingMode</var> determines the decoding algorithm used by 
<link id="TBase64DecodingStream"/>. There are 2 modes:
</p>
<dl>
<dt>bdmStrict</dt><dd>Strict mode, which follows RFC3548 and rejects any characters 
outside of base64 alphabet. In this mode only up to two '=' characters are
accepted at the end. It requires the input to have a Size being a multiple
of 4, otherwise an <link id="EBase64DecodingException"/> exception is
raised.</dd>
<dt>bdmMime</dt><dd>MIME mode, which follows RFC2045 and ignores any characters 
outside of base64 alphabet. In this mode any '=' is seen as the end of
string, it handles apparently truncated input streams gracefully.
</dd>
</dl>                  
</descr>
</element>

<element name="TBase64DecodingMode.bdmMIME">
<short>MIME encoding</short>
</element>

<element name="TBase64DecodingMode.bdmStrict">
<short>Strict encoding</short>
</element>

<element name="TBase64DecodingStream.Mode">
<short>Decoding mode</short>
<descr>
<var>Mode</var> is the mode in which the stream is read. It can be set when
creating the stream or at any time afterwards.
</descr>
<seealso>
<link id="TBase64DecodingStream"/>
</seealso>
</element>

<element name="EBase64DecodingException">
<short>Exception raised on errors</short>
<descr>
<var>EBase64DecodeException</var> is raised when the stream contains errors
against the encoding format. Whether or not this exception is raised depends
on the mode in which the stream is decoded.
</descr>
</element>

<!--
  ********************************************************************
    #fcl.base64.TBase64EncodingStream
  ********************************************************************
-->

<!-- object Visibility: default -->
<element name="TBase64EncodingStream">
<short>Base64 encoding stream.</short>
<descr>
<p>
<var>TBase64EncodingStream</var> can be used to encode data using the base64
algorithm. At creation time, a destination stream is specified. Any data
written to the <var>TBase64EncodingStream</var> instance will be base64
encoded, and subsequently written to the destination stream.
</p>
<p>
The <var>TBase64EncodingStream</var> stream is a write-only stream.
Obviously it is also not seekable. It is meant to be included in  
a chain of streams.
</p>
<p>
By the nature of base64 encoding, when a buffer is written to the stream,
the output stream does not yet contain all output: input must be a multiple
of 3. In order to be sure that the output contains all encoded bytes, the
<link id="TBase64EncodingStream.Flush">Flush</link> method can be used. The
destructor will automatically call <var>Flush</var>, so all data is written
to the destination stream when the decodes is destroyed.  
</p>
</descr>
<seealso>
<link id="TBase64DecodingStream"/>
</seealso>
</element>

<!-- constructor Visibility: public -->
<element name="TBase64EncodingStream.Create">
<short>Create a new instance of the <var>TBase64EncodingStream</var> class.</short>
<descr>
<var>Create</var> instantiates a new <var>TBase64EncodingStream</var> class.
The <var>ASource</var> stream is stored and used to write the encoded
data to.
</descr>
<seealso>
<link id="TBase64EncodingStream.Destroy"/>
<link id="TBase64DecodingStream.Create"/>
</seealso>
</element>

<element name="TBase64EncodingStream.Create.ASource">
<short>Destination stream for encoded data</short>
</element>

<element name="TBase64DecodingStream.Create.AMode">
<short>Encoding mode to be used when encoding</short>
</element>
<element name="TBase64EncodingStream.Flush">
<short>Flush the remaining bytes to the output stream.</short>
<descr>
<var>Flush</var> writes the remaining bytes from the internal encoding
buffer to the output stream and pads the output with "=" signs. It returns
<var>True</var> if padding was necessary, and <var>False</var> if not.
</descr>
<seealso>
<link id="TBase64EncodingStream.Destroy"/>
</seealso>
</element>

<!-- destructor Visibility: public -->
<element name="TBase64EncodingStream.Destroy">
<short>Remove a <var>TBase64EncodingStream</var> instance from memory</short>
<descr>
<var>Destroy</var> flushes any remaining output and then removes the
<var>TBase64EncodingStream</var> instance from memory by calling the
inherited destructor.
</descr>
<errors>
An exception may be raised if the destination stream no longer exists or is
closed.
</errors>
<seealso>
<link id="TBase64EncodingStream.Create"/>
</seealso>
</element>

<!-- function Visibility: public -->
<element name="TBase64EncodingStream.Read">
<short>Read data from the stream</short>
<descr>
<var>Read</var> always raises an exception, because the encoding stream is
write-only.
</descr>
<seealso>
<link id="TBase64EncodingStream.Write"/>
<link id="TBase64EncodingStream.Seek"/>
<link id="TBase64DecodingStream.Read"/>
<link id="#rtl.classes.TStream.Read">TStream.Read</link>
</seealso>
</element>

<!-- function result Visibility: default -->
<element name="TBase64EncodingStream.Read.Result">
<short>Number of bytes actually read</short>
</element>

<!-- argument Visibility: default -->
<element name="TBase64EncodingStream.Read.Buffer">
<short>Buffer to receive read data</short>
</element>

<!-- argument Visibility: default -->
<element name="TBase64EncodingStream.Read.Count">
<short>Number of bytes to read</short>
</element>

<!-- function Visibility: public -->
<element name="TBase64EncodingStream.Write">
<short>Write data to the stream.</short>
<descr>
<var>Write</var> encodes <var>Count</var> bytes from <var>Buffer</var> using
the Base64 mechanism, and then writes the encoded data to the destination
stream. It returns the number of bytes from <var>Buffer</var> that were
actually written. Note that this is not the number of bytes written to the
destination stream: the base64 mechanism writes more bytes to the
destination stream.
</descr>
<errors>
If there is an error writing to the destination stream, an error may occur.
</errors>
<seealso>
<link id="TBase64EncodingStream.Seek"/>
<link id="TBase64EncodingStream.Read"/>
<link id="TBase64DecodingStream.Write"/>
<link id="#rtl.classes.TStream.Write">TStream.Write</link>
</seealso>
</element>

<!-- function result Visibility: default -->
<element name="TBase64EncodingStream.Write.Result">
<short>Number of bytes from buffer actually used</short>
</element>

<!-- argument Visibility: default -->
<element name="TBase64EncodingStream.Write.Buffer">
<short>Buffer with data to write</short>
</element>

<!-- argument Visibility: default -->
<element name="TBase64EncodingStream.Write.Count">
<short>Number of bytes from buffer to write</short>
</element>

<!-- function Visibility: public -->
<element name="TBase64EncodingStream.Seek">
<short>Position the stream</short>
<descr>
<var>Seek</var> always raises an <var>EStreamError</var> 
exception unless the arguments it received it don't change 
the current file pointer position. The encryption stream is 
not seekable.
</descr>
<errors>
An <var>EStreamError</var> error is raised.
</errors>
<seealso>
<link id="TBase64EncodingStream.Read"/>
<link id="TBase64EncodingStream.Write"/>
<link id="#rtl.classes.TStream.Seek">TStream.Seek</link>
</seealso>
</element>

<!-- function result Visibility: default -->
<element name="TBase64EncodingStream.Seek.Result">
<short>New position in the stream</short>
</element>

<!-- argument Visibility: default -->
<element name="TBase64EncodingStream.Seek.Offset">
<short>Offset from origin</short>
</element>

<!-- argument Visibility: default -->
<element name="TBase64EncodingStream.Seek.Origin">
<short>Origin for the seek operation.</short>
</element>

<!--
  ********************************************************************
    #fcl.base64.TBase64DecodingStream
  ********************************************************************
-->

<!-- object Visibility: default -->
<element name="TBase64DecodingStream">
<short>Base64 Decoding stream </short>
<descr>
<p>
<var>TBase64DecodingStream</var> can be used to read data from a stream (the
source stream) that contains Base64 encoded data. The data is read and 
decoded on-the-fly.
</p>
<p>
The decoding stream is read-only, and provides a limited forward-seek capability.
</p>
</descr>
<seealso>
<link id="TBase64EncodingStream"/>
</seealso>
</element>

<!-- constructor Visibility: public -->
<element name="TBase64DecodingStream.Create">
<short>Create a new instance of the <var>TBase64DecodingStream</var> class</short>
<descr>
<p>
<var>Create</var> creates a new instance of the
<var>TBase64DecodingStream</var> class. It stores the source stream
<var>ASource</var> for reading the data from.
</p>
<p>
The optional <var>AMode</var> parameter determines the mode in which the
decoding will be done. If omitted, <var>bdmMIME</var> is used.
</p>
</descr>
<seealso>
<link id="TBase64EncodingStream.Create"/>
<link id="TBase64DecodingMode"/>
</seealso>
</element>

<!-- argument Visibility: default -->
<element name="TBase64DecodingStream.Create.ASource">
<short>Source stream from which to read encoded data</short>
</element>

<!-- procedure Visibility: public -->
<element name="TBase64DecodingStream.Reset">
<short>Reset the stream</short>
<descr>
<var>Reset</var> resets the data as if it was again on the start of the
decoding stream.
</descr>
<errors>
None.
</errors>
<seealso>
<link id="TBase64DecodingStream.EOF"/>
<link id="TBase64DecodingStream.Read"/>
</seealso>
</element>

<!-- function Visibility: public -->
<element name="TBase64DecodingStream.Read">
<short>Read and decrypt data from the source stream</short>
<descr>
<p>
<var>Read</var> reads encrypted data from the source stream
and stores this data in <var>Buffer</var>. At most <var>Count</var> bytes
will be stored in the buffer, but more bytes will be read from 
the source stream: the encoding algorithm multiplies the number of bytes.
</p>
<p>
The function returns the number of bytes stored in the buffer.
</p>
</descr>
<errors>
If an error occurs during the read from the source stream, an exception may
occur.
</errors>
<seealso>
<link id="TBase64DecodingStream.Write"/>
<link id="TBase64DecodingStream.Seek"/>
<link id="#rtl.classes.TStream.Read">TStream.Read</link>
</seealso>
</element>

<!-- function result Visibility: default -->
<element name="TBase64DecodingStream.Read.Result">
<short>Number of bytes stored in buffer.</short>
</element>

<!-- argument Visibility: default -->
<element name="TBase64DecodingStream.Read.Buffer">
<short>Buffer to store data in.</short>
</element>

<!-- argument Visibility: default -->
<element name="TBase64DecodingStream.Read.Count">
<short>Maxmimum number of bytes to store in buffer.</short>
</element>

<!-- function Visibility: public -->
<element name="TBase64DecodingStream.Write">
<short>Write data to the stream</short>
<descr>
<p>
<var>Write</var> always raises an <var>EStreamError</var> exception, because
the decoding stream is read-only. To write to an encrypted stream, use a
<link id="TBase64EncodingStream"/> instance.
</p>
</descr>
<errors>
</errors>
<seealso>
<link id="TBase64DecodingStream.Read"/>
<link id="TBase64DecodingStream.Seek"/>
<link id="TBase64EncodingStream.Write"/>
<link id="#rtl.classes.TStream.Write">TStream.Write</link>
</seealso>
</element>

<!-- function result Visibility: default -->
<element name="TBase64DecodingStream.Write.Result">
<short>Number of bytes written</short>
</element>

<!-- argument Visibility: default -->
<element name="TBase64DecodingStream.Write.Buffer">
<short>Buffer with data to write to the stream</short>
</element>

<!-- argument Visibility: default -->
<element name="TBase64DecodingStream.Write.Count">
<short>Number of bytes to write</short>
</element>

<!-- function Visibility: public -->
<element name="TBase64DecodingStream.Seek">
<short>Set stream position.</short>
<descr>
<p>
<var>Seek</var> sets the position of the stream. In the 
<var>TBase64DecodingStream</var> class, the <var>seek</var>
operation is forward only, it does not support backward seeks.
The forward seek is emulated by reading and discarding data 
till the desired position is reached.
</p>
<p>
For an explanation of the parameters, see 
<link id="#rtl.classes.TStream.Seek">TStream.Seek</link>
</p>
</descr>
<errors>
In case of an unsupported operation, an <var>EStreamError</var> exception is
raised.
</errors>
<seealso>
<link id="TBase64DecodingStream.Read"/>
<link id="TBase64DecodingStream.Write"/>
<link id="TBase64EncodingStream.Seek"/>
<link id="#rtl.classes.TStream.Seek">TStream.Seek</link>
</seealso>
</element>

<!-- function result Visibility: default -->
<element name="TBase64DecodingStream.Seek.Result">
<short>New absolute position in the stream.</short>
</element>

<!-- argument Visibility: default -->
<element name="TBase64DecodingStream.Seek.Offset">
<short>Offset, relative to origin.</short>
</element>

<!-- argument Visibility: default -->
<element name="TBase64DecodingStream.Seek.Origin">
<short>Origin of the seek operation.</short>
</element>

<!-- property Visibility: public -->
<element name="TBase64DecodingStream.EOF">
<short></short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<element name="DecodeStringBase64">
<short>Decodes a Base64 encoded string and returns the decoded data as a
string.</short>
<descr>
<var>DecodeStringBase64</var> decodes the string <var>s</var> (containing Base
64 encoded data) returns the decoded data as a string. It uses a <link
id="TBase64DecodingStream"/> to do this. The <var>Strict</var> parameter is
passed on to the constructor as <var>bdmStrict</var> or <var>bdmMIME</var>
</descr> 
<seealso>
<link id="DecodeStringBase64"/>    
<link id="TBase64DecodingStream"/>
</seealso>
</element>

<element name="DecodeStringBase64.strict">
<short>Choose between strict base64 decoding or MIME decoding </short>
</element>

<element name="EncodeStringBase64">
<short>Encode a string with  Base64 encoding and return the result as a
string.</short>
<descr>
<var>EncodeStringBase64</var> encodes the string <var>s</var> using Base 64
encoding and returns the result. It uses a <link
id="TBase64EncodingStream"/> to do this.
</descr>
<seealso>
<link id="DecodeStringBase64"/>
<link id="TBase64EncodingStream"/>
</seealso>
</element>

<!-- function result Visibility: default -->
<element name="TBase64EncodingStream.Flush.Result">
<short>True if additional bytes were written.</short>
</element>

<!-- function result Visibility: default -->
<element name="EncodeStringBase64.Result">
<short>The Base64 encoded version of <var>S</var></short>
</element>

<!-- argument Visibility: default -->
<element name="EncodeStringBase64.s">
<short>The string to encode with base64</short>
</element>

<!-- function result Visibility: default -->
<element name="DecodeStringBase64.Result">
<short>The base64 decoded version of <var>S</var></short>
</element>

<!-- argument Visibility: default -->
<element name="DecodeStringBase64.s">
<short>The base64 encoded string to decode</short>
</element>

</module> <!-- base64 -->

</package>
</fpdoc-descriptions>