home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: WPS_PM / WPS_PM.zip / xfld085s.zip / helpers / dosh.h < prev    next >
C/C++ Source or Header  |  1999-03-15  |  10KB  |  311 lines
  1.  
  2. /*
  3.  * dosh.h:
  4.  *      header file for dosh.c.
  5.  *      dosh.c contains Control Program helper functions that are
  6.  *      independent of a single application, i.e. you can use them in
  7.  *      any program.
  8.  *
  9.  *      Function prefixes (new with V0.81):
  10.  *      --  dosh*   Dos (Control Program) helper functions
  11.  *
  12.  *      Copyright (C) 1997-99 Ulrich Möller.
  13.  *      This file is part of the XFolder source package.
  14.  *      XFolder is free software; you can redistribute it and/or modify
  15.  *      it under the terms of the GNU General Public License as published
  16.  *      by the Free Software Foundation, in version 2 as it comes in the
  17.  *      "COPYING" file of the XFolder main distribution.
  18.  *      This program is distributed in the hope that it will be useful,
  19.  *      but WITHOUT ANY WARRANTY; without even the implied warranty of
  20.  *      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21.  *      GNU General Public License for more details.
  22.  */
  23.  
  24. #if __cplusplus
  25. extern "C" {
  26. #endif
  27.  
  28. #ifndef DOSH_HEADER_INCLUDED
  29.     #define DOSH_HEADER_INCLUDED
  30.  
  31.     /*
  32.      * doshGetULongTime:
  33.      *      this returns the current time as a ULONG value (in milliseconds).
  34.      *      Useful for stopping how much time the machine has spent in
  35.      *      a certain function. To do this, simply call this function twice,
  36.      *      and subtract the two values, which will give you the execution
  37.      *      time in milliseconds.
  38.      */
  39.  
  40.     ULONG doshGetULongTime(VOID);
  41.  
  42.     /*
  43.      * doshQueryShiftState:
  44.      *      returns TRUE if any of the SHIFT keys are
  45.      *      currently pressed
  46.      */
  47.  
  48.     BOOL doshQueryShiftState(VOID);
  49.  
  50.     /*
  51.      * doshIsWarp4:
  52.      *      returns TRUE if at least OS/2 Warp 4 is running, FALSE otherwise
  53.      */
  54.  
  55.     BOOL doshIsWarp4(VOID);
  56.  
  57.     /*
  58.      * doshEnumDrives:
  59.      *      this copies the drive letters of the drives on the
  60.      *      system to pszBuffer which match the pszFileSystem
  61.      *      string (for example, "HPFS"); if pszFileSystem
  62.      *      is NULL, all drives are enumerated.
  63.      *      pszBuffer should be 30 characters in size.
  64.      */
  65.  
  66.     VOID doshEnumDrives(PSZ pszBuffer, PSZ pszFileSystem);
  67.  
  68.     /*
  69.      * doshQueryBootDrive:
  70.      *      returns the letter of the boot drive
  71.      */
  72.  
  73.     CHAR doshQueryBootDrive(VOID);
  74.  
  75.     /*
  76.      * doshIsFixedDisk:
  77.      *      checks whether a disk is fixed or removeable.
  78.      *      ulLogicalDrive must be 1 for drive A:, 2 for B:, ...
  79.      *      The result is stored in *pfFixed.
  80.      *      Returns DOS error code.
  81.      */
  82.  
  83.     APIRET doshIsFixedDisk(ULONG  ulLogicalDrive,        // in: 1 = A:, 2 = B:, ...
  84.                              PBOOL  pfFixed);            // out: TRUE for fixed disks
  85.  
  86.     /*
  87.      * doshAssertDrive:
  88.      *      this checks for whether the given drive
  89.      *      is currently available. If fSuppress == TRUE,
  90.      *      DosError is used in a critical section to
  91.      *      avoid "Drive not ready" popups.
  92.      */
  93.  
  94.     APIRET doshAssertDrive(ULONG ulLogicalDrive, BOOL fSuppress);
  95.  
  96.     /*
  97.      * doshQueryDiskFree:
  98.      *       returns the number of bytes remaining on the disk
  99.      *       specified by the given logical drive, or -1 upon errors.
  100.      *       Note: This returns a "double" value, because a ULONG
  101.      *       can only hold values of some 4 billion, which would
  102.      *       lead to funny results for drives > 4 GB.
  103.      */
  104.  
  105.     double doshQueryDiskFree(ULONG ulLogicalDrive); // 1 for A:, 2 for B:, 3 for C:, ...
  106.  
  107.     /*
  108.      * doshQueryDiskFSType:
  109.      *       copies the file-system type of the given disk object
  110.      *       (HPFS, FAT, CDFS etc.) fo pszBuf.
  111.      *       Returns the DOS error code.
  112.      */
  113.  
  114.     APIRET doshQueryDiskFSType(ULONG ulLogicalDrive, // in:  1 for A:, 2 for B:, 3 for C:, ...
  115.                                PSZ   pszBuf);        // out: buffer for FS type
  116.  
  117.     /*
  118.      * doshQueryDiskType:
  119.      *      this retrieves more information about a given drive,
  120.      *      which is stored in *pulDeviceType. According to the
  121.      *      IBM Control Program Reference, this value can be:
  122.      *          0  48 TPI low-density diskette drive
  123.      *          1  96 TPI high-density diskette drive
  124.      *          2  3.5-inch 720KB diskette drive
  125.      *          3  8-Inch single-density diskette drive
  126.      *          4  8-Inch double-density diskette drive
  127.      *          5  Fixed disk
  128.      *          6  Tape drive
  129.      *          7  Other (includes 1.44MB 3.5-inch diskette drive)
  130.      *          8  R/W optical disk
  131.      *          9  3.5-inch 4.0MB diskette drive (2.88MB formatted)
  132.      *      Returns DOS error code.
  133.      */
  134.  
  135.     APIRET doshQueryDiskType(ULONG  ulLogicalDrive,      // in: 1 = A:, 2 = B:, ...
  136.                              PULONG pulDeviceType);      // out: device type
  137.  
  138.     /*
  139.      * doshIsFileOnFAT:
  140.      *      returns TRUE if pszFileName resides on
  141.      *      a FAT drive
  142.      */
  143.  
  144.     BOOL doshIsFileOnFAT(PSZ pszFileName);
  145.  
  146.     /*
  147.      * doshIsValidFileName:
  148.      *      this returns NO_ERROR only if pszFile is a valid file name.
  149.      *      This may include a full path.
  150.      *      If a drive letter is specified, this checks for whether
  151.      *      that drive is a FAT drive and adjust the checks accordingly,
  152.      *      i.e. 8+3 syntax and more invalid characters.
  153.      *      If no drive letter is specified, this check is performed
  154.      *      for the current drive.
  155.      *      Note: this performs syntactic checks only. This does not
  156.      *      check for whether the specified path components exist.
  157.      *      However, it _is_ checked for whether the given drive
  158.      *      exists.
  159.      *      If an error is found, the corresponding DOS error code
  160.      *      is returned:
  161.      *          ERROR_INVALID_DRIVE
  162.      *          ERROR_FILENAME_EXCED_RANGE  (on FAT: no 8+3 filename)
  163.      *          ERROR_INVALID_NAME          (invalid character)
  164.      */
  165.  
  166.     APIRET doshIsValidFileName(PSZ pszFile);
  167.  
  168.     /*
  169.      * doshMakeRealName:
  170.      *      this copies pszSource to pszTarget, replacing
  171.      *      all characters which are not supported by file
  172.      *      systems with cReplace.
  173.      *      pszTarget must be at least the same size as pszSource.
  174.      *      If (fIsFAT), the file name will be made FAT-compliant (8+3).
  175.      *      Returns TRUE if characters were replaced.
  176.      */
  177.  
  178.     BOOL doshMakeRealName(PSZ pszTarget, PSZ pszSource, CHAR cReplace, BOOL fIsFAT);
  179.  
  180.     /*
  181.      * doshQueryFileSize:
  182.      *      returns the size of an already opened file
  183.      */
  184.  
  185.     ULONG doshQueryFileSize(HFILE hFile);
  186.  
  187.     /*
  188.      * doshQueryPathSize:
  189.      *      returns the size of any file
  190.      */
  191.  
  192.     ULONG doshQueryPathSize(PSZ pszFile);
  193.  
  194.     /*
  195.      * doshQueryDirExist:
  196.      *      returns TRUE if the given directory
  197.      *      exists.
  198.      */
  199.  
  200.     BOOL doshQueryDirExist(PSZ pszDir);
  201.  
  202.     /*
  203.      * doshCreatePath:
  204.      *      this creates the specified directory.
  205.      *      As opposed to DosCreateDir, this
  206.      *      function can create several directories
  207.      *      at the same time, if the parent
  208.      *      directories do not exist yet.
  209.      */
  210.  
  211.     APIRET doshCreatePath(PSZ pszPath);
  212.  
  213.     /*
  214.      * doshSetCurrentDir:
  215.      *      sets the current working directory
  216.      *      to the given path.
  217.      *      As opposed to DosSetCurrentDir, this
  218.      *      one will change the current drive
  219.      *      also, if one is specified.
  220.      */
  221.  
  222.     APIRET doshSetCurrentDir(PSZ pszDir);
  223.  
  224.     /*
  225.      * doshReadTextFile:
  226.      *      reads a text file from disk, allocates memory
  227.      *      via malloc() and returns a pointer to this
  228.      *      buffer (or NULL upon errors). Specify in
  229.      *      ulExtraMemory how much extra memory (in addition
  230.      *      to the file's size) should be allocated to
  231.      *      allow text manipulation.
  232.      *      Returns NULL if an error occured.
  233.      */
  234.  
  235.     PSZ doshReadTextFile(PSZ pszFile, ULONG ulExtraMemory);
  236.  
  237.     /*
  238.      * doshCreateBackupFileName:
  239.      *      creates a valid backup filename of pszExisting
  240.      *      with a numerical file name extension which does
  241.      *      not exist in the directory where pszExisting
  242.      *      resides.
  243.      *      Returns a PSZ to a buffer which was allocated
  244.      *      using malloc().
  245.      */
  246.  
  247.     PSZ doshCreateBackupFileName(PSZ pszExisting);
  248.  
  249.     /*
  250.      * doshWriteTextFile:
  251.      *      writes a text file to disk; pszFile must contain the
  252.      *      whole path and filename.
  253.      *      An existing file will be backed up if (fBackup).
  254.      *      Returns the number of bytes written.
  255.      */
  256.  
  257.     ULONG doshWriteTextFile(PSZ pszFile, PSZ pszContent, BOOL fBackup);
  258.  
  259.     /*
  260.      * doshOpenLogFile:
  261.      *      this opens a log file in the root directory of
  262.      *      the boot drive; it is titled pszFilename, and
  263.      *      the file handle is returned.
  264.      */
  265.  
  266.     HFILE doshOpenLogFile(PSZ pszFileName);
  267.  
  268.     /*
  269.      * doshWriteToLogFile
  270.      *      writes a string to a log file.
  271.      */
  272.  
  273.     APIRET doshWriteToLogFile(HFILE hfLog, PSZ psz);
  274.  
  275.     /*
  276.      * doshQuickStartSession:
  277.      *      shortcut to DosStartSession w/out having to deal
  278.      *      with all the parameters. This one starts a session
  279.      *      as a child session and can optionally wait for the
  280.      *      session to end (using a termination queue), if
  281.      *      Wait == TRUE; otherwise, this function returns
  282.      *      immediately.
  283.      */
  284.  
  285.     APIRET doshQuickStartSession(PSZ pszPath,     // in: program to start
  286.                                  PSZ pszParams,   // in: parameters for program
  287.                                  BOOL Visible,    // in: show program?
  288.                                  BOOL Wait,       // in: wait for termination?
  289.                                  PULONG pulSID,   // out: session ID
  290.                                  PPID ppid);      // out: process ID
  291.  
  292.     /*
  293.      * doshSetPathAttr:
  294.      *      sets the file attributes of pszFile,
  295.      *      which must be fully qualified.
  296.      *      fAttr can be:
  297.      *              FILE_ARCHIVED
  298.      *              FILE_READONLY
  299.      *              FILE_SYSTEM
  300.      *              FILE_HIDDEN
  301.      */
  302.  
  303.     APIRET doshSetPathAttr(PSZ pszFile, ULONG fAttr);
  304.  
  305. #endif
  306.  
  307. #if __cplusplus
  308. }
  309. #endif
  310.  
  311.