FileSystemFunctions

File related functions

wbc.readTextFile

• Description: Returns the contents of a text file as a string
• Threading: Foreground/blocking
• Function: wbc.readTextFile(fileSpec)
• Arguments:
  • fileSpec: Full path and filename to the text file to be read
• Returns:
  • ERROR/INVALID
  • string representing the contents of the text file.
• Notes: None

wbc.writeTextFile

• Description: Writes the contents of a string to the specified text file.
• Threading: Foreground/blocking
• Function: writeTextFile(fileSpec, contents, encoding)
• Arguments:
  • fileSpec: full path and filename of the file to be written to.
  • contents: string representing the contents of the file
  • encoding: Optional. The text file encoding. The parameter is optional, if omitted, ANSI encoding is used. Possible encoding values are:
  • ANSI: ANSI, single-byte encoding (the default one) is used to save the textual data. No BOM (byte order mark) header is written.
  • UTF: single-byte UTF8 encoding is used to write textual data. The UTF8 BOM header is included.
  • UTF16 or UTF16LE: multi-byte UTF16 Little Endian encoding is used. The UTF16LE BOM header is included.
  • UTF16BE: multi-byte UTF16 Big Endian encoding is used. The UTF16BE BOM header is included.
• Returns:
  • OK/ERROR/INVALID
• Notes:
  • If the file does not exist, it is created.
  • If the file already exists, it is overwritten.

wbc.appendTextFile

• Description: Appends Text to the end of a file.
• Threading: Foreground/Blocking.
• Function: wbc.appendTextFile(fileSpec, contents, encoding)
• Arguments:
  • fileSpec: Filespec of the file being appended to. Environment variables are automatically expanded.
  • contents: Text to be writtent to the file.
  • encoding: Optional. If omitted the existing file encoding is used, or ANSI if no file exists. Can be one of the following:
    • 'ANSI': ANSI, single-byte encoding (the default one) is used to save the textual data. No BOM (byte order mark) header is written.
  • 'UTF8': single-byte UTF8 encoding is used to write textual data. The UTF8 BOM header is included.
  • 'UTF16' or 'UTF16LE': multi-byte UTF16 Little Endian encoding is used. The UTF16LE BOM header is included.
  • 'UTF16BE': multi-byte UTF16 Big Endian encoding is used. The UTF16BE BOM header is included.
• Returns:
  • OK: successful
  • INVALID: invalid arguments.
  • ERROR: Any other error (permissions, disk space, etc).
• Notes:
  • If the file does not exist, it is automatically created.
  • Parent folders are not automatically created. Attempting to specify a file in a nonexistent folder will result in ERROR.

wbc.readBinaryFile

• Description: Reads a local file and returns an array of bytes.
• Threading: foreground/blocking
• Function: wbc.readBinaryFile(fileSpec)
• Arguments:
  • fileSpec: Full path and file name of the file to be read.
• Returns:
  • INVALID/ERROR
  • Array of bytes representing the contents of the file.
• Notes:
  • The file name can contain expandable environment variables (expanded automatically if found), for example '%windir%\win.ini'.

wbc.writeBinaryFile

• Description: Writes an array of bytes into a file.
• Threading: Foreground/blocking
• Function: wbc.writeBinaryFile(fileSpec, byteArray)
• Arguments:
  • fileSpec: full path and filename of the file to be written to.
  • byteArray: an array of bytes that will become the file's contents.
• Returns:
  • OK/ERROR/INVALID
• Notes:
  • If the file does not exist it will be created.
  • If the file already exists it will be overwritten.

wbc.appendBinaryFile

• Description: Appends an array of bytes into a file.
• Threading: Foreground/blocking
• Function: wbc.appendBinaryFile(fileSpec, byteArray)
• Arguments:
  • fileSpec: full path and filename of the file to be written to.
  • byteArray: an array of bytes that will become the file's contents.
• Returns:
  • OK/ERROR/INVALID
• Notes:
  • If the file does not exist it will be created.
  • If the file already exists it will be appended to.

wbc.createFolder

• Description: Creates a folder, including any missing parent folders in the path.
• Threading: Foreground/Blocking.
• Function: wbc.createFolder(path)
• Arguments:
  • path: Path of folder to be created.
• Returns:
  • The original folder name if successfully created, or if it already exists.
  • An empty string if the folder could not be created for any reason.
• Notes: None

wbc.deleteFolder

• Description: Recursively delete a folder.
• Threading: Foreground/Blocking
• Function: wbc.deleteFolder(folderSpec)
• Arguments:
  • folderSpec: path of the folder to be deleted.
• Returns:
  • OK/ERROR
• Notes:
  • All files and subfolders will be deleted.
  • This function is foreground threaded. A large folder depth could take considerably time to complete, making your application unresponsive.
  • Readonly attributes will be ignored -- files and folders with readonly attributes will be deleted along with read-write files.

wbc.copyFile

• Description: Performs a background threaded file copy.
• Threading: Background with callback
• Function: copyFile(sourceFile, destFile, callback)
• Arguments:
  • sourceFile: The source file to be copied.
  • destFile: The destination of the new file.
  • callback: A bound javascript function to be called when copy is complete.
• Returns:
  • Thread ID of copy operation, INVALID, or ERROR.
• Notes:
  • This uses the Windows API to copy the file, so the entire file is copied including the file zone/ntfs stream information if applicable.
  • If the destination file already exists, it is overwritten.
  • If the destination folder doesn't exist, it is created.
  • If the destination file can not be overwritten, 'ERROR' is returned,
  • If the source file doesn't exist or is not accessible, 'ERROR' is returned.
  • The callback evt object is undocumented. Callback occurs only if the file finishes copying.

wbc.copyFileBytes

• Description: Performs a byte-by-byte copy of a file.
• Threading: Foreground/blocking.
• Function: copyFileBytes(sourceFile, destFile)
• Arguments:
  • sourceFile: The file to be copied.
  • destFile: The destination of the new file.
• Returns:
  • OK on success.
  • INVALID if the arguments are invalid.
  • Error if permissions are denied or the destination folder does not exist.
• Notes:
  • Use copyFile whenever possible for best performance, as this function is slow.
  • This function is most typically used to copy the uisdk executable from an install wizard just downloaded into program files for ongoing application usage.
  • Because it avoids copying the Zone information in the file stream, it avoids the security warning that would arise when a user tries to run a program downloaded from the Internet.
  • If the destination file already exists, it is overwritten.
  • Unlike wbc.copyFile, this does NOT first create the parent folder if not present.
  • The parent folder must already exist, or an ERROR will be returned.

wbc.renameFile

• Description: Renames or moves the specified file.
• Threading: Foreground/blocking, background.
• Function: wbc.renameFile(sourceFilespec, destFilespec)
• Arguments:
  • sourceFilespec: full path and file name of the file to be renamed or moved
  • destFilespec: full path and file name of the new name/location of the file being renamed or move.
• Returns:
  • ERROR: if the file cannot be renamed or moved for any reason.
  • INVALID: invalid arguments.
  • OK: if the file is successfully moved in not more than 1/10th of a second.
  • threadID: if the file move operation takes more than 1/10th of a second.
• Notes:
  • If the destination file already exists, it is overwritten.

wbc.deleteFile

• Description: Deletes a file from the local disk.
• Threading: Foreground/blocking
• Function: wbc.deleteFile(fileSpec)
• Arguments:
  • fileSpec: Full filespec of the file to be deleted.
• Returns:
  • OK if successful
  • ERROR if the file was not found, or access was denied.
  • INVALID if invalid arguments were passed.
• Notes: None.

wbc.enumFiles

• Description: Returns a list of all files and folders that match the search mask.
• Threading: Foreground/blocking
• Function: wbc.enumFiles(fileSpec)
• Arguments:
  • fileSpec: Full file specification of the file to be found. Can include wildcards '?' and '*' to return multiple files.
• Returns:
  • ERROR: invalid path or access denied.
  • An empty array if no folders or files are found.
  • An array of objects representing the found files. Each object can have the following properties:
    • name: the name of the file or folder
  • isDirectory: true if the item is a directory
  • size: size of the file in bytes
  • dateCreated: creation date of the file
  • dateModified: modification date
  • dateAccessed: last access date
• Notes
  • To return all file in the root of the C: drive for example, use
  • var files = wbc.enumFiles("c:\.");
  • Use this judiciously as it can take a while to enumerate a folder containing a large number of files.
  • Because this happens in the foreground, the application may become unresponsive.

wbc.fileExists

• Description: Determines whether or not a file exists in a local drive/folder.
• Threading: Foreground/immediate.
• Function: wbc.fileExists(fileSpec)
• Arguments:
  • fileSpec: Full path of the file being checked for.
• Returns:
  • true or false.
• Notes:
  • Invalid folder will return false.
  • Sufficiently restricted NTFS or share permissions may result in an erronous return of false if the file exists but cannot be accessed under the current security context.

wbc.getFileInfo

• Description: Returns information about the specified file
• Threading: Foreground/blocking
• Function: wbc.getFileInfo(fileSpec, options)
• Arguments:
  • fileSpec: A full path and fileName to the file being checked.
  • options: Optional. A string containing zero or option characters (in any order). If null is passed, ALL options are assumed ("vmsh"). The options are:
    • v: include version information.
  • m: stands for media information
  • s: signature information
  • h: for hash information
• Returns:
  • ERROR or INVALID
  • An object containing the following information.
  • General information (always returned)
    • isDirectory: true if the item is a directory. False if it is a file.
    • size: size of the file in bytes
    • dateCreated: creation date of the file
    • dateModified: modification date
    • dateAccessed: last access date
  • File version/resource information. These will be 'undefined' if not found in the file. This section only returned if the 'v' option is specified.
    • fileVersion: the file version
    • fileDescription: the file description
    • productName: product name
    • productVersion: product version
    • copyright: copyright
    • language: language of the resources
  • Media file information. This information block only available if the 'm' option is specified and the file is an image.
    • imageFormat: image file format. Can be one of the following: "JPEG", "BMP", "EMF", "WMF", "PNG", "GIF", "TIFF", "EXIF", "Icon"
    • imageWidth: image width in pixels
    • imageHeight: image height in pixels
    • imageBPP: image bits per pixel value
    • File signature information. This information block only available if the 's' option is specified:
    • signatureName: the name of the signer certificate
    • signatureTime: the time of the signature
    • signatureValid: true if the PE file is signed, and the file signature is valid. False if not signed or signature is invalid.
    • File hash. This information block only available if the 'h' option is specified:
    • sha256: the array of bytes (32 bytes) containing the SHA256 hash of the file
    • sha256Str: the string representation of the hash
• Notes:
  • Each of the four options increases the amount of time this function blocks the foreground thread. Signature information can block the thread for a noticeable time, particularly if the certificate takes time to validate.

wbc.xorFile

• Description: Performs a byte-by-byte XOR on a file.
• Threading: Foreground/blocking
• Function: xorFile(fileSpec, key)
• Arguments:
  • fileSpec: Full path and filename of the file to be transformed.
  • key: Integer. XOR mask.
• Returns:
  • OK/ERROR/INVALID
• Notes:
  • The file name can contain expandable environment variables (expanded automatically if found), such as '%windir%\win.ini'.
  • The file is transformed in place, effectively overwriting the original file.
  • If the same operation is performed twice on the same file, it is returned to its original state.

wbc.registerDirectoryChange

• Description: Monitors changes within the specified directory on a local disk.
• Threading: Foreground/immediate (with background listener thread)
• Function: wbc.registerDirectoryChange(folderSpec, callback)
• Arguments:
  • folderSpec: Full path of the folder to be monitored.
  • callback: bound JS function to be called back.
• Returns:
  • INVALID/ERROR or callback ID.
• Notes:
  • Use this with local folders only. Monitoring of folder on a network share are not supported.
  • Subtree changes are not supported without modification of wbc.js.
  • Changes monitored include renaming, creating, or deleting a file name. Other changes can be monitored, but this requires modification of wbc.js.
  • The callback evt object has the following properties:
    • func: internal function name ('uisdk_RegisterDirectoryChange')
  • changeId: the change callback identifier (as returned by the function cal)
  • directory: the watched directory
  • isWatchSubtree: isWatchSubtree value that was passed to the internal function 'uisdk_RegisterDirectoryChange'
  • notifyFilter: notifyFilter value that was passed to the internal function 'uisdk_RegisterDirectoryChange'
  • The current version of wbc.js allows for only one callback at a time:
    • If a second call to registerDirectoryChange is made with a callback, both folders will be monitored but only the last callback will be used.
  • If callback is set to null on the second call to registerDirectoryChange, the first callback will not be overwritten.

wbc.unregisterDirectoryChange

• Description: Stops monitoring a specific folder currently being monitored by a call to registerDirectoryChange
• Threading: Foreground/immediate
• Function: wbc.unregisterDirectoryChange(changeID)
• Arguments:
  • changeID: The change ID returned by the call to registerDirectoryChange
• Returns:
  • OK/ERROR/INVALID
• Notes:
  • The last callback specified in registerDirectoryChange remains in use.
  • This can be overwritten by passing a new callback to future calls to registerDirectoryChange, or retained by passing null.