home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 2 / AACD 2.iso / AACD / Programming / prooflibrary / autodocs / proof.autodoc
Encoding:
Text File  |  1999-03-12  |  35.9 KB  |  1,195 lines
  1. TABLE OF CONTENTS
  2.  
  3. proof.library/--background--
  4. proof.library/--history--
  5. proof.library/AllocProofA
  6. proof.library/AllocProofOwnerA
  7. proof.library/AllocProofOwnerEntry
  8. proof.library/ConvertFromProofA
  9. proof.library/ConvertToProofA
  10. proof.library/FreeProof
  11. proof.library/FreeProofOwner
  12. proof.library/GetProofAttrsA
  13. proof.library/GetProofOwnerAttrsA
  14. proof.library/GetProofOwnerEntry
  15. proof.library/IsProofA
  16. proof.library/IsProofFromLockA
  17. proof.library/LoadProofA
  18. proof.library/LoadProofFromBPTRA
  19. proof.library/LoadProofFromLockA
  20. proof.library/LoadProofOwnerA
  21. proof.library/SaveProofA
  22. proof.library/SaveProofOwnerA
  23. proof.library/SetProofAttrsA
  24. proof.library/SetProofOwnerAttrsA
  25. proof.library/SetProofOwnerEntry
  26. proof.library/ValidProofDesc
  27. proof.library/--background--                     proof.library/--background--
  28.  
  29.    PURPOSE
  30.  To create small 'proof' sized images of pictures for display with the
  31.  option of storing them to disk in a compact, fast format, suitable for
  32.  viewing on any target display system. 
  33.  
  34.    COPYRIGHT
  35.  The copyright in this library is owned by Paul Huxham.
  36.  
  37.  PhotoAlbum is Copyright 1996-1998 by Helmut Hoffmann
  38.  
  39.    DISCLAIMER
  40.  proof.library and its associated files are supposed to be a proof
  41.  creation/maintenance system. Even though every effort has been made to
  42.  make proof.library as stable and functional as possible, I cannot rule
  43.  out the possibility that proof.library may have bugs that have side
  44.  effects (possibly harmful) on your system.
  45.  
  46.  I hereby reject any liability or responsibility for these or any other
  47.  consequences from the use of proof.library whatsoever. This includes, but
  48.  is not limited to, damage to your equipment, to your data, personal
  49.  injuries, financial loss or any other kinds of side effects.
  50.  
  51.  proof.library is provided as-is. This means I do not guarantee that
  52.  proof.library is fit for any specific purpose and I do not guarantee any
  53.  bug fixes, updates or help during error recovery.
  54.  
  55.    DISTRIBUTION
  56.  proof.library should be distributed at no charge to the end user. It may
  57.  be included on Aminet CDs.
  58.  
  59.  The author retains all rights to the enclosed software. Payment is not
  60.  required for the use of proof.library.
  61.  
  62.  For ANY COMMERCIAL APPLICATION using proof.library, contact the author
  63.  for further information concerning distribution.
  64.  
  65.    REQUIREMENTS
  66.  A minimum of Kickstart 2.0, 68020 CPU is required to use proof.library.
  67.  jpeg.library (by the same author) is required IF you intend to use the
  68.  default proof body format. (You most probably will!)
  69.  
  70.    COMPLIER
  71.  proof.library was written and compiled using CED V3.5 and SAS/C 6.55 on
  72.  an Amiga 4000/060. CyberGuard was used to detect/correct programming
  73.  errors.
  74.  
  75.    BUGS
  76.  Should you find any bugs, please report them so that they can be fixed.
  77.  Likewise any suggestions for improvment of the library should be
  78.  forwarded so that they can be addressed.
  79.  
  80.    THANKYOUS
  81.  Many thanks to
  82.    Dinh Thi Kim Tuyen
  83.      -whom I cannot thank enough for showing me what I can be when I let
  84.       go of the darkness. I love you.
  85.  
  86.    Steve Quartly
  87.      - For pushing me into corners I wouldn't normally go, to teach me to
  88.        see things where I would normally give up.
  89.  
  90.    AUTHOR
  91.   You can contact the author via:
  92.     email: paulh@mafeking.scouts.org.au
  93.   or
  94.     P.O. Box 875
  95.     Morley,
  96.     Perth,
  97.     Western Australia 6943
  98.  
  99. proof.library/--history--                           proof.library/--history--
  100.  
  101.  V2.1
  102.   > Fixed a bug where a non-linked loaded proof didn't contain an
  103.     ImagePath. Proofs created in memory did.
  104.  
  105.  V2.0
  106.   > Fixed an oversight where the proofs minimum size was 10 x 10. Now the
  107.     minimum size is 1 x 1.
  108.  
  109.   > Now you can pass a pointer to a NULL string in PFN_ProofPath and the
  110.     generated proof will be nonlinked. This is the same as not passing in
  111.     this tag at all. ("PFN_ProofPath, NULL" is the same as not passing in
  112.     this tag.)
  113.  
  114.   > Added a new tag PFN_ProofLinked. If you use GetProofAttrs() with this
  115.     tag, you can tell if the proof is linked or nonlinked.
  116.  
  117.  V1.3
  118.   > Fixed a bug where if ConvertToProof() was called more than once on
  119.     the same proof pointer, memory was lost.
  120.  
  121.  V1.2
  122.   > Fixed a bug where if the original proof is a photoalbum thumbnail,
  123.     getting the PFN_TextImageDesc returned an invalid pointer.
  124.  
  125.  V1.1
  126.   > Fixed a bug where if the original format was greyscale, getting the
  127.     image description returned a stray pointer to memory.
  128.  
  129.   > Added an environment variable to allow switching off the check by
  130.     protection bits. This fixes problems with filesystems that dont store
  131.     or return protection bits correctly, eg CDs. in ENV:proof.library, make
  132.     a variable called 'Test_Proof_By_Protection" and set it it 'yes' or
  133.     'no'. Use a value of no to skip testing the protection bits.
  134.  
  135.   > Fixed an enforcer hit, if the filetype stored by the calling
  136.     application was above the specified range. (Was supposed to allow for
  137.     custom image format descriptions.)
  138.  
  139.  V1.0
  140.   > Initial release.
  141.  
  142. proof.library/AllocProofA                           proof.library/AllocProofA
  143.  
  144.    NAME
  145.  AllocProofA -- Allocate memory space for a proof structure
  146.  AllocProof -- Varargs stub for AllocProofA
  147.  
  148.    SYNOPSIS
  149.  err = AllocProofA( pf, taglist )
  150.                     a0  a1
  151.  
  152.  ULONG AllocProofA( struct Proof **pf, struct TagItem *taglist )
  153.  
  154.  err = AllocProof( pf, tag1, ... )
  155.  
  156.  ULONG AllocProof( struct Proof **pf, ULONG tag1, ... )
  157.  
  158.    FUNCTION
  159.  Allocates the necessary memory space for a proof structure. Should be
  160.  matched with a call to FreeProof().
  161.  
  162.    INPUTS
  163.  pf      - pointer to a struct Proof pointer.
  164.  taglist - pointer to an optional tag list specifying how to initialize
  165.            the data structure returned by this function. (For a complete
  166.            list of available tags, see the SetProofAttrsA() function).
  167.  
  168.    RESULT
  169.  err - returns PFERR_NONE if successful, otherwise an error code.
  170.        See proof.h for error code definitions.
  171.  
  172.    NOTE
  173.  If you intend to use the PFN_MemoryPool tag, you MUST pass the same
  174.  memory pool pointer (result from CreatePool) to every function called in
  175.  proof.library.
  176.  
  177.    WARNING
  178.  
  179.    BUGS
  180.  
  181.    SEE ALSO
  182.  FreeProof(), SetProofAttrsA()
  183.  
  184. proof.library/AllocProofOwnerA                 proof.library/AllocProofOwnerA
  185.  
  186.    NAME
  187.  AllocProofOwnerA -- Allocate memory space for a proof owner structure
  188.  AllocProofOwner -- Varargs stub for AllocProofOwnerA
  189.  
  190.    SYNOPSIS
  191.  err = AllocProofOwnerA( po, taglist )
  192.                          a0  a1
  193.  
  194.  ULONG AllocProofOwnerA( struct ProofOwner **po, struct TagItem *taglist )
  195.  
  196.  err = AllocProofOwner( po, tag1, ... )
  197.  
  198.  ULONG AllocProofOwner( struct ProofOwner **po, ULONG tag1, ... )
  199.  
  200.    FUNCTION
  201.  Allocates the necessary memory space for a proof owner structure. Should
  202.  be matched with a call to FreeProofOwner().
  203.  
  204.    INPUTS
  205.  po      - pointer to a struct ProofOwner pointer.
  206.  taglist - pointer to an optional tag list.
  207.  
  208.    RESULT
  209.  err - returns PFERR_NONE if successful, otherwise an error code.
  210.        See proof.h for error code definitions.
  211.  
  212.    NOTE
  213.  If you intend to use the PFN_MemoryPool tag, you MUST pass the same
  214.  memory pool pointer (result from CreatePool) to every function called in
  215.  proof.library.
  216.  
  217.    WARNING
  218.  
  219.    BUGS
  220.  
  221.    SEE ALSO
  222.  FreeProofOwner()
  223.  
  224. proof.library/AllocProofOwnerEntry         proof.library/AllocProofOwnerEntry
  225.  
  226.    NAME
  227.  AllocProofOwnerEntry -- Allocate a new bit for an owner entry
  228.  
  229.    SYNOPSIS
  230.  result = AllocProofOwnerEntry( po, group, name, bitnum )
  231.                                 a0  d0     a1    a2
  232.  
  233.  ULONG AllocProofOwnerEntry( struct ProofOwner *po, BYTE group,
  234.                            char *name, LONG *bitnum )
  235.  
  236.    FUNCTION
  237.  Allocates a new bit for an owner entry. 
  238.  
  239.    INPUTS
  240.  po     - Pointer to a struct ProofOwner.
  241.  group  - A group number from 0 to 3.
  242.  name   - The name to set the entry to.
  243.  bitnum - A pointer to a LONG to store the bit number allocated for you.
  244.  
  245.    RESULT
  246.  err - returns PFERR_NONE if successful (bitnum is undefined), otherwise
  247.        an error code. See proof.h for error code definitions.
  248.  
  249.    WARNING
  250.  
  251.    BUGS
  252.  
  253.    SEE ALSO
  254.  GetProofOwnerEntry()
  255.  
  256. proof.library/ConvertFromProofA               proof.library/ConvertFromProofA
  257.  
  258.    NAME
  259.  ConvertFromProofA -- Convert proof data to a target format
  260.  ConvertFromProof -- Varargs stubs for ConvertFromProofA
  261.  
  262.    SYNOPSIS
  263.  err = ConvertFromProofA( pf, taglist )
  264.                           a0  a1
  265.  
  266.  ULONG ConvertFromProofA( struct Proof *pf, struct TagItem *taglist )
  267.  
  268.  err = ConvertFromProof( pf, tag1, ... )
  269.  
  270.  ULONG ConvertFromProofA( struct Proof *pf, ULONG tag1, ... )
  271.  
  272.    FUNCTION
  273.  Convert proof image data to a destination format. Currently only RGB
  274.  triplet destination buffers are supported.
  275.  
  276.    INPUTS
  277.  pf      - pointer to a struct Proof.
  278.  taglist - pointer to an optional tag list specifying how to convert the
  279.            proof data.
  280.  
  281.       PFN_RGBTripletBuffer - Specifies a pointer to store the RGB
  282.           triplets into.
  283.  
  284.    RESULT
  285.  err - returns PFERR_NONE if successful, otherwise an error code.
  286.        See proof.h for error code definitions.
  287.  
  288.    WARNING
  289.  
  290.    BUGS
  291.  
  292.    SEE ALSO
  293.  
  294. proof.library/ConvertToProofA                   proof.library/ConvertToProofA
  295.  
  296.    NAME
  297.  ConvertToProofA -- Convert an image to thumbnail data
  298.  ConvertToProof -- Varargs stubs for ConvertToProofA
  299.  
  300.    SYNOPSIS
  301.  err = ConvertToProofA( pf, taglist )
  302.                         a0  a1
  303.  
  304.  ULONG ConvertToProofA( struct Proof *pf, struct TagItem *taglist )
  305.  
  306.  err = ConvertToProof( pf, tag1, ... )
  307.  
  308.  ULONG ConvertToProofA( struct Proof *pf, ULONG tag1, ... )
  309.  
  310.    FUNCTION
  311.  Convert an buffer to a proof image. Currently only RGB triplet buffers
  312.  are supported.
  313.  
  314.    INPUTS
  315.  pf      - pointer to a struct Proof.
  316.  taglist - pointer to an optional tag list specifying how to convert the
  317.            image data. You may also pass in any header tags as described
  318.            in GetProofAttrs().
  319.  
  320.       PFN_RGBTripletBuffer - Specifies a pointer to the first red component
  321.           of the RGB triplets, stored contiguously in memory. (The width
  322.           and height of the buffer data must be passed either with this
  323.           function, or in AllocProofA().
  324.  
  325.       PFN_JFIFQuality - A jpeg save quality value (0-100) to use with
  326.           jpeg.library if saving the proof in jpeg format (default 85).
  327.  
  328.       PFN_MemoryPool - A memory pool pointer to allocate memory for the
  329.           proof image.
  330.  
  331.    RESULT
  332.  err - returns PFERR_NONE if successful, otherwise an error code.
  333.        See proof.h for error code definitions.
  334.  
  335.    WARNING
  336.  
  337.    BUGS
  338.  
  339.    SEE ALSO
  340.  
  341. proof.library/FreeProof                               proof.library/FreeProof
  342.  
  343.    NAME
  344.  FreeProof -- Free the memory space allocated for a proof
  345.  
  346.    SYNOPSIS
  347.  FreeProof( pf, taglist )
  348.             a0  a1
  349.  
  350.  void FreeProof( struct Proof **pf, struct TagItem *taglist )
  351.  
  352.    FUNCTION
  353.  Frees all memory space associated with a proof structure. It is safe to
  354.  call this function with a NULL proof pointer.
  355.  
  356.    INPUTS
  357.  pf - pointer to a struct Proof pointer.
  358.  taglist - pointer to an optional tag list.
  359.  
  360.    RESULT
  361.  
  362.    NOTE
  363.  If you intend to use the PFN_MemoryPool tag, you MUST pass the same
  364.  memory pool pointer (result from CreatePool) to every function called in
  365.  proof.library.
  366.  
  367.    WARNING
  368.  
  369.    BUGS
  370.  
  371.    SEE ALSO
  372.  AllocProofA()
  373.  
  374. proof.library/FreeProofOwner                     proof.library/FreeProofOwner
  375.  
  376.    NAME
  377.  FreeProofOwner -- Free the memory space allocated for a proof owner
  378.  
  379.    SYNOPSIS
  380.  FreeProofOwner( po, taglist )
  381.                  a0  a1
  382.  
  383.  void FreeProofOwner( struct ProofOwner **po, struct TagItem *taglist )
  384.  
  385.    FUNCTION
  386.  Frees all memory space associated with a proof owner structure. If the
  387.  proof owner structure has not been saved, it will be lost. It is safe to
  388.  call this function with a NULL proofowner pointer.
  389.  
  390.    INPUTS
  391.  po - pointer to a struct ProofOwner pointer.
  392.  taglist - pointer to an optional tag list.
  393.  
  394.    RESULT
  395.  
  396.    NOTE
  397.  If you intend to use the PFN_MemoryPool tag, you MUST pass the same
  398.  memory pool pointer (result from CreatePool) to every function called in
  399.  proof.library.
  400.  
  401.    WARNING
  402.  
  403.    BUGS
  404.  
  405.    SEE ALSO
  406.  AllocProofOwnerA()
  407.  
  408. proof.library/GetProofAttrsA                     proof.library/GetProofAttrsA
  409.  
  410.    NAME
  411.  GetProofAttrsA -- Get attributes of a proof
  412.  GetProofAttrs -- Varargs stub for GetProofAttrsA
  413.  
  414.    SYNOPSIS
  415.  result = GetProofAttrsA( pf, taglist )
  416.                          a0  a1
  417.  
  418.  ULONG GetProofAttrsA( struct Proof *pf, struct TagItem *taglist )
  419.  
  420.  result = GetProofAttrs( pf, tag1, ... )
  421.  
  422.  BOOL GetProofAttrs( struct Proof *pf, ULONG tag1, ... )
  423.  
  424.    FUNCTION
  425.  Returns specified information from the proof into the taglist (ti_Data)
  426.  pointers.
  427.  
  428.    INPUTS
  429.  pf      - pointer to a struct Proof.
  430.  taglist - pointer to a tag list, containing the information to retrieve.
  431.  
  432.   Proof header tags
  433.    PFN_ProofPathName - Return the path/filename of this proof's file. (char *
  434. *)
  435.  
  436.    PFN_CustomBuffer - Return a pointer to the custom buffer. (UBYTE **)
  437.  
  438.    PFN_CustomBufferSize - Return the size of the custom buffer. (ULONG *)
  439.  
  440.    PFN_Comment - Return the comment associated with the proof. (char **)
  441.  
  442.    PFN_ProofVersion - Return the version number of the proof. (UBYTE *)
  443.  
  444.    PFN_ProofWidth - Return the width of the proof. (UBYTE *)
  445.  
  446.    PFN_ProofHeight - Return the height of the proof. (UBYTE *)
  447.  
  448.    PFN_ProofQuestionable - Return the questionability of the proof. (BOOL *)
  449.  
  450.    PFN_ProofAspectX - Return the x aspect of the proof. (WORD *)
  451.  
  452.    PFN_ProofAspectY - Return the y aspect of the proof. (WORD *)
  453.  
  454.    PFN_ProofSaveable - Return the savabilty of the proof. (BOOL *)
  455.  
  456.   Proof description tags
  457.    PFN_ImageName - Return the filename of the original image file
  458.             associated with this proof. (char **)
  459.  
  460.    PFN_ImagePath - Return the path of the original image file associated
  461.             with this proof. (char **)
  462.  
  463.    PFN_ImageWidth - Return the width of the image. (ULONG *)
  464.  
  465.    PFN_ImageHeight - Return the height of the image. (ULONG *)
  466.  
  467.    PFN_ImageFileSize - Return the file size of the image. (ULONG *)
  468.  
  469.    PFN_ImageType - Return the type of the image as PDIV_*. (UBYTE *)
  470.  
  471.    PFN_ImageDepth - Return the depth of the image. (UBYTE *)
  472.  
  473.    PFN_ImageFormat - Return the format of the image as PDFB_*. (UBYTE *)
  474.  
  475.    PFN_CategoryOwner - Return the image's category owner. (UBYTE *)
  476.  
  477.    PFN_ImageGroup - Return the group of the image. (UBYTE *)
  478.  
  479.    PFN_ImageCategory - Return the category of the image. (ULONG *)
  480.  
  481.    PFN_TextImageType - Return a pointer to a text descriptor of the
  482.             original image. (char **)
  483.  
  484.    PFN_TextImageDesc - Copies into the supplied pointer a text descriptor
  485.             of the image format. (char *)
  486.  
  487.   Miscellaneous tags
  488.    PFN_UserData - Return the user data field. (ULONG *)
  489.  
  490.    RESULT
  491.  err - returns PFERR_NONE if successful, otherwise an error code.
  492.        See proof.h for error code definitions.
  493.  
  494.    WARNING
  495.  
  496.    BUGS
  497.  
  498.    SEE ALSO
  499.  
  500. proof.library/GetProofOwnerAttrsA           proof.library/GetProofOwnerAttrsA
  501.  
  502.    NAME
  503.  GetProofOwnerAttrsA -- Get attributes of a proof owner structure
  504.  GetProofOwnerAttrs -- Varargs stub for GetProofAttrsOwnerA
  505.  
  506.    SYNOPSIS
  507.  result = GetProofOwnerAttrsA( po, taglist )
  508.                                a0  a1
  509.  
  510.  ULONG GetProofOwnerAttrsA( struct ProofOwner *po,
  511.                           struct TagItem *taglist )
  512.  
  513.  result = GetProofOwnerAttrs( po, tag1, ... )
  514.  
  515.  ULONG GetProofAttrs( struct ProofOwner *po, ULONG tag1, ... )
  516.  
  517.    FUNCTION
  518.  Gets specified information in the taglist from proof owner structure.
  519.  
  520.    INPUTS
  521.  po      - pointer to a struct ProofOwner.
  522.  taglist - pointer to a tag list, containing the information to get.
  523.  
  524.       PFN_ProofOwnerID - Retrieves the owner ID of this
  525.           structure. (UBYTE *)
  526.  
  527.       PFN_ProofOwnerIdent - Retrieves the ident string for this
  528.           structure. (char **)
  529.  
  530.    RESULT
  531.  err - returns PFERR_NONE if successful, otherwise an error code.
  532.        See proof.h for error code definitions.
  533.  
  534.    WARNING
  535.  
  536.    BUGS
  537.  
  538.    SEE ALSO
  539.  SetProofOwnerAttrsA()
  540.  
  541. proof.library/GetProofOwnerEntry             proof.library/GetProofOwnerEntry
  542.  
  543.    NAME
  544.  GetProofOwnerEntry -- Get the name of a group/category from a proof owner
  545.  
  546.    SYNOPSIS
  547.  result = GetProofOwnerEntry( po, group, category )
  548.                               a0  d0     d1
  549.  
  550.  char *GetProofOwnerEntry( struct ProofOwner *po, BYTE group,
  551.                          BYTE category )
  552.  
  553.    FUNCTION
  554.  Gets the name of group/category from the specified proof owner.
  555.  
  556.    INPUTS
  557.  po       - Pointer to a struct ProofOwner.
  558.  group    - A group number from 0 to 3.
  559.  category - A category number from 0 to 22 or POWN_GROUP_NAME to get the
  560.             name of the group.
  561.  
  562.    RESULT
  563.  result - returns NULL if no entry defined, or a pointer to a NULL
  564.           terminated string.
  565.  
  566.    WARNING
  567.  
  568.    BUGS
  569.  
  570.    SEE ALSO
  571.  SetProofOwnerEntry()
  572.  
  573. proof.library/IsProofA                                 proof.library/IsProofA
  574.  
  575.    NAME
  576.  IsProofA -- Tests if a file is a proof file
  577.  IsProof -- Varargs stub for IsProofA
  578.  
  579.    SYNOPSIS
  580.  result = IsProofA( pathname, taglist )
  581.                     a0        a1
  582.  
  583.  BOOL IsProofA( char *pathname, struct TagItem *taglist )
  584.  
  585.  result = IsProof( pathname, tag1, ... )
  586.  
  587.  BOOL IsProof( char *pathname, ULONG tag1, ... )
  588.  
  589.    FUNCTION
  590.  Tests if the specified path/filename is a proof file. If the file does
  591.  not exist, FALSE will be returned.
  592.  
  593.    INPUTS
  594.  pathname - pointer to a string containing the complete path and filename
  595.             of the file to test.
  596.  taglist  - pointer to an optional tag list.
  597.  
  598.       PFN_AllowPhotoAlbum - If TRUE, allow photoalbum proofs (jfif format)
  599.           to be read. (Default TRUE)
  600.  
  601.       PFN_TestProofByProtection - If TRUE, use the proof protection bit to
  602.           determine if the file is a proof. This negates the
  603.           PFN_AllowPhotoAlbum tag. (default TRUE)
  604.  
  605.    RESULT
  606.  result - returns TRUE if pathname is a proof, otherwise FALSE. FALSE
  607.           will also be returned if the file does not exist.
  608.  
  609.    WARNING
  610.  How the file type is determined is private! This may be changed in the
  611.  future. You MUST use the library functions to determine if a file is
  612.  indeed a proof file.
  613.  
  614.    BUGS
  615.  Some file system handlers, notably for CD, do not return the all or any
  616.  protectionbits. To eliminate this as a problem for detecting proofs
  617.  stored on these devices, you can set the environment variable:
  618.  proof.library/Test_Proof_By_Protection to "no". This will disable using
  619.  protection bits for proof detection for all applications using the
  620.  library.
  621.  
  622.    SEE ALSO
  623.  IsProofFromLockA()
  624.  
  625. proof.library/IsProofFromLockA                 proof.library/IsProofFromLockA
  626.  
  627.    NAME
  628.  IsProofFromLockA -- Tests if the lock is a proof file
  629.  IsProofFromLock -- Varargs stub for IsProofFromLockA
  630.  
  631.    SYNOPSIS
  632.  result = IsProofFromLockA( lock, taglist )
  633.                              a0   a1
  634.  
  635.  BOOL IsProofFromLockA( BPTR lock, struct TagItem *taglist )
  636.  
  637.  result = IsProofFromLock( BPTR lock, tag1, ... )
  638.  
  639.  BOOL IsProofFromLock( BPTR lock, ULONG tag1, ... )
  640.  
  641.    FUNCTION
  642.  Tests if the specified lock is a proof file. If the file does not
  643.  exist, FALSE will be returned.
  644.  
  645.    INPUTS
  646.  lock     - lock on the file to test.
  647.  taglist  - pointer to an optional tag list.
  648.  
  649.       PFN_AllowPhotoAlbum - If TRUE allow photoalbum proofs (jfif format)
  650.           to be read. (Default TRUE)
  651.  
  652.       PFN_TestProofByProtection - If TRUE, use the proof protection bit to
  653.           determine if the file is a proof. This negates the
  654.           PFN_AllowPhotoAlbum tag. (default TRUE)
  655.  
  656.    RESULT
  657.  result - returns TRUE if lock is a proof, otherwise FALSE.
  658.  
  659.    WARNING
  660.  How the file type is determined is private! This may be changed in the
  661.  future. You MUST use the library functions to determine if a file is
  662.  indeed a proof file.
  663.  
  664.    BUGS
  665.  Some file system handlers, notably for CD, do not return the all or any
  666.  protectionbits. To eliminate this as a problem for detecting proofs
  667.  stored on these devices, you can set the environment variable:
  668.  proof.library/Test_Proof_By_Protection to "no". This will disable using
  669.  protection bits for proof detection for all applications using the
  670.  library.
  671.  
  672.    SEE ALSO
  673.  IsProofA()
  674.  
  675. proof.library/LoadProofA                             proof.library/LoadProofA
  676.  
  677.    NAME
  678.  LoadProofA -- Load a proof from disk
  679.  LoadProof -- Varargs stub for LoadProofA
  680.  
  681.    SYNOPSIS
  682.  err = LoadProofA( filename, pf, taglist )
  683.                    a0        a1  a2
  684.  
  685.  ULONG LoadProofA( char *filename, struct Proof **pf,
  686.                        struct TagItem *taglist )
  687.  
  688.  err = LoadProofA( filename, pf, tag1, ... )
  689.  
  690.  ULONG LoadProof( char *filename, struct Proof **pf,
  691.                       ULONG tag1, ... )
  692.  
  693.    FUNCTION
  694.  Loads a proof structure from disk into memory using the filename,
  695.  applying the specified tags. Should be matched with a call to
  696.  FreeProof() if call returns successfully.
  697.  Supplying a pointer to a pointer containing NULL (empty pointer to
  698.  pointer) is valid. A proof structure will be allocated for you and
  699.  returned in your pointer (no need to call AllocProof() in this case), if
  700.  an error occurs whilst loading, you are however not required to call
  701.  FreeProof().
  702.  
  703.    INPUTS
  704.  filename - filename of proof to load.
  705.  pf       - pointer to a struct Proof pointer (contents may be NULL).
  706.  taglist  - pointer to an optional tag list.
  707.  
  708.       PFN_AllowPhotoAlbum - If TRUE allow photoalbum proofs (jfif format)
  709.           to be read. (Default TRUE)
  710.  
  711.    RESULT
  712.  err - returns PFERR_NONE if successful, otherwise an error code.
  713.        See proof.h for error code definitions.
  714.  
  715.    WARNING
  716.  If you are calling this function in a loop, be sure to NULL the passed in
  717.  proof pointer every time the function is called, otherwise you will
  718.  overwrite the previously allocated proof.
  719.  
  720.    BUGS
  721.  
  722.    SEE ALSO
  723.  FreeProof(), LoadProofFromLockA(), LoadProofFromBPTRA()
  724.  
  725. proof.library/LoadProofFromBPTRA             proof.library/LoadProofFromBPTRA
  726.  
  727.    NAME
  728.  LoadProofFromBPTRA -- Load a proof from an open BPTR file pointer.
  729.  LoadProofFromBPTR -- Varargs stub for LoadProofFromBPTRA
  730.  
  731.    SYNOPSIS
  732.  err = LoadProofFromBPTRA( fp, pf, taglist )
  733.                            a0        a1  a2
  734.  
  735.  ULONG LoadProofBPTRA( BPTR fp, struct Proof **pf,
  736.                        struct TagItem *taglist )
  737.  
  738.  err = LoadProofFromBPTRA( fp, pf, tag1, ... )
  739.  
  740.  ULONG LoadProofFromBPTR( BPTR fp, struct Proof **pf, ULONG tag1, ... )
  741.  
  742.    FUNCTION
  743.  Loads a proof structure from disk into memory using the already open AND
  744.  positioned AmigaDOS file BPTR pointer, applying the specified tags.
  745.  Should be matched with a call to FreeProof() if call returns
  746.  successfully. Supplying a pointer to a pointer containing NULL (empty
  747.  pointer to pointer) is valid. A proof structure will be allocated for
  748.  you and returned in your pointer (no need to call AllocProof() in this
  749.  case), if an error occurs whilst loading, you are however not required
  750.  to call FreeProof().
  751.  
  752.    INPUTS
  753.  BPTR - already opened AND positioned AmigaDOS BPTR pointer of proof to
  754.         load.
  755.  pf       - pointer to a struct Proof pointer (contents may be NULL).
  756.  taglist  - pointer to an optional tag list.
  757.  
  758.       PFN_AllowPhotoAlbum - If TRUE allow photoalbum proofs (jfif format)
  759.           to be read. (Default TRUE)
  760.  
  761.    RESULT
  762.  err - returns PFERR_NONE if successful, otherwise an error code.
  763.        See proof.h for error code definitions.
  764.  
  765.    WARNING
  766.  If you are calling this function in a loop, be sure to NULL the passed in
  767.  proof pointer every time the function is called, otherwise you will
  768.  overwrite the previously allocated proof.
  769.  
  770.  Remember to pass in an OPEN and POSITIONED BPTR to this function.
  771.  
  772.    BUGS
  773.  
  774.    SEE ALSO
  775.  FreeProof(), LoadProofA(), LoadProofFromLockA()
  776.  
  777. proof.library/LoadProofFromLockA             proof.library/LoadProofFromLockA
  778.  
  779.    NAME
  780.  LoadProofFromLockA -- Load a proof from disk
  781.  LoadProofFromLock -- Varargs stub for LoadProofFromLockA
  782.  
  783.    SYNOPSIS
  784.  err = LoadProofFromLockA( lock, pf, taglist )
  785.                            a0    a1  a2
  786.  
  787.  ULONG LoadProofFromLockA( BPTR lock, struct Proof **pf,
  788.                                struct TagItem *taglist )
  789.  
  790.  err = LoadProofFromLockA( lock, pf, tag1, ... )
  791.  
  792.  ULONG LoadProofFromLock( BPTR lock, struct Proof **pf,
  793.                               ULONG tag1, ... )
  794.  
  795.    FUNCTION
  796.  Loads a proof structure from disk into memory using the lock. Should be
  797.  matched with a call to FreeProof().
  798.  Supplying a NULL pointer is valid. A proof structure will be allocated
  799.  for you and returned in your pointer - if an error occurs whilst loading,
  800.  you are however not required to call FreeProof(). Don't forget to
  801.  free the supplied lock after calling this function.
  802.  
  803.    INPUTS
  804.  lock    - lock on proof to load.
  805.  pf      - pointer to a struct Proof pointer (contents may be NULL).
  806.  taglist - pointer to an optional tag list.
  807.  
  808.       PFN_AllowPhotoAlbum - If TRUE allow photoalbum proofs (jfif format)
  809.           to be read. (Default TRUE)
  810.  
  811.    RESULT
  812.  err - returns PFERR_NONE if successful, otherwise an error code.
  813.        See proof.h for error code definitions.
  814.  
  815.    NOTE
  816.  If you intend to use the PFN_MemoryPool tag, you MUST pass the same
  817.  memory pool pointer (result from CreatePool) to every function called in
  818.  proof.library.
  819.  
  820.    WARNING
  821.  
  822.    BUGS
  823.  
  824.    SEE ALSO
  825.  FreeProof(), LoadProofA(), LoadProofFromBPTRA()
  826.  
  827. proof.library/LoadProofOwnerA                   proof.library/LoadProofOwnerA
  828.  
  829.    NAME
  830.  LoadProofOwnerA -- Load a proof owner from disk
  831.  LoadProofOwner -- Varargs stub for LoadProofOwnerA
  832.  
  833.    SYNOPSIS
  834.  err = LoadProofOwnerA( filename, po, taglist )
  835.                         a0        a1  a2
  836.  
  837.  ULONG LoadProofOwnerA( char *filename, struct ProofOwner **po,
  838.                       struct TagItem *taglist )
  839.  
  840.  err = LoadProofOwnerA( filename, po, tag1, ... )
  841.  
  842.  ULONG LoadProofOwner( char *filename, struct ProofOwner **po,
  843.                       ULONG tag1, ... )
  844.  
  845.    FUNCTION
  846.  Loads a proof owner file into memory, using the filename and applying the
  847.  specified tags. Should be matched with a call to FreeProofOwner() if call
  848.  returns successfully.
  849.  Supplying a pointer to a pointer containing NULL (empty pointer to
  850.  pointer) is valid. A proof owner structure will be allocated for you and
  851.  returned in your pointer (no need to call AllocProofOwner() in this
  852.  case), if an error occurs whilst loading, you are however not required
  853.  to call FreeProofOwner().
  854.  
  855.    INPUTS
  856.  filename - filename of proof owner to load.
  857.  pf       - pointer to a struct ProofOwner pointer (contents may be NULL).
  858.  taglist  - pointer to an optional tag list.
  859.  
  860.       PFN_MemoryPool - A memory pool pointer to allocate memory for the
  861.           nodes.
  862.  
  863.    RESULT
  864.  err - returns PFERR_NONE if successful, otherwise an error code.
  865.        See proof.h for error code definitions.
  866.  
  867.    NOTE
  868.  If you intend to use the PFN_MemoryPool tag, you MUST pass the same
  869.  memory pool pointer (result from CreatePool) to every function called in
  870.  proof.library.
  871.  
  872.    WARNING
  873.  If you are calling this function in a loop, be sure to NULL the passed in
  874.  proofowner pointer every time the function is called, otherwise you will
  875.  overwrite the previously allocated proofowner.
  876.  
  877.    BUGS
  878.  
  879.    SEE ALSO
  880.  FreeProofOwner()
  881.  
  882. proof.library/SaveProofA                             proof.library/SaveProofA
  883.  
  884.    NAME
  885.  SaveProofA -- Save a proof to disk
  886.  SaveProof -- Varargs stub for SaveProofA
  887.  
  888.    SYNOPSIS
  889.  err = SaveProofA( pf, taglist )
  890.                    a0  a1
  891.  
  892.  ULONG SaveProofA( struct Proof **pf, struct TagItem *taglist )
  893.  
  894.  err = SaveProofA( pf, tag1, ... )
  895.  
  896.  ULONG SaveProof( struct Proof **pf, ULONG tag1, ... )
  897.  
  898.    FUNCTION
  899.  Save a proof structure to disk, using the specified tags.
  900.  
  901.    INPUTS
  902.  pf      - pointer to a struct Proof pointer.
  903.  taglist - pointer to an optional tag list. (For a complete list of
  904.            available tags, see the SetProofAttrsA() function).
  905.  
  906.       PFN_ProofPath - Specifies the path to save the generated proof file.
  907.           Using this tag, implies that the proof is a linked proof.
  908.           Appropriate information will be saved in the proof file to allow
  909.           relocation of the proof fiel with respect to the original image.
  910.           If unspecified, the proof is saved into the images' directory
  911.           with a slightly different filename. No files will be overwritten
  912.           by this process!
  913.  
  914.       PFN_CustomBuffer - Specifies a pointer to a custom buffer to save
  915.           (implies PFN_CustomBufferSize).
  916.  
  917.       PFN_CustomBufferSize - Specifies the size in bytes of the custom
  918.           buffer to save (implies PFN_CustomBuffer).
  919.  
  920.    RESULT
  921.  err - returns PFERR_NONE if successful, otherwise an error code.
  922.        See proof.h for error code definitions.
  923.  
  924.    WARNING
  925.  
  926.    BUGS
  927.  
  928.    SEE ALSO
  929.  FreeProof()
  930.  
  931. proof.library/SaveProofOwnerA                   proof.library/SaveProofOwnerA
  932.  
  933.    NAME
  934.  SaveProofOwnerA -- Save a proof owner structure to disk
  935.  SaveProofOwner -- Varargs stub for SaveProofOwnerA
  936.  
  937.    SYNOPSIS
  938.  err = SaveProofOwnerA( po, taglist )
  939.                         a0  a1
  940.  
  941.  ULONG SaveProofOwnerA( struct ProofOwner *po, struct TagItem *taglist )
  942.  
  943.  err = SaveProofOwnerA( po, tag1, ... )
  944.  
  945.  ULONG SaveProofOwner( struct ProofOwner *po, ULONG tag1, ... )
  946.  
  947.    FUNCTION
  948.  Save a proof owner structure to disk, using the specified tags.
  949.  
  950.    INPUTS
  951.  po      - pointer to a struct ProofOwner.
  952.  taglist - pointer to an optional tag list.
  953.  
  954.       PFN_ProofOwnerName - Specifies the path/filename to save the proof
  955.           owner into. No files will be overwritten by this process!
  956.  
  957.    RESULT
  958.  err - returns PFERR_NONE if successful, otherwise an error code.
  959.        See proof.h for error code definitions.
  960.  
  961.    WARNING
  962.  
  963.    BUGS
  964.  
  965.    SEE ALSO
  966.  
  967. proof.library/SetProofAttrsA                     proof.library/SetProofAttrsA
  968.  
  969.    NAME
  970.  SetProofAttrsA -- Set attributes of a proof
  971.  SetProofAttrs -- Varargs stub for SetProofAttrsA
  972.  
  973.    SYNOPSIS
  974.  result = SetProofAttrsA( pf, taglist )
  975.                          a0  a1
  976.  
  977.  ULONG SetProofAttrsA( struct Proof *pf, struct TagItem *taglist )
  978.  
  979.  result = SetProofAttrs( pf, tag1, ... )
  980.  
  981.  ULONG SetProofAttrs( struct Proof *pf, ULONG tag1, ... )
  982.  
  983.    FUNCTION
  984.  Sets specified information from the taglist into the proof. Will also
  985.  resave the proof if it has already been saved.
  986.  
  987.    INPUTS
  988.  pf      - pointer to a struct Proof.
  989.  taglist - pointer to a tag list, containing the information to set.
  990.  
  991.    Header specific tags:
  992.       PFN_ProofWidth - Specifies the width in pixels of the Proof
  993.           image. Values range from 0 to 255. (UBYTE)
  994.  
  995.       PFN_ProofHeight - Specifies the Height in pixels of the Proof
  996.           image. Values range from 0 to 255. (UBYTE)
  997.  
  998.       PFN_ProofAspectX - Specifies the X aspect ratio of the Proof image.
  999.           The format is the same as in a DisplayInfo structure. (WORD)
  1000.  
  1001.       PFN_ProofAspectY - Specifies the Y aspect ratio of the Proof image.
  1002.           The format is the same as in a DisplayInfo structure. (WORD)
  1003.  
  1004.       PFN_ProofQuestionable - Specifies that image content of the
  1005.           Proof is of a dubious nature. Use this in a browser to
  1006.           determine which thumbnails to show at any given time (BOOL)
  1007.  
  1008.       PFN_ProofBodyType - Specifies the format of the proof image data.
  1009.           See proof.h for proof format definitions.
  1010.  
  1011.       PFN_ProofBodyFlags - Additional flags for proof body data.
  1012.           See proof.h for flag definitions.
  1013.  
  1014.    Description specific tags:
  1015.       PFN_ImageWidth - Specifies the width in pixels of the original
  1016.           image. Values range from 1 to 2147483647. (ULONG)
  1017.  
  1018.       PFN_ImageHeight - Specifies the height in pixels of the original
  1019.           image. Values range from 1 to 2147483647. (ULONG)
  1020.  
  1021.       PFN_ImageFileSize - Specifies the byte count of the original image
  1022.           (AmigaDOS file size). Values range from 1 to 2147483647. (ULONG)
  1023.  
  1024.       PFN_ImageFormat - Specifies the file format of the original image
  1025.           (eg JPEG, GIF etc). Valid values are defined in proof.h
  1026.  
  1027.       PFN_ImageDepth - Specifies the depth of the original image. See
  1028.           proof.h for the use of this value. Values range from 0 to 255.
  1029.           (UBYTE)
  1030.  
  1031.       PFN_CategoryOwner - Specifies the id of the owners category file.
  1032.           Values range from 0 to 255. (UBYTE)
  1033.  
  1034.       PFN_ImageGroup - Specifies the group this image belongs to. Values
  1035.           range from 0 to 3. (UBYTE)
  1036.  
  1037.       PFN_ImageCategory - Specifies the category this image belongs to.
  1038.           Values are bitwise for 22 bits of a ULONG. This allows images to
  1039.           be categorized into more than one category. (ULONG)
  1040.  
  1041.       PFN_ImagePlanar - Specifies that the original image is in a planar
  1042.           format. (BOOL)
  1043.  
  1044.       PFN_ImageChunky - Specifies that the original image is in a chunky
  1045.           format. (BOOL)
  1046.  
  1047.       PFN_ImageHAM6 - Specifies that the original image is in the HAM6
  1048.           format. (BOOL)
  1049.  
  1050.       PFN_ImageHalfBrite - Specifies that the original image is in the
  1051.           halfbrite format. (BOOL)
  1052.  
  1053.       PFN_ImageHAM8 - Specifies that the original image is in the HAM8
  1054.           format. (BOOL)
  1055.  
  1056.       PFN_Image24Bit - Specifies that the original image is a 24 bit
  1057.           format. (BOOL)
  1058.  
  1059.       PFN_ImageFlags - Specifies bulk flags descriptions (see proof.h)
  1060.  
  1061.       PFN_ImageComment - Specifies a comment string (unlimited length) to
  1062.           be saved along with the proof. (char *)
  1063.  
  1064.    Save specific tags:
  1065.       PFN_ImageName - Specifies the file name (excluding the path) of the
  1066.           original image. If you use this tag, you should also supply a
  1067.           PFN_ImagePath tag. (char *)
  1068.  
  1069.       PFN_ImagePath - Specifies the path of the original image. If you use
  1070.           this tag, you should also supply a PFN_ImageName tag. (char *)
  1071.  
  1072.       PFN_ImagePathName - Specifies the path and filename of the original
  1073.           image. This is mutually exclusive with PFN_ImageName and
  1074.           PFN_ImagePath tags. (char *)
  1075.  
  1076.       PFN_DescriptionChunk - Specifies if a TDSC chunk should be written to
  1077.           the proof file (default TRUE).
  1078.  
  1079.   Miscellaneous tags
  1080.    PFN_UserData - Sets the user data field. (ULONG)
  1081.  
  1082.    RESULT
  1083.  err - returns PFERR_NONE if successful, otherwise an error code.
  1084.        See proof.h for error code definitions.
  1085.  
  1086.    WARNING
  1087.  
  1088.    BUGS
  1089.  
  1090.    SEE ALSO
  1091.  
  1092. proof.library/SetProofOwnerAttrsA           proof.library/SetProofOwnerAttrsA
  1093.  
  1094.    NAME
  1095.  SetProofOwnerAttrsA -- Set attributes of a proof owner structure
  1096.  SetProofOwnerAttrs -- Varargs stub for SetProofAttrsOwnerA
  1097.  
  1098.    SYNOPSIS
  1099.  result = SetProofOwnerAttrsA( po, taglist )
  1100.                                a0  a1
  1101.  
  1102.  ULONG SetProofOwnerAttrsA( struct ProofOwner *po,
  1103.                           struct TagItem *taglist )
  1104.  
  1105.  result = SetProofOwnerAttrs( po, tag1, ... )
  1106.  
  1107.  ULONG SetProofAttrs( struct ProofOwner *po, ULONG tag1, ... )
  1108.  
  1109.    FUNCTION
  1110.  Sets specified information from the taglist into the proof owner.
  1111.  
  1112.    INPUTS
  1113.  po      - pointer to a struct ProofOwner.
  1114.  taglist - pointer to a tag list, containing the information to set.
  1115.  
  1116.       PFN_ProofOwnerID - Specifies the owner ID of this structure. Values
  1117.           range from 0 to 255. (UBYTE)
  1118.  
  1119.       PFN_ProofOwnerIdent - Specifies the name of the owner of this
  1120.           structure. Setting to NULL, removes the ident string. (char *)
  1121.  
  1122.    RESULT
  1123.  err - returns PFERR_NONE if successful, otherwise an error code.
  1124.        See proof.h for error code definitions.
  1125.  
  1126.    WARNING
  1127.  
  1128.    BUGS
  1129.  
  1130.    SEE ALSO
  1131.  GetProofOwnerAttrsA()
  1132.  
  1133. proof.library/SetProofOwnerEntry             proof.library/SetProofOwnerEntry
  1134.  
  1135.    NAME
  1136.  SetProofOwnerEntry -- Set the name of a group/category in a proof owner
  1137.  
  1138.    SYNOPSIS
  1139.  result = SetProofOwnerEntry( po, group, category, name )
  1140.                               a0  d0     d1        d2
  1141.  
  1142.  ULONG SetProofOwnerEntry( struct ProofOwner *po, BYTE group,
  1143.                          BYTE category, char *name )
  1144.  
  1145.    FUNCTION
  1146.  Sets the name of group/category in the specified proof owner. You can
  1147.  remove an entry by setting it to NULL. You can set the groups name, by
  1148.  passing POWN_GROUP_NAME as the category.
  1149.  
  1150.    INPUTS
  1151.  po       - Pointer to a struct ProofOwner.
  1152.  group    - A group number from 0 to 3.
  1153.  category - A category number from 0 to 22 or POWN_GROUP_NAME to specify
  1154.             the name of the group.
  1155.  name     - The name to set the entry to, or NULL to remove the entry.
  1156.  
  1157.    RESULT
  1158.  err - returns PFERR_NONE if successful, otherwise an error code.
  1159.        See proof.h for error code definitions.
  1160.  
  1161.    WARNING
  1162.  
  1163.    BUGS
  1164.  
  1165.    SEE ALSO
  1166.  GetProofOwnerEntry()
  1167.  
  1168. proof.library/ValidProofDesc                     proof.library/ValidProofDesc
  1169.  
  1170.    NAME
  1171.  ValidProofDesc -- Establish if a proof has a description
  1172.  
  1173.    SYNOPSIS
  1174.  result = ValidProofDesc( pf )
  1175.                           a0
  1176.  
  1177.  BOOL ValidProofDesc( struct proof *pf )
  1178.  
  1179.    FUNCTION
  1180.  Establishes if a proof contains an image descriptor.
  1181.  
  1182.    INPUTS
  1183.  pf - pointer to a struct Proof.
  1184.  
  1185.    RESULT
  1186.  err - returns TRUE if the proof contains a valid description or FALSE if
  1187.        not.
  1188.  
  1189.    WARNING
  1190.  
  1191.    BUGS
  1192.  
  1193.    SEE ALSO
  1194.  
  1195.