/help/Mime.dtx

  1@@EJclMimeError
  2<GROUP MIME>
  3Summary:
  4  Base class for exceptions raised in response to MIME encoding/decoding errors.
  5Description:
  6  The EJclMimeError class is the exception class that is raised when an error occurs
  7  within one of MIME-routines.
  8Donator:
  9  Ralf Junker
 10--------------------------------------------------------------------------------
 11@@MimeEncodeString
 12<GROUP MIME>
 13Summary:
 14  MIME-Encodes a string.
 15Description:
 16  MimeEncodeString encodes the supplied string with a MIME64 encoding algorithm.
 17Parameters:
 18  s - String to be encoded.
 19Result:
 20  MIME encoded string.
 21See also:
 22  MimeDecodeString
 23  MimeEncodeStream
 24  MimeEncode
 25  MimeEncodedSize
 26Donator:
 27  Ralf Junker
 28--------------------------------------------------------------------------------
 29@@MimeDecodeString
 30<GROUP MIME>
 31Summary:
 32  MIME-Decodes a string.
 33Description:
 34  MimeDecodeString decodes the supplied MIME64-encoded string.
 35Parameters:
 36  s - MIME64-encoded string to be decoded.
 37Result:
 38  Decoded string.
 39See also:
 40  MimeEncodeString
 41  MimeDecodeStream
 42  MimeDecode
 43  MimeDecodedSize
 44Donator:
 45  Ralf Junker
 46--------------------------------------------------------------------------------
 47@@MimeEncodeStream
 48<GROUP MIME>
 49Summary:
 50  MIME-Encodes a stream.
 51Description:
 52  MimeEncodeStream encodes InputStream starting at the current position up to the
 53  end and writes the result to OutputStream, again starting at the current
 54  position. When done, it will not reset either stream's positions, but leave
 55  InputStream at the last read position (i.e. the end) and OutputStream at the
 56  last write position (which can, but is not always the end).
 57  To encode the entire InputStream from beginning to end, make sure that its
 58  offset is positioned at the beginning of the stream. You can force this by
 59  issuing Seek (0, soFromBeginning) before calling this function.
 60Parameters:
 61  InputStream - Input stream to be encoded.
 62  OutputStream - Output stream.
 63See also:
 64  MimeDecodeStream
 65  MimeEncodeString
 66  MimeEncode
 67  MimeEncodedSize
 68Donator:
 69  Ralf Junker
 70--------------------------------------------------------------------------------
 71@@MimeDecodeStream
 72<GROUP MIME>
 73Summary:
 74  Decodes a MIME-encoded stream.
 75Description:
 76  MimeDecodeStream decodes InputStream starting at the current position up to the
 77  end and writes the result to OutputStream, again starting at the current
 78  position. When done, it will not reset either stream's positions, but leave
 79  InputStream at the last read position (i.e. the end) and OutputStream at the
 80  last write position (which can, but is not always the end).
 81  To decode the entire InputStream from beginning to end, make sure that its
 82  offset is positioned at the beginning of the stream. You can force this by
 83  issuing Seek (0, soFromBeginning) before calling this function.
 84Parameters:
 85  InputStream - Input stream to be decoded.
 86  OutputStream - Output stream.
 87See also:
 88  MimeEncodeStream
 89  MimeDecodeString
 90  MimeDecode
 91  MimeDecodedSize
 92Donator:
 93  Ralf Junker
 94--------------------------------------------------------------------------------
 95@@MimeEncodedSize
 96<GROUP MIME>
 97Summary:
 98  Calculates the output size for encoding.
 99Description:
100  MimeEncodedSize calculates the output size of I MimeEncoded bytes. Use for MimeEncode only.
101Parameters:
102  I - Number of bytes to encode.
103Result:
104  Number of bytes needed for encoding.
105See also:
106  MimeEncode
107  MimeDecodedSize
108Donator:
109  Ralf Junker
110--------------------------------------------------------------------------------
111@@MimeDecodedSize
112<GROUP MIME>
113Summary:
114  Calculates the output size for decoding.
115Description:
116  MimeDecodedSize calculates the maximum output size of I MimeDecoded bytes. You
117  may use it for MimeDecode to calculate the maximum amount of memory required for
118  decoding in one single pass.
119Parameters:
120  I - Number of bytes to decode.
121Result:
122  Maximum number of bytes needed for decoding.
123See also:
124  MimeDecode
125  MimeEncodedSize
126Donator:
127  Ralf Junker
128--------------------------------------------------------------------------------
129@@MimeEncode
130<GROUP MIME>
131Summary:
132  The primary Mime encoding routine.
133Description:
134  MimeEncode is the primary MIME-encoding routine and is used by MimeEncodeString
135  and MimeEncodeStream but can also be used directly.
136  CAUTION: OutputBuffer must have enough memory allocated to take all encoded
137  output. MimeEncodedSize(InputBytesCount) calculates this amount in bytes.
138  MimeEncode will then fill the entire OutputBuffer, so there is no
139  OutputBytesCount result for this procedure. Preallocating all memory at once (as
140  required by MimeEncode) avoids the time-consuming process of reallocation.
141Parameters:
142  InputBuffer - Points to the memory block to encode.
143  InputByteCount - Number of bytes to encode.
144  OutputBuffer - Points to the output buffer.
145Notes:
146  If not all data fits into memory at once, you can use MimeEncode multiple times, but you must be very careful about the size of the InputBuffer. It should be set to a number that is a multiple of 3.
147See also:
148  MimeEncodedSize
149  MimeDecode
150Donator:
151  Ralf Junker
152--------------------------------------------------------------------------------
153@@MimeDecode
154<GROUP MIME>
155Summary:
156  The primary Mime decoding routine.
157Description:
158  MimeDecode is the primary MIME-decoding routine and can also be used directly.
159  CAUTION: OutputBuffer must have enough memory allocated to take all
160  output. MimeDecodedSize(InputBytesCount) calculates this amount in bytes. There is no
161  guarantee that all output will be filled after decoding. MimeDecode therefore
162  returns the actual number of bytes written to OutputBuffer. Preallocating all
163  memory at once (as is required by MimeDecode) avoids the time-consuming process
164  of reallocation. After calling MimeDecode, simply cut the allocated memory down
165  to OutputBytesCount, i.e. SetLength(OutString, OutputBytesCount).
166Parameters:
167  InputBuffer - Points to the memory block to encode.
168  InputBytesCount - Number of bytes to encode.
169  OutputBuffer - Points to the output buffer.
170Result:
171  Number of bytes actually written to the OutputBuffer.
172See also:
173  MimeDecodedSize
174  MimeEncode
175Donator:
176  Ralf Junker
177--------------------------------------------------------------------------------
178@@MimeDecodePartial
179<GROUP MIME>
180Summary:
181  MIME decode a chunk of data in a multi-phase decoding routine.
182Description:
183  MIME decodes a chunk of data in a mutli-phase decoding routine. It is used
184  within MimeDecodeString, MimeDecodeStream, and MimeDecode, but can also be used
185  directly.
186Parameters:
187  InputBuffer - Buffer to decode.
188  InputBytesCount - Number of bytes to decode.
189  OutputBuffer - Points to the output buffer.
190  ByteBuffer - Bytes of buffer from previous call.
191  ByteBufferSpace - Number of bytes to read before ByteBuffer is full.
192Result:
193  Number of bytes actually written to the OutputBuffer.
194Notes:
195  On first call ByteBuffer should be 0 (zero) and ByteBufferSpace should be 4. The values returned in these parameters should be used in the next call to MimeDecodePartial or MimeDecodePartialEnd.
196See also:
197  MimeDecodePartialEnd
198Donator:
199  Ralf Junker
200--------------------------------------------------------------------------------
201@@MimeDecodePartialEnd
202<GROUP MIME>
203Summary:
204  MIME decode the last chunk of data in a multi-phase decoding routine.
205Description:
206  MIME decodes the last chunk of data in a mutli-phase decoding routine. It is
207  used within MimeDecodeString, MimeDecodeStream, and MimeDecode, but can also be
208  used directly.
209Parameters:
210  OutputBuffer - Points to the output buffer.
211  ByteBuffer - Bytes of buffer from previous call.
212  ByteBufferSpace - Number of bytes to read before ByteBuffer is full
213Result:
214  Number of bytes actually written to the OutputBuffer.
215Notes:
216  ByteBuffer and ByteBufferSpace are the values returned in the last call to MimeDecodePartial.
217See also:
218  MimeDecodePartial
219Donator:
220  Ralf Junker