home *** CD-ROM | disk | FTP | other *** search
/ The AGA Experience 2 / agavol2.iso / software / utilities / misc / crmv1.9t / developer / doc / crm_lib.doc
Text File  |  1978-06-29  |  20KB  |  499 lines
  1. TABLE OF CONTENTS
  2.  
  3. CrM.library/cmAllocCrunchStructA
  4. CrM.library/cmCheckCrunched
  5. CrM.library/cmCrunchData
  6. CrM.library/cmCryptData
  7. CrM.library/cmDecrunch
  8. CrM.library/cmFreeCrunchStruct
  9. CrM.library/cmProcessCrunchStructA
  10. CrM.library/cmProcessPW
  11.  
  12. CrM.library/cmAllocCrunchStructA             CrM.library/cmAllocCrunchStructA
  13.  
  14.     NAME
  15.     cmAllocCrunchStructA -- Allocate a crunchstruct. (V4)
  16.  
  17.     SYNOPSIS
  18.     crunchstruct = cmAllocCrunchStructA (taglist);
  19.     D0             -78                   A0
  20.  
  21.     struct cmCrunchStruct *cmAllocCrunchStructA
  22.         (struct TagItem *taglist);
  23.  
  24.     crunchstruct = cmAllocCrunchStruct (firsttag, ...);
  25.  
  26.     struct cmCrunchStruct *cmAllocCrunchStruct (Tag, ...);
  27.  
  28.     FUNCTION
  29.     Allocates a cmCrunchStruct structure needed by cmCrunchData().  See
  30.     the docs to cmProcessCrunchStructA() for more details.  This is a
  31.     last minute add on to the library, so don't get confused.  You should
  32.     use cmAllocCrunchStructA() and cmFreeCrunchStruct() instead of
  33.     cmProcessCrunchStructA() because they are easier to use, but I
  34.     implemented these functions too late for the example sources, so they
  35.     still use cmProcessCrunchStructA().
  36.  
  37.     INPUTS
  38.     taglist - pointer to an array of tags
  39.  
  40.     TAGS
  41.     See cmProcessCrunchStructA() for the tags.
  42.  
  43.     RESULT
  44.     crunchstruct - pointer to a cmCrunchStruct structure or Null for
  45.                    failure.
  46.  
  47.     BUGS
  48.     Well, it's not really a bug, but you should not change the cmcr_Algo
  49.     field yourself.  This means that you should free your old
  50.     crunchstruct and allocate a new one also to swtich a minor thing like
  51.     password encryption on or off.  This is for future compatibility.  It
  52.     is safe to change the flags in the cmcr_Algo field between two calls
  53.     to cmCrunchData() but it's not a nice way.  _NEVER_ change the
  54.     crunchalgorithm this way!
  55.  
  56.     SEE ALSO
  57.     cmCrunchData(), cmFreeCrunchStruct(), cmProcessCrunchStructA()
  58.  
  59. CrM.library/cmCheckCrunched                       CrM.library/cmCheckCrunched
  60.  
  61.     NAME
  62.     cmCheckCrunched -- Check whether file is crunched or not.
  63.  
  64.     SYNOPSIS
  65.     type = cmCheckCrunched (dataheader);
  66.     D0     -42              A0
  67.  
  68.     ULONG cmCheckCrunched (struct DataHeader *);
  69.  
  70.     FUNCTION
  71.     Checks the dh_ID field of the DataHeader to determine which crunch
  72.     algorithm was used.  See CrM_lib.h for the type.  Currently the
  73.     following are supported (lower 4 Bits of D0):
  74.         cm_Normal  - File was crunched with CrM-Normal algorithm
  75.         cm_LZH     - File was crunched with LZ-Huffman algorithm
  76.     additionally these Flags may be set:
  77.         cmF_Sample - additionally the Sample-Mode was used
  78.         cmF_PW     - additionally the Password Encryption was enabled
  79.  
  80.     This Function check only the dh_ID field of the DataHeader, you don't
  81.     need to initialize the rest of it.
  82.  
  83.     You need not to call this funtion when you want to decrunch some data
  84.     but it is very useful as you don't need to load the whole file.
  85.  
  86.     INPUTS
  87.     DataHeader - pointer to a DataHeader structure
  88.  
  89.     RESULT
  90.     type - type of cruncher used to compress the data, or NULL if the
  91.            data is not crunched or if the header is not recognized.
  92.  
  93.     SEE ALSO
  94.     cmDecrunch(), cmProcessCrunchStructA()
  95.  
  96. CrM.library/cmCrunchData                             CrM.library/cmCrunchData
  97.  
  98.     NAME
  99.     cmCrunchData() -- Crunch some piece of data. (V4)
  100.  
  101.     SYNOPSIS
  102.     newlen = cmCrunchData (crunchstruct);
  103.     D0       -72           A0
  104.  
  105.     ULONG cmCrunchData (struct cmCrunchStruct *);
  106.  
  107.     FUNCTION
  108.     Crunch some piece of data.  All details have to be initialized in the
  109.     cmCrunchStruct structure allocated with cmProcessCrunchStructA().
  110.  
  111.     The fields and their meanings:
  112.       cmcr_Src         - (APTR)
  113.                          Points to the data to be crunched.  Has to be
  114.                          initialized before calling cmCrunchData().
  115.       cmcr_SrcLen      - (ULONG)
  116.                          This is the lenght of the source data region.
  117.                          Has to be initialized before calling
  118.                          cmCrunchData().
  119.       cmcr_Dest        - (APTR)
  120.                          Points to the buffer for the crunched data.  You
  121.                          may use the Source memory region as Destination
  122.                          (only one buffer needed), then you have to set
  123.                          the cmF_Overlay flag.
  124.       cmcr_DestLen     - (ULONG)
  125.                          This is the lenght of the Destination memory
  126.                          region.  If the crunched data doesn't fit into
  127.                          the buffer cmCrunchData() will return with an
  128.                          error:  newlen = 0, cmcr_QuitFlag = "n"
  129.       cmcr_DataHdr     - (struct DataHeader *)
  130.                          Pointer to a 14 bytes long array.  The
  131.                          dataheader for the file will be generated there.
  132.                          Set this value to NULL if you don't want a
  133.                          dataheader.
  134.       cmcr_DisplayHook - (struct Hook *)
  135.                          The crunch algorithm will call this hook from
  136.                          time to time.  You can vary the between two
  137.                          calls with the cmcr_DisplayStep variable.  Set
  138.                          cmcr_DisplayHook to NULL if you don't need a
  139.                          hook.  Parameters are as follows:
  140.                            A0 - (struct Hook *) your hook
  141.                            A2 - (struct cmCrunchStruct *) your
  142.                                 crunchstructure
  143.                            A1 - (struct cmCurrentStats *) structure
  144.                                 telling you how far the crunching process
  145.                                 has advanced.  The structure looks like
  146.                                 this:
  147.                                   cmcu_ToGo - number of bytes remaining
  148.                                               to be processed.
  149.                                   cmcu_Len  - len of currently crunched
  150.                                               data.  In the LZ-Huffman
  151.                                               mode this value will be to
  152.                                               big especially with short
  153.                                               files.
  154.                          You have to return TRUE or FALSE.  TRUE means
  155.                          that you want to continue crunching, FALSE tells
  156.                          the crunch algorithm that you want to abort.
  157.       cmcr_DisplayStep - (UWORD)
  158.                          Sets the number of bytes processed between two
  159.                          calls of the hook.  Default is $400 = 1024.
  160.     The following fields are *READONLY*:
  161.       cmcr_Offset      - (UWORD)
  162.                          Offset you want to crunch the data with.  Bigger
  163.                          offsets produce better results but also longer
  164.                          crunch times.  Maximum is $7ffe.  Set this value
  165.                          with cmProcessCrunchData().
  166.       cmcr_HuffSize    - (UWORD)
  167.                          Sets the size of the huffman buffer in KBytes
  168.                          (only valid if you use the cm_LZH algorith).
  169.                          Default is 16.
  170.       cmcr_Algo        - (UWORD)
  171.                          Determines which algorithm you want to use.
  172.                          Values may be (stored in lower 4 bits):
  173.                            cm_Normal    - File was crunched with
  174.                                           CrM-Normal algorithm.
  175.                            cm_LZH       - File was crunched with
  176.                                           LZ-Huffman algorithm.
  177.                          in addition these Flags may be set (def=FALSE):
  178.                            cmF_Sample   - additionally the Sample-Mode
  179.                                           was used.
  180.                            cmF_PW       - additionally the Password
  181.                                           Encryption was enabled.
  182.                            cmF_Overlay  - Source and Dest memory region
  183.                                           overlap.
  184.                                           (cmcr_Dest <= cmcr_Src) has to
  185.                                           be true in this case.
  186.                            cmF_LEDFlash - Power LED flashes while
  187.                                           crunching.
  188.       cmcr_MaxOffset   - (ULONG)
  189.                          Offset for which the buffers have been
  190.                          allocated.
  191.       cmcr_RealOffset  - (ULONG)
  192.                          Offset which is used for current data.  This is
  193.                          either cmcr_MaxOffset or cmcr_SrcLen.
  194.       cmcr_MinSecDist  - (ULONG)
  195.                          Minimum Security Distance:  Distance that has to
  196.                          be kept between source and destination buffer
  197.                          (when they overlap) to decrunch savely.
  198.       cmcr_CrunchedLen - (ULONG)
  199.                          Size of crunched data. NULL if crunching failed.
  200.       cmcr_QuitFlag    - (CHAR)
  201.                          Reason for returning:
  202.                          NULL - no error occurred.
  203.                          "a"  - crunching was aborted (display hook
  204.                                 returned FALSE).
  205.                          "n"  - not able to crunch: Destination buffer is
  206.                                 to small.
  207.       cmcr_LEDFlashFlag - (BOOLEAN)
  208.                          Has the same function as the cmF_LEDFlash flag
  209.                          but this field is used by the crunchalgorithm.
  210.                          You may change this field _ONLY_ from within the
  211.                          display hook (while crunching).
  212.  
  213.     NOTE: cmcr_Src and cmcr_Dest have to be even addresses.
  214.  
  215.     INPUTS
  216.     crunchstruct - pointer to a struct cmCrunchStruct allocated with
  217.                    cmProcessCrunchStructA().
  218.                      
  219.     RESULT
  220.     newlen - Lenght of the crunched data or NULL if crunching failed.
  221.  
  222.     SEE ALSO
  223.     cmProcessCrunchStructA()
  224.         
  225. CrM.library/cmCryptData                               CrM.library/cmCryptData
  226.  
  227.     NAME
  228.     cmCryptData() -- (De-)crypt some piece of data with a password. (V4)
  229.  
  230.     SYNOPSIS
  231.     action = cmCryptData (datahdr, data, password, action);
  232.     D0       -60          A0       A1    A2        D0
  233.  
  234.     ULONG cmCryptData (struct DataHeader *, APTR, CHAR *, ULONG);
  235.  
  236.     FUNCTION
  237.     Crypts or decrypts the data provided.  In either case you have to
  238.     provide the data and the dataheader.
  239.  
  240.     Action determines how this function behaves.  If action is Null the
  241.     data will switch its state, i.e.  from encrypted to normal or vice
  242.     versa.  cm_EnCrypt will lead to some crypted piece of data, when the
  243.     data is already crypted nothing is done.  cm_DeCrypt behaves in the
  244.     same way:  when the data isn't crypted at all nothing is done.
  245.  
  246.     Password lets you specify a password yourself.  If the password is
  247.     Null, an empty string or the wrong one for decryption and reqtools
  248.     requester will appear.  When decrypting the internal list is scanned
  249.     first for the right password before displaying a requester.  The
  250.     maximum size for passwords is 80 chars plus the terminating zero.
  251.  
  252.     In case of decryption each password you enter will be added to the
  253.     internal list of passwords.  This list is used only for decryption
  254.     and is scanned at every attempt to decrypt something for the right
  255.     password.  So you only have to type your password once.  When the
  256.     entered password is already present in the list another requetser
  257.     appears allowing you to remove this or all passwords from the list.
  258.  
  259.     To encrypt some data you have to enter you password twice.  This is
  260.     to prevent mistakes as you cannot read what you type.  If you provide
  261.     an empty string as password cmCryptData() will put the string the
  262.     user entered there.  Thus password has to point to an area which is
  263.     at least 84 bytes long.
  264.  
  265.     The return values reflect what was done.  Null indicates that nothing
  266.     was done due to an error (not packed at all) or due to the data
  267.     already being in the wanted state.  cm_EnCrypt/cm_Decrypt means that
  268.     the data was en-/decrypted.
  269.  
  270.     INPUTS
  271.     datahdr  - pointer to a dataheader structure.
  272.     data     - pointer to your crunched (and crypted) data.
  273.     password - pointer to a (empty) string or Null.
  274.     action   - cm_EnCrypt, cm_Decrypt or Null to switch the state.
  275.  
  276.     RESULT
  277.     action - action that was performed (cm_EnCrypt, cm_DeCrypt or Null).
  278.  
  279.     SEE ALSO
  280.     cmCrunchData(), cmDecrunch()
  281.  
  282. CrM.library/cmDecrunch                                 CrM.library/cmDecrunch
  283.  
  284.     NAME
  285.     cmDecrunch() -- Decrunch some piece of data.
  286.  
  287.     SYNOPSIS
  288.     newdest = cmDecrunch (source, dest, datahdr);
  289.     D0        -48         A0      A1    A2
  290.  
  291.     APTR cmDecrunch (APTR, APTR, struct DataHeder *);
  292.  
  293.     FUNCTION
  294.     This function decrunches some piece of data to any location you want.
  295.     It checks whether the data is crunched or not and will choose the
  296.     right decruncher.  If the data was packed using the Sample-Mode it is
  297.     automatically decrypted.  If you used password encryption the library
  298.     internal list is scanned first for a matching password.  In case of
  299.     failure a reqtools requester is displayed to get the right password.
  300.     If you cancel it decrunching fails.
  301.  
  302.     The first 14 bytes of a data file are the data header you need to
  303.     decrunch the data, so there is no need to create a special one.
  304.  
  305.     After decrunching newdest points to the start of the decrunched data.
  306.     Normally this equals dest, but when dh_MinSecDist in the dataheader
  307.     is not zero there is some additional memory needed for decrunching.
  308.     In this case newdest points dest + dh_MinSecDist.  This is also the
  309.     reason why you have to provide a dh_OriginalLen + dh_MinSecDist large
  310.     destination area for save decrunching.
  311.  
  312.     source and dest areas may overlap where source has to be smaller or
  313.     equal to dest.  This is not the case when source and dest areas do
  314.     not overlap.  The crunched data may not be longer than the decrunched
  315.     data.  This is not very often the case (and silly, too) but be
  316.     careful!
  317.  
  318.     INPUTS
  319.     source  - pointer to crunched data (has to be even!)
  320.     dest    - pointer to buffer for decrunched (original) data
  321.     datahdr - pointer to a DataHeader structure
  322.  
  323.     RESULT
  324.     newdest - pointer to beginning of decrunched data of Null for failure
  325.               NOTE: newdest may be different from dest when the
  326.                     dh_MinSecDist field is not zero.
  327.  
  328.     SEE ALSO
  329.     cmCheckCrunched(), cmCrunchData()
  330.  
  331. CrM.library/cmFreeCrunchStruct                 CrM.library/cmFreeCrunchStruct
  332.  
  333.     NAME
  334.     cmFreeCrunchStruct -- Free a crunchstruct. (V4)
  335.  
  336.     SYNOPSIS
  337.     cmFreeCrunchStruct (crunchstruct);
  338.     -84                 A0
  339.  
  340.     VOID cmFreeCrunchStruct (struct cmCrunchStruct *);
  341.  
  342.     FUNCTION
  343.     Frees a cmCrunchStruct structure needed by cmCrunchData().  See the
  344.     docs to cmProcessCrunchStructA() for more details.  This is a last
  345.     minute add on to the library, so don't get confused.  You should use
  346.     cmAllocCrunchStructA() and cmFreeCrunchStruct() instead of
  347.     cmProcessCrunchStructA() because they are easier to use, but I
  348.     implemented these functions too late for the example sources, so they
  349.     still use cmProcessCrunchStructA().
  350.  
  351.     INPUTS
  352.     crunchstruct - pointer to a cmCrunchStruct struture
  353.  
  354.     RESULT
  355.     no result.
  356.  
  357.     SEE ALSO
  358.     cmCrunchData(), cmAllocCrunchStructA(), cmProcessCrunchStructA()
  359.  
  360. CrM.library/cmProcessCrunchStructA         CrM.library/cmProcessCrunchStructA
  361.  
  362.     NAME
  363.     cmProcessCrunchStructA -- Allocate/Free a crunchstruct. (V4)
  364.  
  365.     SYNOPSIS
  366.     crunchstruct = cmProcessCrunchStructA
  367.                                          (crunchstruct, action, taglist);
  368.     D0             -66                    A1            D0      A0
  369.  
  370.     APTR cmProcessCrunchStructA (struct cmCrunchStruct *, ULONG,
  371.         struct TagItem *taglist);
  372.  
  373.     crunchstruct = cmProcessCrunchStruct (crunchstruct, action,
  374.         firsttag, ...);
  375.  
  376.     APTR cmProcessCrunchStruct (struct cmCrunchStruct *, ULONG,
  377.         Tag, ...);
  378.  
  379.     FUNCTION
  380.     Allocates or frees a cmCrunchStruct structure needed by
  381.     cmCrunchData().  action has to be either cm_AllocStruct or
  382.     cm_FreeStruct.
  383.  
  384.     action=cm_AllocStruct allocates a cmCrunchStruct and crunchstruct may
  385.     be of any value.  You may control the crunchalgorithm, the
  386.     crunchoffset and the huffman buffer size (in LZ-Huffman mode) with
  387.     tags (see below).  You may use the same crunchstruct for several
  388.     calls to cmCrunchData() but you may *NOT* change any of the readonly
  389.     fields.  So you have to free the crunchstruct and allocate another
  390.     one when you want to change the crunchalgorithm or the crunchoffset.
  391.     The allocated crunchstruct is returned in D0.  When you don't have
  392.     enough memory for the buffers needed, that is about 200-400K
  393.     depending on algorithm and offset, cmProcessCrunchStructA() will fail
  394.     and return Null.
  395.  
  396.     When you choose action=cmFreeStruct you have to provide a
  397.     crunchstruct but no tags are taken care of.  All allocated buffers
  398.     will be freed.  In this case cmProcessCrunchStructA() will always
  399.     return Null.
  400.  
  401.     INPUTS
  402.     crunchstruct - pointer to a cmCrunchStruct struture
  403.                    (action=cm_FreeStruct)
  404.     action       - type of operation: cm_AllocStruct or cm_FreeStruct
  405.     taglist      - pointer to an array of tags (action=cm_AllocStruct)
  406.  
  407.     TAGS
  408.     CMCS_Algo     - (UWORD)
  409.                     Determines which algorithm you want to use.  Values
  410.                     may be (stored in lower 4 bits):
  411.                       cm_Normal    - File was crunched with CrM-Normal
  412.                                      algorithm.
  413.                       cm_LZH       - File was crunched with LZ-Huffman
  414.                                      algorithm.
  415.                     in addition these Flags may be set (default=FALSE):
  416.                       cmF_Sample   - Use the Sample-Mode.
  417.                       cmF_PW       - Enable Password Encryption.
  418.                       cmF_Overlay  - Source and Dest memory region
  419.                                      overlap. (cmcr_Dest <= cmcr_Src) has
  420.                                      to be true in this case.
  421.                       cmF_LEDFlash - Power LED flashes while crunching.
  422.                     Default is cm_LZH.
  423.     CMCS_Offset   - (UWORD)
  424.                     Offset you want to crunch the data with.  Bigger
  425.                     offsets produce better results but also longer crunch
  426.                     times.  Default and maximum is $7ffe.
  427.     CMCS_HuffSize - (UWORD)
  428.                     Sets the size of the huffman buffer in KBytes (only
  429.                     valid if you use the cm_LZH algorith).  Default is
  430.                     16.
  431.  
  432.     RESULT
  433.     crunchstruct - pointer to a cmCrunchStruct structure or Null for
  434.                    failure when action=cm_AllocStruct.
  435.  
  436.     BUGS
  437.     Well, it's not really a bug, but you should not change the cmcr_Algo
  438.     field yourself.  This means that you should free your old
  439.     crunchstruct and allocate a new one also to swtich a minor thing like
  440.     password encryption on or off.  This is for future compatibility.  It
  441.     is safe to change the flags in the cmcr_Algo field between two calls
  442.     to cmCrunchData() but it's not a nice way.  _NEVER_ change the
  443.     crunchalgorithm this way!
  444.  
  445.     SEE ALSO
  446.     cmCrunchData()
  447.  
  448. CrM.library/cmProcessPW                               CrM.library/cmProcessPW
  449.  
  450.     NAME
  451.     cmProcessPW() -- Add/remove a pw to/from the internal list. (V4)
  452.  
  453.     SYNOPSIS
  454.     action = cmProcessPW (password, action);
  455.     D0       -54          A0        D0
  456.  
  457.     ULONG cmProcessPW (CHAR *, ULONG);
  458.  
  459.     FUNCTION
  460.     Add or remove a password to/from the library internal list.
  461.  
  462.     The password may be upto 80 bytes long plus the terminating zero.
  463.     Supplying Null instead a pointer to the password will display a
  464.     reqtools requester to let you enter the password.
  465.  
  466.     To add a password to the list set action to cm_AddPW.  When the
  467.     password is already in the list nothing will happen and Null is
  468.     returned, otherwise the password will be added and you get cm_AddPW
  469.     as resultcode.
  470.  
  471.     If you set action to cm_RemovePW the given password will be searched
  472.     in the list and removed from it.  When the password is not in the
  473.     list Null is returned, otherwise cm_RemovePW.
  474.  
  475.     action=cm_RemoveAll will clear the whole list.  You always get
  476.     cm_RemoveAll as resultcode.
  477.  
  478.     To switch the state of the password set action to Null.  This means
  479.     that when the given password is already in the list it will be
  480.     removed from it, otherwise it is added to the list.  The return value
  481.     reflects the action that was done.
  482.  
  483.     A returned Null either means that nothing was done or that there
  484.     occured an error as no reqtools.library or not enough memory
  485.     available.
  486.  
  487.     INPUTS
  488.     password - pointer to the password to process or Null to invoke a
  489.                reqtools requester.
  490.     action   - type of operation: cm_AddPW, cm_RemovePW, cm_RemoveAll or
  491.                Null.
  492.  
  493.     RESULT
  494.     action   - operation that was done.
  495.  
  496.     SEE ALSO
  497.     cmCryptData(), cmDecrunch()
  498.  
  499.