home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 1998 May / Pcwk5b98.iso / WEBSERVE / PI3 / PI3WEB.EXE / DEVEL / INCLUDE / PIFInfo.h < prev    next >
C/C++ Source or Header  |  1997-10-19  |  19KB  |  607 lines
  1. /*____________________________________________________________________________*\
  2.  *
  3.  
  4.  Copyright (c) 1997 John Roy. All rights reserved.
  5.  
  6.  These sources, libraries and applications are
  7.  FREE FOR COMMERCIAL AND NON-COMMERCIAL USE
  8.  as long as the following conditions are adhered to.
  9.  
  10.  Redistribution and use in source and binary forms, with or without
  11.  modification, are permitted provided that the following conditions
  12.  are met:
  13.  
  14.  1. Redistributions of source code must retain the above copyright
  15.     notice, this list of conditions and the following disclaimer. 
  16.  
  17.  2. Redistributions in binary form must reproduce the above copyright
  18.     notice, this list of conditions and the following disclaimer in
  19.     the documentation and/or other materials provided with the
  20.     distribution.
  21.  
  22.  3. Redistributions of any form whatsoever and all advertising materials 
  23.     mentioning features must contain the following
  24.     acknowledgment:
  25.     "This product includes software developed by John Roy
  26.     (http://www.johnroy.com/pi3/)."
  27.  
  28.  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  29.  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  30.  OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  31.  IN NO EVENT SHALL THE AUTHORS OR ITS CONTRIBUTORS BE LIABLE FOR ANY
  32.  DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  33.  DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
  34.  GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  35.  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  36.  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  37.  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  38.  OF THE POSSIBILITY OF SUCH DAMAGE.
  39.  
  40.  *____________________________________________________________________________*|
  41.  *
  42.  * $Source: PIFInfo.h$
  43.  * $Date: Sun Aug 10 06:29:35 1997$
  44.  *
  45.  Description:
  46. \*____________________________________________________________________________*/
  47. /* $HeaderTop:$ */
  48.  
  49. #ifndef PIFINFO_H_
  50. #define PIFINFO_H_
  51.  
  52. #include "PiAPI.h"
  53.  
  54. /*____________________________________________________________________________*\
  55.  *
  56.  Typedefs:
  57. \*____________________________________________________________________________*/
  58. typedef struct FileSystemEntity PIFInfo;
  59. #define PIPLATFORM_FSIZE unsigned long
  60.  
  61. /*____________________________________________________________________________*\
  62.  *
  63.  Name:
  64.     PIFInfo_new
  65.  
  66.  Synopsis:
  67.     PIFInfo *PIFInfo_new( const char *pPath )
  68.  
  69.  Description:
  70.     Create a new file information object.
  71.  
  72.  Notes:
  73.     This object should be deleted with PIFInfo_delete() when it is
  74.     no longer needed.
  75.  
  76.  Return Values:
  77.     On success PIFInfo_new() return a pointer to a new PIFInfo object.
  78.  
  79.  Errors:
  80.     NULL will be returned if an pPath is NULL or memory could not be 
  81.     allocated for the new PIFInfo object.
  82.     
  83.     More specific error information can be retrieved using
  84.     PIPlatform_getLastError().
  85.         
  86.  See Also:
  87.     PIFInfo_delete().
  88. \*____________________________________________________________________________*/
  89. PUBLIC_PIAPI PIFInfo *PIFInfo_new( const char *pPath );
  90.  
  91. /*____________________________________________________________________________*\
  92.  *
  93.  Name:
  94.     PIFInfo_delete
  95.  
  96.  Synopsis:
  97.     int PIFInfo_delete( PIFInfo *pFileInfo );
  98.  
  99.  Description:
  100.     Destroys an PIFInfo object and free any memory associated with it.
  101.  
  102.  Notes:
  103.     Using pFileInfo for any further operations after PIFInfo_delete()
  104.     has been used will cause undefined behaviour.
  105.     
  106.  Return Values:
  107.     On success PIFInfo_delete() returns zero (PIAPI_COMPLETED).
  108.  
  109.  Errors:
  110.     On error PIFInfo_delete() will return a non-zero value. The function
  111.     PIPlatform_getLastError() can be used to retreve more specific error
  112.     information.
  113.  
  114.  See Also:
  115.     PIFInfo_new().
  116. \*____________________________________________________________________________*/
  117. PUBLIC_PIAPI int PIFInfo_delete( PIFInfo *pFileInfo );
  118.  
  119. /*____________________________________________________________________________*\
  120.  *
  121.  Name:
  122.     PIFInfo_exists
  123.  
  124.  Synopsis:
  125.     int PIFInfo_exists( PIFInfo *pFileInfo )
  126.  
  127.  Description:
  128.     Specifies whether or not the file information object pFileInfo
  129.     refers to a file that actually exists.
  130.     
  131.  Notes:
  132.     Always compare this return code against PIAPI_TRUE as some
  133.     error return value may be non-negative.
  134.  
  135.  Return Values:
  136.     On success PIFInfo_exists() returns either PIAPI_TRUE or
  137.     PIAPI_FALSE, indicating whether or not a file respresented by
  138.     pFileInfo exists.
  139.  
  140.  Errors:
  141.     This function does not generate an error.
  142.         
  143.  See Also:
  144.     PIFInfo_isRegular(), PIFInfo_isReadable(),
  145.     PIFInfo_isDirectory(), PIFInfo_isLink().
  146. \*____________________________________________________________________________*/
  147. PUBLIC_PIAPI int PIFInfo_exists( PIFInfo *pFileInfo );
  148.  
  149. /*____________________________________________________________________________*\
  150.  *
  151.  Name:
  152.     PIFInfo_getName
  153.  
  154.  Synopsis:
  155.     const char *PIFInfo_getName( PIFInfo *pFileInfo )
  156.  
  157.  Description:
  158.     Returns the name of the file referred to by pFileInfo.
  159.     
  160.  Notes:
  161.  Return Values:
  162.     On sucess PIFInfo_getName() returns a non-NULL pointer to
  163.     the filename.
  164.  
  165.  Errors:
  166.     On error PIFInfo_getName() returns NULL. The function
  167.     PIPlatform_getLastError() can be used to retrieve more specific
  168.     error information.
  169.  
  170.  See Also:
  171.     PIFInfo_getPath()
  172. \*____________________________________________________________________________*/
  173. PUBLIC_PIAPI const char *PIFInfo_getName( PIFInfo *pFileInfo );
  174.  
  175. /*____________________________________________________________________________*\
  176.  *
  177.  Name:
  178.     PIFInfo_getAlternateName
  179.  
  180.  Synopsis:
  181.     const char *PIFInfo_getAlternateName( PIFInfo *pFileInfo )
  182.  
  183.  Description:
  184.     Returns the alternet name of the file referred to by pFileInfo.
  185.     
  186.  Notes:
  187.     Some operating systems maintain alternate filenames for files. This        function can be used to access the alternate filename. When the
  188.     operating system does not define an alternate file 
  189.     PIFInfo_getAlternateName() behaves as PIFInfo_getName().
  190.  
  191.  Return Values:
  192.     On sucess PIFInfo_getAlternateName() returns a non-NULL pointer to
  193.     the alternate filename.
  194.  
  195.  Errors:
  196.     On error PIFInfo_getAlternateName() returns NULL. The function
  197.     PIPlatform_getLastError() can be used to retrieve more specific
  198.     error information.
  199.  
  200.  See Also:
  201.     PIFInfo_getPath()
  202. \*____________________________________________________________________________*/
  203. PUBLIC_PIAPI const char *PIFInfo_getAlternateName( PIFInfo *pFileInfo );
  204.  
  205. /*____________________________________________________________________________*\
  206.  *
  207.  Name:
  208.     PIFInfo_getPath
  209.  
  210.  Synopsis:
  211.     const char *PIFInfo_getPath( PIFInfo *pFileInfo )
  212.  
  213.  Description:
  214.     Returns the full path to the file referred to by pFileInfo.
  215.     
  216.  Notes:
  217.  Return Values:
  218.     On sucess PIFInfo_getPath() returns a non-NULL pointer to
  219.     the files path.
  220.  
  221.  Errors:
  222.     On error PIFInfo_getPath() returns NULL. The function
  223.     PIPlatform_getLastError() can be used to retrieve more specific
  224.     error information.
  225.  
  226.  See Also:
  227.     PIFInfo_getName()
  228. \*____________________________________________________________________________*/
  229. PUBLIC_PIAPI const char *PIFInfo_getPath( PIFInfo *pFileInfo );
  230.  
  231. /*____________________________________________________________________________*\
  232.  *
  233.  Name:
  234.     PIFInfo_getPathRoot
  235.  
  236.  Synopsis:
  237.     const char *PIFInfo_getPathRoot( PIFInfo *pFileInfo )
  238.  
  239.  Description:
  240.     Returns the file path to the directory containing the file     
  241.     referred to by pFileInfo.
  242.     
  243.  Notes:
  244.  Return Values:
  245.     On sucess PIFInfo_getPathRoot() returns a non-NULL pointer.
  246.  
  247.  Errors:
  248.     On error PIFInfo_getPathRoot() returns NULL. The function
  249.     PIPlatform_getLastError() can be used to retrieve more specific
  250.     error information.
  251.  
  252.  See Also:
  253.     PIFInfo_getPathRoot()
  254. \*____________________________________________________________________________*/
  255. PUBLIC_PIAPI const char *PIFInfo_getPathRoot( PIFInfo *pFileInfo );
  256.  
  257. /*____________________________________________________________________________*\
  258.  *
  259.  Name:
  260.     PIFInfo_isRegular
  261.  
  262.  Synopsis:
  263.     int PIFInfo_isRegular( PIFInfo *pFileInfo )
  264.  
  265.  Description:
  266.     Specifies whether or not the file information object pFileInfo
  267.     refers to a file that is a regular file. 
  268.     
  269.  Notes:
  270.     Directories and symbolic links are some of the valid PIFInfo 
  271.     objects that are not regular files.
  272.  
  273.  Return Values:
  274.     On success PIFInfo_isRegular() returns either PIAPI_TRUE or
  275.     PIAPI_FALSE, indicating whether or not a file respresented by
  276.     pFileInfo is a regular file.
  277.  
  278.  Errors:
  279.     This function does not generate an error.
  280.  
  281.  See Also:
  282.     PIFInfo_exists(), PIFInfo_isReadable(),
  283.     PIFInfo_isDirectory(), PIFInfo_isLink().
  284. \*____________________________________________________________________________*/
  285. PUBLIC_PIAPI int PIFInfo_isRegular( PIFInfo *pFileInfo );
  286.  
  287. /*____________________________________________________________________________*\
  288.  *
  289.  Name:
  290.     PIFInfo_isDirectory
  291.  
  292.  Synopsis:
  293.     int PIFInfo_isDirectory( PIFInfo *pFileInfo )
  294.  
  295.  Description:
  296.     Specifies whether or not the file information object pFileInfo
  297.     refers to a directory.
  298.     
  299.  Notes:
  300.  
  301.  Return Values:
  302.     On success PIFInfo_isDirectory() returns either PIAPI_TRUE or
  303.     PIAPI_FALSE, indicating whether or not a file respresented by
  304.     pFileInfo is a directory.
  305.  
  306.  Errors:
  307.     This function does not generate an error.
  308.  
  309.  See Also:
  310.     PIFInfo_exists(), PIFInfo_isRegular(), PIFInfo_isReadable(),
  311.     PIFInfo_isLink().
  312. \*____________________________________________________________________________*/
  313. PUBLIC_PIAPI int PIFInfo_isDirectory( PIFInfo *pFileInfo );
  314.  
  315. /*____________________________________________________________________________*\
  316.  *
  317.  Name:
  318.     PIFInfo_isLink
  319.  
  320.  Synopsis:
  321.     int PIFInfo_isLink( PIFInfo *pFileInfo )
  322.  
  323.  Description:
  324.     Specifies whether or not the file information object pFileInfo
  325.     refers to a symbolic link.
  326.     
  327.  Notes:
  328.  
  329.  Return Values:
  330.     On success PIFInfo_isLink() returns either PIAPI_TRUE or
  331.     PIAPI_FALSE, indicating whether or not a file respresented by
  332.     pFileInfo is a symbolic link.
  333.  
  334.  Errors:
  335.     This function does not generate an error.
  336.  
  337.  See Also:
  338.     PIFInfo_exists(), PIFInfo_isRegular(), PIFInfo_isReadable(),
  339.     PIFInfo_isDirectory().
  340. \*____________________________________________________________________________*/
  341. PUBLIC_PIAPI int PIFInfo_isLink( PIFInfo *pFileInfo );
  342.  
  343. /*____________________________________________________________________________*\
  344.  *
  345.  Name:
  346.     PIFInfo_isReadable
  347.  
  348.  Synopsis:
  349.     int PIFInfo_isReadable( PIFInfo *pFileInfo )
  350.  
  351.  Description:
  352.     Specifies whether or not the file information object pFileInfo
  353.     refers to a file that may be opened for reading.
  354.     
  355.  Notes:
  356.     The readibility of a file is effected by its permissions, the
  357.     user privilages of the executing program and the exclusive lock
  358.     status of the file.
  359.  
  360.  Return Values:
  361.     On success PIFInfo_isReadable() returns either PIAPI_TRUE or
  362.     PIAPI_FALSE, indicating whether or not a file respresented by
  363.     pFileInfo may be opened for reading.
  364.  
  365.  Errors:
  366.     This function does not generate an error.
  367.  
  368.  See Also:
  369.     PIFInfo_exists(), PIFInfo_isRegular(), PIFInfo_isExecutable(),
  370.     PIFInfo_isWritable(), PIFInfo_isDirectory(), PIFInfo_isLink().
  371. \*____________________________________________________________________________*/
  372. PUBLIC_PIAPI int PIFInfo_isReadable( PIFInfo *pFileInfo );
  373.  
  374. /*____________________________________________________________________________*\
  375.  *
  376.  Name:
  377.     PIFInfo_isWritable
  378.  
  379.  Synopsis:
  380.     int PIFInfo_isWritable( PIFInfo *pFileInfo )
  381.  
  382.  Description:
  383.     Specifies whether or not the file information object pFileInfo
  384.     refers to a file that may be opened for writting.
  385.     
  386.  Notes:
  387.     The readibility of a file is effected by its permissions, the
  388.     user privilages of the executing program and the types of locks
  389.     held on the file.
  390.  
  391.  Return Values:
  392.     On success PIFInfo_isWritable() returns either PIAPI_TRUE or
  393.     PIAPI_FALSE, indicating whether or not a file respresented by
  394.     pFileInfo may be opened for writting.
  395.  
  396.  Errors:
  397.     This function does not generate an error.
  398.  
  399.  See Also:
  400.     PIFInfo_exists(), PIFInfo_isRegular(), PIFInfo_isReadable(),
  401.     PIFInfo_isExecutable(), PIFInfo_isDirectory(), PIFInfo_isLink().
  402. \*____________________________________________________________________________*/
  403. PUBLIC_PIAPI int PIFInfo_isWritable( PIFInfo *pFileInfo );
  404.  
  405. /*____________________________________________________________________________*\
  406.  *
  407.  Name:
  408.     PIFInfo_isExecutable
  409.  
  410.  Synopsis:
  411.     int PIFInfo_isExecutable( PIFInfo *pFileInfo )
  412.  
  413.  Description:
  414.     Specifies whether or not the file information object pFileInfo
  415.     refers to a file that may be executed as a program.
  416.     
  417.  Notes:
  418.     The execute status of a file is effected by its permissions, the
  419.     user privilages of the executing program and the exclusive lock
  420.     status of the file.
  421.  
  422.  Return Values:
  423.     On success PIFInfo_isExecutable() returns either PIAPI_TRUE or
  424.     PIAPI_FALSE, indicating whether or not a file respresented by
  425.     pFileInfo may be executed.
  426.  
  427.  Errors:
  428.     This function does not generate an error.
  429.  
  430.  See Also:
  431.     PIFInfo_exists(), PIFInfo_isRegular(), PIFInfo_isReadable(),
  432.     PIFInfo_isWritable(), PIFInfo_isDirectory(), PIFInfo_isLink().
  433. \*____________________________________________________________________________*/
  434. PUBLIC_PIAPI int PIFInfo_isExecutable( PIFInfo *pFileInfo );
  435.  
  436. /*____________________________________________________________________________*\
  437.  *
  438.  Name:
  439.     PIFInfo_getSize
  440.  
  441.  Synopsis:
  442.     PIPLATFORM_FSIZE PIFInfo_getFile( PIFInfo *pFileInfo )
  443.  
  444.  Description:
  445.     Specifies the size of the file represented by file information
  446.     object pFileInfo.
  447.     
  448.  Notes:
  449.     PIPlatform_getLastError() must be used to distinguish an error
  450.     condition from a zero length file.
  451.  
  452.  Return Values:
  453.     On success PIFInfo_getFile() returns the file size. On failure
  454.     PIFInfo_getFile() returns 0.
  455.  
  456.  Errors:
  457.     PIPlatform_getLastError() can be examined to distinguish an error
  458.     condition from a zero byte file. PIFInfo_getSize() will set the
  459.     thread specific error code to PIAPI_COMPLETED before attempting to
  460.     get the file size. If PIPlatform_getLastError() returns 0
  461.     (PIAPI_COMPLETED) then no error occured. See 'Errors' for a full
  462.     description of possible errors.
  463.  
  464.  See Also:
  465.     PIFInfo_getExtension().
  466. \*____________________________________________________________________________*/
  467. PUBLIC_PIAPI PIPLATFORM_FSIZE PIFInfo_getSize( PIFInfo *pFileInfo );
  468.  
  469. /*____________________________________________________________________________*\
  470.  *
  471.  Name:
  472.     PIFInfo_getLastModified
  473.  
  474.  Synopsis:
  475.     PIPLATFORM_TIME PIFInfo_getLastModified( PIFInfo *pFileInfo )
  476.  
  477.  Description:
  478.     Gives the time of the last modification to the file specified
  479.     by pFileInfo.
  480.     
  481.  Notes:
  482.     Time is measured in seconds elapsed since 00:00:00 UTC, Jan. 1, 1970.
  483.  
  484.  Return Values:
  485.     On success PIFInfo_getFile() returns the time of the last modification
  486.     to the file pFileInfo. On error PIFInfo_getLastModified() returns 0.
  487.  
  488.  Errors:
  489.     PIPlatform_getLastError() can be examined to distinguish an error
  490.     condition from a file which was last modified at exactly
  491.     00:00:00 UTC, Jan. 1, 1970.
  492.  
  493.  See Also:
  494. \*____________________________________________________________________________*/
  495. PUBLIC_PIAPI PIPLATFORM_TIME PIFInfo_getLastModified( PIFInfo *pFileInfo );
  496.  
  497. /*____________________________________________________________________________*\
  498.  *
  499.  Name:
  500.     PIFInfo_getExtension
  501.  
  502.  Synopsis:
  503.     const char *PIFInfo_getExtension( PIFInfo *pFileInfo )
  504.  
  505.  Description:
  506.     Returns the extension of the file represented by pFileInfo.
  507.     A file extension is the sequence of characters following the
  508.     last period ('.') in the filename, when scanning left to right.
  509.     
  510.  Notes:
  511.     PIFInfo_getExtension() may operate correctly even when pFileInfo    
  512.     does not represent a real file.
  513.  
  514.     The returned value is a pointer to a component of the filename
  515.     as represented internally in the PIFInfo object. Some functions
  516.     such as PIFInfo_delete() will cause this pointer to become
  517.     invalid.
  518.  
  519.  Return Values:
  520.     On success PIFInfo_getExtension() returns the extension of the
  521.     file. If the file does not have an extension this will be 
  522.     the empty string ("").
  523.  
  524.  Errors:
  525.     If pFileInfo is NULL an error occurs PIFInfo_getExtension() returns
  526.     NULL.
  527.  
  528.     More specific error information can be retrieved using
  529.     PIPlatform_getLastError().
  530.  
  531.  See Also:
  532.     PIFInfo_getPath().
  533. \*____________________________________________________________________________*/
  534. PUBLIC_PIAPI const char *PIFInfo_getExtension( PIFInfo *pFileInfo );
  535.  
  536. /*____________________________________________________________________________*\
  537.  *
  538.  Name:
  539.     PIFInfo_getFirstFileInDirectory
  540.  
  541.  Synopsis:
  542.     PIFInfo *PIFInfo_getFirstFileInDirectory( PIFInfo *pFileInfo )
  543.  
  544.  Description:
  545.     Returns a new PIFInfo object which contains information about the
  546.     first file in the directory referred to by pFileInfo. This object
  547.     can be used in subsequent calls to PIFInfo_getNextFileInDirectory() to
  548.     iterate through all files in a directory.
  549.     
  550.  Notes:
  551.     PIFInfo_getFirstFileInDirectory() allocates a new PIFInfo object,
  552.     distinct from pFileInfo which must be seperately destroyed using
  553.     PIFInfo_delete().
  554.  
  555.  Return Values:
  556.     On success PIFInfo_getFirstFileInDirectory() returns a non-NULL pointer
  557.     to a valid PIFInfo object.
  558.  
  559.  Errors:
  560.     On error PIFInfo_getFirstFileInDirectory() returns NULL and
  561.     PIPlatform_getLastError() can be used to retrieve an error code
  562.     indicating the reason for the failure.
  563.  
  564.  See Also:
  565.     PIFInfo_getNextFileInDirectory().
  566. \*____________________________________________________________________________*/
  567. PUBLIC_PIAPI PIFInfo *PIFInfo_getFirstFileInDirectory( PIFInfo *pFileInfo );
  568.  
  569. /*____________________________________________________________________________*\
  570.  *
  571.  Name:
  572.     PIFInfo_getNextFileInDirectory
  573.  
  574.  Synopsis:
  575.     int PIFInfo_getNextFileInDirectory( PIFInfo *pFileInfo )
  576.  
  577.  Description:
  578.     Makes pFileInfo point to the next file in the directory. The object
  579.     referred to by pFileInfo must have been created with a call to
  580.     PIFInfo_getFirstFileInDirectory().
  581.  
  582.  Notes:
  583.     If pFileInfo refers the last file in the directory,
  584.     PIFInfo_getNextFileInDirectory() returns PIAPI_FALSE and pFileInfo
  585.     does no refer to a valid file.
  586.  
  587.  Return Values:
  588.     On success PIFInfo_getNextFileInDirectory() returns PIAPI_TRUE and
  589.     pFileInfo points to the next file in the directory. If there
  590.     are no other files in the directory or an error occurs 
  591.     PIFInfo_getNextFileInDirectory() returns PIAPI_FALSE.
  592.     The object pFileInfo should be destroy using PIFInfo_delete() when
  593.     it is no longer needed.
  594.  
  595.  Errors:
  596.     On error PIFInfo_getNextFileInDirectory() returns PIAPI_FALSE and
  597.     PIPlatform_getLastError() returns a value other than
  598.     PIAPI_COMPLETED indicating which error occurred.
  599.  
  600.  See Also:
  601.     PIFInfo_getFirstFileInDirectory()
  602. \*____________________________________________________________________________*/
  603. PUBLIC_PIAPI int PIFInfo_getNextFileInDirectory( PIFInfo *pFileInfo );
  604.  
  605. #endif /* PIFINFO_H_ */
  606.  
  607.