Documentation for Win32lib v0.60.6
Table of Contents

File Operations

The basic File I/O routines using Windows API routines.


  • func copyFile(sequence CurrentName, sequence NewName, integer Flag)   Copies a file.
  • func createDirectory(sequence Name)   Creates a new directory
  • func deleteFile(sequence Name)   Deletes an operating system file.
  • func getCurrentDirectory()   Gets the current directory
  • func getFileInfo(object pPath, object pAttrib, object pItems)   Retrieves various properties of a file.
  • func getFullPathName(sequence File, integer Option)    Returns the path and long file name that File refers to.
  • func getPathFromIDList(atom idl)   
  • func getTempFile(object Dir, sequence Prefix)   Used to create an empty file, intended to temporary use.
  • func getTempPath()   Used to find out the directory designated for temporary files.
  • func moveFile(sequence CurrentName, sequence NewName)   Renames or Moves a file.
  • func selectDirectory(sequence title, object flags, atom callback, atom cbData)   Displays a dialog for selecting directories.
  • func setCurrentDirectory(sequence Path)   Sets the current directory
  • func setFileAttr(sequence pPath, object pAttribs)   Sets one or more attibutes for the specified file.
  • func setSearchPaths(sequence Paths)   Sets the file system paths to use when searching for files
  • func w32FileOpen(sequence Path, sequence Mode)   Search the set 'searchpaths' for the file then opens it.
  • func w32FindFile(sequence File)   Search the set 'searchpaths' for the file and returns its path specification.

    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    copyFile
    (sequence CurrentName, sequence NewName, integer Flag)

    Copies a file.

    Returns: ATOM: w32True if successful, w32False if not.

    Category: File Operations

    If Flag is w32True then it will not copy the file if the NewName already exists.

            copyFile("C:\\TEMP\\~xyz.tmp", "D:\\PROJECT\\input.txt")
    

    See Also: createDirectory, deleteFile, getCurrentDirectory, getFileInfo, getFullPathName, getPathFromIDList, getTempFile, getTempPath, moveFile, selectDirectory, setCurrentDirectory, setFileAttr, setSearchPaths, w32FileOpen, w32FindFile


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    createDirectory
    (sequence Name)

    Creates a new directory

    Returns: ATOM: w32True if successful, w32False if not.

    Category: File Operations

    Name is the name of the directory to create. If you need this routine to also create all the intervening directories, specify the Name as {w32True, Name }

          -- Create the PROJECT directory in the D: drive
          createDirectory("D:\\PROJECT")
          -- Create the 'saves' directory and 'temp' and 'temp\project'
          -- if required.
          createDirectory({w32True, "C:\\temp\\project\\saves"})
    

    See Also: copyFile, deleteFile, getCurrentDirectory, getFileInfo, getFullPathName, getPathFromIDList, getTempFile, getTempPath, moveFile, selectDirectory, setCurrentDirectory, setFileAttr, setSearchPaths, w32FileOpen, w32FindFile


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    deleteFile
    (sequence Name)

    Deletes an operating system file.

    Returns: ATOM: w32True if successful, w32False if not.

    Category: File Operations

            deleteFile("C:\\TEMP\\~xyz.tmp")
    

    See Also: copyFile, createDirectory, getCurrentDirectory, getFileInfo, getFullPathName, getPathFromIDList, getTempFile, getTempPath, moveFile, selectDirectory, setCurrentDirectory, setFileAttr, setSearchPaths, w32FileOpen, w32FindFile


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    getCurrentDirectory
    ()

    Gets the current directory

    Returns: SEQUENCE: Name of current directory path

    Category: File Operations

    Example

          sequence lPath
          lPath = getCurrentDirectory()
    

    See Also: copyFile, createDirectory, deleteFile, getFileInfo, getFullPathName, getPathFromIDList, getTempFile, getTempPath, moveFile, selectDirectory, setCurrentDirectory, setFileAttr, setSearchPaths, w32FileOpen, w32FindFile


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    getFileInfo
    (object pPath, object pAttrib, object pItems)

    Retrieves various properties of a file.

    Returns: SEQUENCE: {Name, Type, Attrib, hIcon, iIcon, ExeType, ImageList}

    Category: File Operations

    pPath is either a path name (absolute or relative) or a pointer to an ItemIDList

    The possbile values for pAttrib are ...

  • FILE_ATTRIBUTE_READONLY
  • FILE_ATTRIBUTE_HIDDEN
  • FILE_ATTRIBUTE_SYSTEM
  • FILE_ATTRIBUTE_DIRECTORY
  • FILE_ATTRIBUTE_ARCHIVE
  • FILE_ATTRIBUTE_DEVICE
  • FILE_ATTRIBUTE_NORMAL
  • FILE_ATTRIBUTE_TEMPORARY
  • FILE_ATTRIBUTE_SPARSE_FILE
  • FILE_ATTRIBUTE_REPARSE_POINT
  • FILE_ATTRIBUTE_COMPRESSED
  • FILE_ATTRIBUTE_OFFLINE
  • FILE_ATTRIBUTE_NOT_CONTENT_INDEXED
  • FILE_ATTRIBUTE_ENCRYPTED

    These are either given as a sequence or an or'd atom.

    The possbile values for Items are ...

  • SHGFI_LARGEICON -- get large icon
  • SHGFI_SMALLICON -- get small icon
  • SHGFI_OPENICON -- get open icon
  • SHGFI_SHELLICONSIZE -- get shell size icon
  • SHGFI_PIDL -- pPath is a pidl
  • SHGFI_USEFILEATTRIBUTES -- use pAttrib
  • SHGFI_ADDOVERLAYS -- apply the appropriate overlays
  • SHGFI_OVERLAYINDEX -- Get the index of the overlay
  • SHGFI_ICON -- get icon
  • SHGFI_DISPLAYNAME -- get display name
  • SHGFI_TYPENAME -- get type name
  • SHGFI_ATTRIBUTES -- get attributes
  • SHGFI_ICONLOCATION -- get icon location
  • SHGFI_EXETYPE -- return exe type
  • SHGFI_SYSICONINDEX -- get system icon index
  • SHGFI_LINKOVERLAY -- put a link overlay on icon
  • SHGFI_SELECTED -- show icon in selected state
  • SHGFI_ATTR_SPECIFIED -- get only specified attributes

    These are either given as a sequence or an or'd atom.

    This routine returns seven items in a sequence...

  • Name -- Display name of file.
  • Type -- Type of file
  • Attrib -- File's properties.
  • hIcon -- Handle to file's icon
  • iIcon -- Index into the .exe for this icon
  • ExeType -- Type of executable
  • ImageList -- Pointer to the system's image list

    Note that if you request the file's icon, you are responsible for calling destroyIcon() when you have finished with the icon.

    Examples:

        sequence Props
        Props = getFileInfo("test.bmp",
                      0,
                      w32or_all({
                            SHGFI_ICON,
                            SHGFI_DISPLAYNAME,
                            SHGFI_TYPENAME,
                            SHGFI_ATTRIBUTES
                      }
                      )
                    )
    

    The returned Attrib value is a combination of these flags...

  • SFGAO_CANCOPY
  • SFGAO_CANMOVE
  • SFGAO_CANLINK
  • SFGAO_CANRENAME
  • SFGAO_CANDELETE
  • SFGAO_HASPROPSHEET
  • SFGAO_DROPTARGET
  • SFGAO_LINK
  • SFGAO_SHARE
  • SFGAO_READONLY
  • SFGAO_GHOSTED (also known as SFGAO_HIDDEN)
  • SFGAO_FILESYSANCESTOR
  • SFGAO_FOLDER
  • SFGAO_FILESYSTEM
  • SFGAO_HASSUBFOLDER
  • SFGAO_CONTENTSMASK
  • SFGAO_VALIDATE
  • SFGAO_REMOVABLE
  • SFGAO_COMPRESSED
  • SFGAO_BROWSABLE
  • SFGAO_NONENUMERATED
  • SFGAO_NEWCONTENT
  • SFGAO_CANMONIKER

    See Also: copyFile, createDirectory, deleteFile, getCurrentDirectory, getFullPathName, getPathFromIDList, getTempFile, getTempPath, moveFile, selectDirectory, setCurrentDirectory, setFileAttr, setSearchPaths, w32FileOpen, w32FindFile


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    getFullPathName
    (sequence File, integer Option)

    Returns the path and long file name that File refers to.

    Returns: SEQUENCE: {PathName, FileName}

    Category: File Operations

    File is a reference to a file.
    Option is w32True if the file must exist, w32False if it doesn't have to exist.

    Note that the Path value returned always ends with a '/' character.

    If Option is w32True and the file does not exist, then empty strings are returned. If Option is w32False and the file does not exist then the returned Path value is prefixed with '?'.

    Example

          sequence lPaths
          lNames = getFullPathName("D:..\\demosa~1.fil")
    

    Given that the current directory for D: drive is "\windows\system" and the short name of "demosample.fil" is "demosa~1.fil" then this example would return ...
    {"D:\windows\", "demosample.fil"}

    See Also: copyFile, createDirectory, deleteFile, getCurrentDirectory, getFileInfo, getPathFromIDList, getTempFile, getTempPath, moveFile, selectDirectory, setCurrentDirectory, setFileAttr, setSearchPaths, w32FileOpen, w32FindFile


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    getPathFromIDList
    (atom idl)

    Returns: SEQUENCE: The folder name

    Category: File Operations

    desc

    See Also: copyFile, createDirectory, deleteFile, getCurrentDirectory, getFileInfo, getFullPathName, getTempFile, getTempPath, moveFile, selectDirectory, setCurrentDirectory, setFileAttr, setSearchPaths, w32FileOpen, w32FindFile


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    getTempFile
    (object Dir, sequence Prefix)

    Used to create an empty file, intended to temporary use.

    Returns: SEQUENCE: The name of the file created.

    Category: File Operations

    If Dir is a number or an empty string, the temporary directory is used.
    If Prefix is less than 3 characters long, it is padded out with underscores. Only the first three characters are used.
    The filename created has the form nnnn.TMP, where nnnn is a number used to enforce uniqueness.

            TempFilename = getTempFile(0, "my")
    

    See Also: copyFile, createDirectory, deleteFile, getCurrentDirectory, getFileInfo, getFullPathName, getPathFromIDList, getTempPath, moveFile, selectDirectory, setCurrentDirectory, setFileAttr, setSearchPaths, w32FileOpen, w32FindFile


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    getTempPath
    ()

    Used to find out the directory designated for temporary files.

    Returns: Sequence: The name of a directory. It always ends with a '\' character.

    Category: File Operations

            TempPath = getTempPath()
    

    See Also: copyFile, createDirectory, deleteFile, getCurrentDirectory, getFileInfo, getFullPathName, getPathFromIDList, getTempFile, moveFile, selectDirectory, setCurrentDirectory, setFileAttr, setSearchPaths, w32FileOpen, w32FindFile


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    moveFile
    (sequence CurrentName, sequence NewName)

    Renames or Moves a file.

    Returns: ATOM: w32True if successful, w32False if not.

    Category: File Operations

            moveFile("C:\\TEMP\\~xyz.tmp", "D:\\PROJECT\\input.txt")
    

    See Also: copyFile, createDirectory, deleteFile, getCurrentDirectory, getFileInfo, getFullPathName, getPathFromIDList, getTempFile, getTempPath, selectDirectory, setCurrentDirectory, setFileAttr, setSearchPaths, w32FileOpen, w32FindFile


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    selectDirectory
    (sequence title, object flags, atom callback, atom cbData)

    Displays a dialog for selecting directories.

    Returns: SEQUENCE: The folder name last selected. "" if dialog is cancelled.

    Category: File Operations

    title is the Title that will apear on the dialog box.
    flags

    See Also: copyFile, createDirectory, deleteFile, getCurrentDirectory, getFileInfo, getFullPathName, getPathFromIDList, getTempFile, getTempPath, moveFile, setCurrentDirectory, setFileAttr, setSearchPaths, w32FileOpen, w32FindFile


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    setCurrentDirectory
    (sequence Path)

    Sets the current directory

    Category: File Operations

    Path is the name of directory path you wish to set as the new current directory.

    Example

          -- set the new directory to current dirs parent.
          setCurrentDirectory("..")
          -- set directory to BIN folder
          setCurrentDirectory("BIN")
    

    See Also: copyFile, createDirectory, deleteFile, getCurrentDirectory, getFileInfo, getFullPathName, getPathFromIDList, getTempFile, getTempPath, moveFile, selectDirectory, setFileAttr, setSearchPaths, w32FileOpen, w32FindFile


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    setFileAttr
    (sequence pPath, object pAttribs)

    Sets one or more attibutes for the specified file.

    Category: File Operations

    ret: ATOM: 0 if this fails. pPath is a file's path and name
    pAttribs is either an atom that contains all the required attributes, or a sequence containing a list of required attrbutes.

    Examples:

          if setFileAttr("C:\\spec.fil", FILE_ATTRIBUTE_READONLY) = 0 then
              errmsg("Failed to set file to read only")
          end if
    

    See Also: copyFile, createDirectory, deleteFile, getCurrentDirectory, getFileInfo, getFullPathName, getPathFromIDList, getTempFile, getTempPath, moveFile, selectDirectory, setCurrentDirectory, setSearchPaths, w32FileOpen, w32FindFile


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    setSearchPaths
    (sequence Paths)

    Sets the file system paths to use when searching for files

    Returns: SEQUENCE: The previously set paths.

    Category: File Operations

    The initial search path is empty.
    Paths is a list of one or more directory paths, separated by either commas or semi-colons.

    These paths are used by any of the library routines that take a file name, to search for the file.

    For example: setBitmap() setIcon() loadBitmapFromFile() loadForm()

    Example:

          sequence old
          old = setSearchPaths("..\\images\\;..\\sounds\\")
    

    See Also: copyFile, createDirectory, deleteFile, getCurrentDirectory, getFileInfo, getFullPathName, getPathFromIDList, getTempFile, getTempPath, moveFile, selectDirectory, setCurrentDirectory, setFileAttr, w32FileOpen, w32FindFile


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    w32FileOpen
    (sequence Path, sequence Mode)

    Search the set 'searchpaths' for the file then opens it.

    Returns: INTEGER: File Handle.

    Category: File Operations

    This operates just like the standard open() routine except that when opening a file for reading or appending, it searchs the paths defined by setSearchPaths() for the file.

    Note 1: If the Path contains an explicit drive value (eg. C:) or the path starts with a slash, the defined search paths are not used as the library believes you are specifying a non-relative path.

    Note 2: If the Mode is set for output ("w" or "wb") then the search paths are not used.

    Example:

          VOID = setSearchPaths(".\\images\\;.\\sounds\\")
          fh1 = w32FileOpen("welcome.bmp", "r") -- looks in the search paths
          fh2 = w32FileOPen("welcome.wav", "r") -- looks in the search paths
          fh3 = w32FileOpen("C:\\autoexec.bat", "r") -- does not look in the search paths
    

    See Also: copyFile, createDirectory, deleteFile, getCurrentDirectory, getFileInfo, getFullPathName, getPathFromIDList, getTempFile, getTempPath, moveFile, selectDirectory, setCurrentDirectory, setFileAttr, setSearchPaths, w32FindFile


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    w32FindFile
    (sequence File)

    Search the set 'searchpaths' for the file and returns its path specification.

    Returns: SEQUENCE: Path name and file name.

    Category: File Operations

    This searchs the current directory and then the paths defined by setSearchPaths() for the File. If it finds the file, it returns the path-file specification.

    Example:

          VOID = setSearchPaths(".\\images\\;.\\sounds\\")
          fh1 = w32FindFile("welcome.bmp", "r") -- returns .\images\welcome.bmp
          fh2 = w32FindFile("welcome.wav", "r") -- returns .\sounds\welcome.wav
          fh3 = w32FindFile("C:\\autoexec.bat", "r") -- returns C:\\autoexec.bat
    

    See Also: copyFile, createDirectory, deleteFile, getCurrentDirectory, getFileInfo, getFullPathName, getPathFromIDList, getTempFile, getTempPath, moveFile, selectDirectory, setCurrentDirectory, setFileAttr, setSearchPaths, w32FileOpen