home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 31 / CDASC_31_1996_juillet_aout.iso / internet / base64_2.zip / BASE64.DOC next >
Text File  |  1996-06-09  |  9KB  |  217 lines
  1. Documentation for the Base 64 Encoder:
  2. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  3.  
  4. Contents:
  5. ---------
  6.  
  7. 1. General information regarding the programs
  8. 2. About ENCODE64.EXE   
  9. 3. About DECODE64.EXE    
  10. 4. Technical information regarding BASE 64 encoding
  11. 5. Disclaimer, distribution, etc.
  12. 6. Revision Notes
  13.  
  14. 1. General:
  15. ~~~~~~~~~~~
  16.   These DOS programs have built-in error checking to make sure the files
  17. are processed correctly. However, if there are unexplained errors while
  18. processing, the program will give a "Runtime Error" message. Check in
  19. this documentation for information regarding possible errors. Most errors
  20. will likely be caused by the DECODE64 program, because of text-processing
  21. problems. If all else fails, refer to the section on DECODE64 and see
  22. how the program works! If you think a certain problem may be a bug in 
  23. the program, please e-mail me. My e-mail address is at the bottom of 
  24. this document.
  25.   NOTE: DECODE64 will only decode files with a CR/LF at the end of every
  26. line. It will not decode a file with only LF. This program was made for
  27. DOS, so if you need to decode a file with only LF (ASCII 10) at the end
  28. of every line, it will need to be converted to DOS CR/LF first (having
  29. an ASCII 13 & ASCII 10 at the end of every line).
  30.   IMPORTANT: Internet mail programs will probably not recognize encoded 
  31. files over e-mail when encoded using ENCODE64. This is because information 
  32. is added to the header and body of sent e-mails when files are included 
  33. with them. It is impossible to mimic this with these programs. Whoever 
  34. receives a Base64 encoded file encoded using ENCODE64 may need a utility 
  35. similar to DECODE64 to be able to decode it.
  36.  
  37.  
  38. 2. About ENCODE64.EXE:
  39. ~~~~~~~~~~~~~~~~~~~~~~
  40.   This program takes any file (binary or otherwise) and converts it 
  41. into a format transmittable over the Internet. (See technical information 
  42. below.) The command line for this program is:
  43.  
  44. ENCODE64 <filename>
  45.  
  46. Where <filename> is any file.
  47. Example:
  48.  
  49. C:\>ENCODE64 PROGRAM.ZIP
  50.  
  51. After executing this, ENCODE64 will create a file called "PROGRAM.64" in
  52. the current directory. If a file with that name was already found, it will
  53. say so and will not overwrite it (it must be moved or deleted before
  54. ENCODE64 will create the file, just to make sure that no data is lost).
  55.  
  56.  
  57. 3. About DECODE64.EXE:
  58. ~~~~~~~~~~~~~~~~~~~~~~
  59.   Command line for this program is:
  60.  
  61.   DECODE64 <filename>
  62.  
  63.   Where <filename> is any BASE-64 encoded file.
  64.  
  65.   This program takes any BASE-64 encoded file and converts it back into
  66. whatever it was before it was encoded. Since some formats of BASE-64
  67. encoding may have different line lengths, etc, these steps are followed
  68. by the program:
  69.  
  70. 1. Search <filename> for the string 'name="' (no single quotes). When
  71.    it finds the string, it will take the output filename from between
  72.    the quotes and check to see if there is already a file of the same
  73.    name in the current directory. If there is, it will prompt you if  
  74.    you want the file overwritten. If not, it will quit. If the file
  75.    was not found, it will create it.
  76.    
  77.    See revision notes at the bottom of this document for another, 
  78.    optional, file name format (under version 2, revision #3).
  79.  
  80. 2. Make sure the end of the header is found. If the 'name="' was
  81.    found before the end of the header, it will read lines until a blank
  82.    line is found. This means that the end of the header has been
  83.    reached. There *MUST* be a space between the header and the encoded 
  84.    data. The header is composed of the 'name="' and other data.
  85.  
  86. 3. Read one line. The length of this line will tell how long the BASE-64
  87.    lines are formatted for. If any subsequent line is smaller than the
  88.    first line, the end of the file has been reached.
  89.  
  90. 4. If any encoded data line's length is not evenly divisible by 4, 
  91.    the program will abandon processing.
  92.  
  93. 5. If an end of file was reached without a single line being smaller
  94.    in length than 4, or with a "-" character being reached, then the
  95.    program will give a "Possible unexpected end of file" message.
  96.  
  97.    See revision note at the end of the document under version 2,
  98.    revision #5 regarding the dash symbol at the end of encoded data.
  99.  
  100. The ideal format for the BASE 64 file would be one created by the 
  101. ENCODE64 program, or in this format:
  102.  
  103. --==========================
  104. name="test.zip"
  105. <header stuff>
  106. <header stuff>
  107.  
  108. AAAABBBBCCCCDDDDEEEEFFFFGGGGHHHHIIIIJJJJKKKKLLLLMMMMNNNNOOOOPPPP
  109. QQ==
  110. --==========================
  111.  
  112. Note the blank line between the header and the encoded data, and the
  113. "-" character immediately following the encoded data. This will make
  114. sure the file is created properly.
  115. If there is no blank space between the header and the encoded data,
  116. the program will keep reading until it reaches a blank line, causing
  117. errors.
  118. If the file ends immediately after the encoded data, DECODE64 will give
  119. a false error message ("Possible unexpected end of file"), but will
  120. nevertheless create the file correctly.
  121.  
  122. About the "Bad Character" error: This error is caused by a character
  123. other than the ones accepted by Base64 being in the encoded data. This
  124. error will not halt the program, but the outputted file may have bad
  125. data in it. If the end of the encoded data was not properly found,
  126. this error could also be caused by DECODE64 attempting to decode 
  127. regular text which may appear after the encoded file segment.
  128.  
  129. Most other errors may be caused by DECODE64 not being able to properly
  130. find the end of the encoded data. For best results, edit the encoded
  131. file so it matches the template shown above.
  132.  
  133.  
  134. 4. Technical Information:
  135. ~~~~~~~~~~~~~~~~~~~~~~~~~
  136.   BASE-64 (MIME encoding) converts regular 8-bit encoded files into 
  137. a form which can be readily transmittable via Internet e-mail. It
  138. is impossible to send any 8-bit file over e-mail without this or a
  139. similar process done (such as XX-encoding, UU-encoding, etc).
  140.   The way it encodes is by taking three (8-bit) bytes from the file, 
  141. and converting those 24 bits into 4 sets of 6-bit numbers. Since a 
  142. 6-bit number can never go over 63, it outputs to the BASE-64 file
  143. with these characters:
  144.  
  145. Character:ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/
  146. Value:    0..............................................................63
  147.  
  148.   Since some files will not have sizes evenly divisible by three, padding
  149. is added with the "=" character at the end of the BASE64 file.
  150.  
  151.   BASE-64 is superior to UU encoding & XX encoding in that it does not 
  152. use any characters that may *not* be readily transmittable via Internet.
  153. Also, for ever 45 encoded characters of XX & UU, there is one extra
  154. character as a line checksum (seen as the first character of every
  155. line). Data transmission has become so reliable that checksums are
  156. no longer necessary.
  157.   For more information on MIME encoding, look up RFC 1521.
  158.  
  159.  
  160. 5. Disclaimer, Distribution, Etc.
  161. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  162.   DISCLAIMER: I'm not responsible if this messes up your computer in
  163. any way. But how could it? :) 
  164.  
  165.   These programs are freeware, and if you like it, e-mail me. If 
  166. there are any persistant problems with either of the programs which you 
  167. think are bugs, e-mail me. These programs can be distributed freely
  168. as long as ALL files are kept in the same archive. If these programs
  169. are put on a CD-ROM, FTP site, WWW, etc, I'd appreciate knowing it!
  170. Also, none of the programs can be sold.
  171.   Thanks to the few people who have e-mailed me and convinced me to 
  172. bring out future versions.
  173.  
  174.  
  175.   These programs were written by Fire Frog in April, 1996.
  176.  
  177.   My e-mail address (as of now) is:
  178.  
  179.   frog@star2.opsys.com
  180.  
  181.   BBS I can be contacted on (as "Fire Frog"):
  182.  
  183.   MANx Cat BBS -- 305-245-0113
  184.   (Based in the Miami area)
  185.  
  186.   Sysop: Major Airwaves
  187.  
  188.  
  189. 6. Revision Updates
  190. ~~~~~~~~~~~~~~~~~~~
  191.  These notes tell of added features, etc, added to the programs. The
  192.  programs themselves don't tell their own version number, but if this
  193.  document was included with your archive, then you have the updated
  194.  version.
  195.  
  196.  Sorry, no fancy version numbers. Can only make filename eight 
  197.  characters! :)
  198.  
  199. #1 -- Basic version.
  200.  
  201. #2 -- 1. First update. 
  202.       
  203.       2. Slightly faster disk access added. 
  204.          
  205.       3. Support for using the 'name = <filename>' string instead of 
  206.           'name="<filename>"' string. (Used by some encoders.)
  207.          
  208.       4. User can now optionally overwrite files: either the ".64"
  209.           files created by ENCODE64 or the files created by DECODE64.
  210.    
  211.       5. Support for some encoders, which, instead of having dashes
  212.           "-" immediately following encoded data, will have a blank
  213.           line and then the dashes. If it finds a blank line anywhere  
  214.           in encoded data, it will stop processing.
  215. ________________________________________________________________________
  216. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  217.