home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / ifsinf.zip / addenda next >
Text File  |  1994-12-07  |  10KB  |  269 lines
  1. We are currently updating the IFS document, but the updates are not
  2. complete at this time.  However, the following change is the most
  3. requested clarification/revision that we have received.
  4.  
  5. Mary Monahan
  6.  
  7.  
  8. FS_FINDFIRST
  9. FIND FIRST MATCHING FILE NAME(S)
  10.  
  11.  
  12. | Purpose
  13.  
  14. | Find first occurrence(s) of matching file name(s) in a directory.
  15.  
  16.  
  17.   Calling Sequence
  18.  
  19.     int far pascal FS_FINDFIRST (pcdfsi, pcdfsd, pName, iCurDirEnd,
  20.                                     attr, pfsfsi, pfsfsd,
  21.                                     pData, cbData, pcMatch, level, flags)
  22.     struct cdfsi far *    pcdfsi;
  23.     struct cdfsd far *    pcdfsd;
  24.     char far *             pName;
  25.     unsigned short    iCurDirEnd;
  26.     unsigned short          attr;
  27.     struct fsfsi far *    pfsfsi;
  28.     struct fsfsd far *    pfsfsd;
  29.     char far *             pData;
  30.     unsigned short        cbData;
  31.     unsigned short far * pcMatch;
  32.     unsigned short         level;
  33.     unsigned short         flags;
  34.  
  35.  
  36.  
  37.   Where
  38.  
  39.   PCDFSI
  40.   ______
  41.      is a pointer to the file-system-independent working directory structure.
  42.  
  43.   PCDFSD
  44.   ______
  45.      is a pointer to the file-system-dependent working directory structure.
  46.  
  47.   PNAME
  48.   _____
  49.      is a pointer to the ASCIIZ name of the file or directory.
  50.  
  51.      Wildcard characters are allowed only in the last component.  The FSD does
  52.      not need to validate this pointer.
  53.  
  54.   ICURDIREND
  55.   __________
  56.      is the index of the end of the current directory in pName.
  57.  
  58. |    This is provided to allow optimization of FSD path processing.  If
  59.      iCurDirEnd == -1 there is no current directory relevant to the name text,
  60.      that is, a device.
  61.  
  62.   ATTR
  63.   ____
  64.      is a bit field that governs the match.
  65.  
  66. |    Any directory entry whose attribute bit mask is a subset of attr and whose
  67. |    name matches that in pName should be returned.  The attr field is two byte
  68. |    sized attribute bit masks.  The least significant byte contains the "may
  69. |    have" bits.  For example,  a "may have" attribute of system and hidden is
  70. |    passed in.  A file with the same name and an attribute of system is found.
  71. |    This file is returned.  A file with the same name and no attributes (a
  72. |    regular file) is also returned.  The "may have" attributes read-only and
  73. |    file-archive will not be passed in and should be ignored when comparing
  74. |    directory attributes.  The most significant byte contains the "must have"
  75. |    bits.  A file with a matching name must also have the attributes in the
  76. |    "must have" bits to be returned.  See the OS/2 Version 3.0 Control Program
  77.                                                ________________________________
  78. |    Programming Reference for more information about the attribute field under
  79.      _____________________
  80. |    DosFindFirst.
  81.  
  82. |    The value of attr passed to the FSD will be valid.  The bit 0x0040 indi-
  83. |    cates a non-8.3 filename format.  It should be treated the same way as
  84. |    system and hidden attributes are.  You should not return a file name that
  85. |    does not conform to 8.3 filename format if this bit is not set in the "may
  86. |    have" bits.
  87.  
  88.   PFSFSI
  89.   ______
  90.      is a pointer to the file-system-independent file-search structure.
  91.  
  92.      The FSD should not update this structure.
  93.  
  94.   PFSFSD
  95.   ______
  96.      is a pointer to the file-system-dependent file-search structure.
  97.  
  98.     The FSD may use this to store information about continuation of the
  99.     search.
  100.  
  101.  PDATA
  102.  _____
  103.     is the address of the application data area.
  104.  
  105.     Addressing of this data area is not validated by the kernel (see
  106.     FSH_PROBEBUF).  The FSD will fill in this area with a set of packed,
  107.     variable-length structures that contain the requested data and matching
  108.     file name.
  109.  
  110.  CBDATA
  111.  ______
  112.     is the length of the application data area in bytes.
  113.  
  114.  PCMATCH
  115.  _______
  116.     is a pointer to the number of matching entries.
  117.  
  118.      The FSD returns, at most, this number of entries;  the FSD returns in this
  119.      parameter the number of entries actually placed in the data area.
  120.  
  121.      The FSD does not need to validate this pointer.
  122.  
  123.   LEVEL
  124.   _____
  125.      is the information level to be returned.
  126.  
  127. |    Level selects among a series of data structures to be returned (see
  128. |    below).  The level passed to the FSD is valid.
  129.  
  130.   FLAGS
  131.   _____
  132.      indicates whether to return file-position information.
  133.  
  134. |    flags == FF_NOPOS (0x00) indicates that file-position information should
  135. |              not be returned (see below).
  136. |    flags == FF_GETPOS (0x01) indicates that file-position information should
  137.                be returned and the information format described below should be
  138.                used.
  139.  
  140.      The flag passed to the FSD has a valid value.
  141.  
  142.  
  143.   Remarks
  144.  
  145.   NOTE:
  146.  
  147. | The find structure passed back to the user is the structure defined for the
  148. | 16 bit DosFindFirst API with some modification if the flags parameter is set.
  149. | The basic, level one FILEFINDBUF structure is
  150.  
  151. |   struct FileFindBuf  {
  152. |     unsigned short  dateCreate;
  153. |     unsigned short  timeCreate;
  154. |     unsigned short  dateAccess;
  155. |     unsigned short  timeAccess;
  156. |     unsigned short   dateWrite;
  157. |     unsigned short   timeWrite;
  158. |     long                 cbEOF;
  159. |     long               cbAlloc;
  160. |     unsigned short        attr;
  161. |     unsigned char       cbName;
  162. |     unsigned char     szNameY";
  163. |   }
  164.  
  165. | For flags == 1, the FSD must store in the first DWORD of the per-file attri-
  166. | butes structure adequate information that in addition with the file name will
  167. | allow the search to be resumed from the file by calling FS_FINDFROMNAME.  For
  168. | example,  an ordinal representing the file's position in the directory could
  169. | be stored.  If the filename must be used to restart the search, the DWORD may
  170. | be left blank.
  171.  
  172. | For level 0x0001 and flags == 1, directory information for FS_FINDFIRST is
  173. | returned in the following format:
  174. |   struct FileFromFindBuf  {
  175. |     long              position;  /* position given to FSD on following */
  176. |                                  /* FS_FINDFROMNAME call            */
  177. |     unsigned short  dateCreate;
  178. |     unsigned short  timeCreate;
  179. |     unsigned short  dateAccess;
  180. |     unsigned short  timeAccess;
  181. |     unsigned short   dateWrite;
  182. |     unsigned short   timeWrite;
  183. |     long                 cbEOF;
  184. |     long               cbAlloc;
  185. |     unsigned short        attr;
  186. |     unsigned char       cbName;
  187. |     unsigned char     szNameY";
  188. |   }
  189.  
  190. | The other information levels have similar format, with the position the first
  191. | field in the structure for flags == 1.  For level 0x0002 and flags == 1,
  192. | directory information for FS_FINDFIRST is returned in the following format:
  193.  
  194. |   struct FileFromFindBuf  {
  195. |     long              position;  /* this field is not present if flags */
  196. |                                  /* is 0                               */
  197. |     unsigned short  dateCreate;
  198. |     unsigned short  timeCreate;
  199. |     unsigned short  dateAccess;
  200. |     unsigned short  timeAccess;
  201. |     unsigned short   dateWrite;
  202. |     unsigned short   timeWrite;
  203. |     long                 cbEOF;
  204. |     long               cbAlloc;
  205. |     unsigned short        attr;
  206. |     unsigned long       cbList;  /* size of EAs for the file           */
  207. |     unsigned char       cbName;
  208. |     unsigned char     szNameY";
  209. |   }
  210.  
  211. | For level 0x0003 and flags == 1, the directory information for FS_FINDFIRST
  212. | is a bit more complicated.  An EAOP struction will be located at the begin-
  213. | ning of pData.  You should start filling in the data after the EAOP struc-
  214. | ture.  The data format is:
  215.  
  216. |   struct FileFromFindBuf  {
  217. |     long              position;  /* this field is not present if flags */
  218. |                                  /* is 0.                              */
  219. |     unsigned short  dateCreate;
  220. |     unsigned short  timeCreate;
  221. |     unsigned short  dateAccess;
  222. |     unsigned short  timeAccess;
  223. |     unsigned short   dateWrite;
  224. |     unsigned short   timeWrite;
  225. |     long                 cbEOF;
  226. |     long               cbAlloc;
  227. |     unsigned short        attr;
  228. |     FEALIST            fealist;  /* this is a variable length field    */
  229. |     unsigned char       cbName;
  230. |     unsigned char     szNameY";
  231. |   }
  232.  
  233. | For a description of the FEALIST structure, see "FEAs" on page 1-10.
  234.  
  235.   If the non-8.3 filename format bit is set in the attributes of a file found
  236.   by FS_FINDFIRST/NEXT/FROMNAME, it must be turned off in the copy of the
  237.   attributes returned in pData.
  238.  
  239.   If FS_FINDFIRST for a particular search returns an error, an FS_FINDCLOSE for
  240.   that search will not be issued.
  241.  
  242.   Sufficient information to find the next matching directory entry must be
  243.   saved in the fsfsd data structure.
  244.  
  245.   In the case where directory entry information overflows the pData area, the
  246.   FSD should be able to continue the search from the entry which caused the
  247.   overflow on the next FS_FINDNEXT or FS_FINDFROMNAME.
  248.  
  249.   In the case of a global search in a directory, the first two entries in that
  250.   directory as reported by the FSD should be '.' and '..' (current and the
  251.   parent directories).
  252.  
  253.   NOTE:  The FSD will be called with the FINDFIRST/FINDFROMNAME interface when
  254.   the 32-bit DosFindFirst/DosFindNext APIs are called.  THIS IS A CHANGE FROM
  255.   1.X IFS interface for redirector FSDs.  The kernel will also be massaging the
  256.   find records so that they appear the way the caller expects.  Redirectors who
  257.   have to resume searches should take this information into account.  (i.e. You
  258.   might want to reduce the size of the buffer sent to the server, so that the
  259.   position fields can be added to the beginning of all the find records).
  260.  
  261. | APPLICATION NOTE:  Some applications have been coded to expect behavior
  262. | beyond the architectural requirements.  For example, there are applications
  263. | that require DosFindFirst to return an entry for a file that has been open-
  264. | created, but which has never been closed.  You can debate whether a file
  265. | truly exists until it has been closed, but unless the applications are
  266. | changed they will still not work.  Consequently, it is recommended that FSDs
  267. | exhibit this behavior.
  268.  
  269.