overwolf.io API

Check whether a certain file exists and/or to write content into files.

tip

For app-related I/O functionalities, use the overwolf.extensions.io API. In addition, the simple I/O plugin offers several more general I/O features that are not available through the APIs.

Methods Reference

• overwolf.io.fileExists()
• overwolf.io.writeFileContents()
• overwolf.io.readFileContents()
• overwolf.io.copyFile()
• overwolf.io.dir()
• overwolf.io.readBinaryFile()
• overwolf.io.readTextFile()
• overwolf.io.exist()
• overwolf.io.listenOnFile()
• overwolf.io.stopFileListener()
• overwolf.io.watchFile()
• overwolf.io.stopWatchingFile()

Types Reference

• overwolf.io.enums.eEncoding enum
• overwolf.io.enums.encoding enum
• overwolf.io.enums.fileListenerState enum
• overwolf.io.ReadFileOptions Object
• overwolf.io.ListenFileOptions Object
• overwolf.io.DirResult Object
• overwolf.io.FileExistsResult Object
• overwolf.io.ReadFileContentsResult Object
• overwolf.io.ListenOnFileResult Object
• overwolf.io.WatchedFileChanged Object
• overwolf.io.enums.WatchEventType enum
• overwolf.io.ExistsResult Object
• overwolf.io.ReadBinaryFileResult Object
• overwolf.io.ReadTextFileResult Object
• overwolf.io.FileInfo Object
• overwolf.io.FileInDir Object

Sample app

In our APIs sample apps repository, you can find and download a sample app that demonstrates the usage in the IO API:

• The io-sample - Demonstrates how to open and load a file to your app, Display it, Add some content, and Write it back to the file.

It's a great place to get started - All the samples in this repository are built with JS code and demonstrate primary usage in the API.

fileExists(filePath, callback)

Version added: 0.93

Checks for the existence of a file in a given path.

Parameter	Type	Description
filePath	string	Path to check for
callback	function	Returns the result
callback	(Result: FileExistsResult) => void	Returns with the result

writeFileContents(filePath, content, encoding, triggerUacIfRequired, callback)

Version added: 0.93

Permissions required: FileSystem

Writes content into a target text file.

If the file doesn’t exist, it will be created, along with any required directories along the path. Otherwise, the file’s content will be overwritten.

Parameter	Type	Description
filePath	string	Path to check for
content	string	Content to write
encoding	eEncoding enum	Encoding to use
triggerUacIfRequired	bool	If additional permissions are required, triggers the Windows UAC dialog
callback	(Result) => void	Returns with the result

readFileContents(filePath, encoding, callback)

Version added: 0.93

Permissions required: FileSystem

Returns a string with the targeted text file’s content.

Parameter	Type	Description
filePath	string	Full path of the targeted file
encoding	eEncoding enum	Encoding to use
callback	(Result: ReadFileContentsResult) => void	Returns the result

copyFile(src, dst, overrideFile, reserved, callback)

Version added: 0.93

Permissions required: FileSystem

Copy a file from the local extension directory to a destination in the local machine.

Parameter	Type	Description
src	string	A relative file path from your extension's root folder, or a full overwolf-extension:// URI to the source file
dst	string	Destination absolute path to copy to including filename. See usage example below
overrideFile	bool	"true" if you want an existing file to be overwritten, "false" otherwise
reserved	bool	For future use
callback	(Result) => void	Returns with the result

Usage example

overwolf.io.copyFile("Fortnite Battle Royale 03-19-2020 14-10-18-457.mp4","C:/Users/Hal9000/AppData/Local/Overwolf/Extensions/nhmkaollkcmjiecdnnjmgfifjgkfegkljnjjbipp/1.0.18/copy.mp4",false,false,console.log)

dir(path, callback)

Version added: 0.141

Permissions required: FileSystem

Lists all files and folder in the target path.

Parameter	Type	Description
path	string	The target path
callback	(Result: DirResult) => void	Returns with the result

Usage example

overwolf.io.dir("C:/Users/Hal9000/Videos/Overwolf",console.log)

readBinaryFile(path, options, callback)

Version added: 0.141

Permissions required: FileSystem

Read binary file.

Reads a file's contents and returns an array of byte values.
This function is extremely slow! Use it only for small files or to get file header info using the options parameter (maxBytesToRead) to limit the amount of data to fetch.

Parameter	Type	Description
path	string	The target path
options	ReadFileOptions object
callback	(Result: ReadBinaryFileResult) => void	Returns with the result

readTextFile(path, options, callback)

Version added: 0.141

Permissions required: FileSystem

Read text file.

Reads a file's contents and returns it as text.

Parameter	Type	Description
path	string	The target path
options	ReadFileOptions object
callback	(Result: ReadTextFileResult) => void	Returns with the result

exist(path, callback)

Version added: 0.141

Permissions required: FileSystem

Is path exist.

Parameter	Type	Description
path	string	The target path
callback	(Result: ExistsResult) => void	Returns with the result

listenOnFile(id, path, option, callback)

Version added: 0.141

Permissions required: FileSystem

Start listening on file.

Stream a file (text files only), line-by-line, from the local filesystem.

Parameter	Type	Description
id	string	listen Id
path	string	file path
options	ListenFileOptions Object
callback	(Result: ListenOnFileResult) => void	Returns with the result

Usage example

overwolf.io.listenOnFile('test.txt','C:\\test\\test.txt', {},console.log)

stopFileListener(id)

Version added: 0.141

Permissions required: FileSystem

Stop listening on file.

Stop streaming a file that you previously passed when calling listenOnFile.
There are no callbacks - as this will never fail (even if the stream doesn't exist).

Parameter	Type	Description
id	string	listen Id

stopFileListener notes

On stop, listenOnFile callback will trigger with a "truncated" state:

{
    "success" : true, 
    "error": "", 
    "state": "truncated" 
    ...
}

watchFile(filePath, callback)

Version added: 0.208

Watches a file for any changes that occur to its content.

Parameter	Type	Description
filePath	string	Path to the file to watch
callback	(Result: WatchedFileChanged) => void	Callback that is called upon registering, and on every subsequent file change

Note

File changes will be listened to forever, unless:

• The file is renamed/deleted. In which case, the listener will be notified of the change, and will then stop.
• File watching on this file is closed, via overwolf.io.stopWatchingFile()

stopWatchingFile(filePath, callback)

Version added: 0.208

Stops watching the specified file

Parameter	Type	Description
filePath	string	Path to the file to stop watching
callback	(Reuslt) => void	Callback that is called with the result of the stop operation

fileListenerState enum

File listener state.

Options
started
running
terminated
truncated

encoding enum

encoding types.

Options
Default
UTF8
UTF32
Unicode
UTF7
ASCII
BigEndianUnicode

eEncoding enum

File encoding.

Options
UTF8
UTF8BOM
Unicode
UnicodeBOM
ASCII

ReadFileOptions Object

Version added: 0.141

Describes the different options to read a file.

Parameter	Type	Description
encoding	eEncoding enum
maxBytesToRead	int	default is 0 => read all file
offset	int	start reading point, default is 0

ListenFileOptions Object

Version added: 0.141

Describes the different options to listen to a file.

Parameter	Type	Description
skipToEnd	bool	should skip directly to end of file. default if false
encoding	encoding enum	Encoding to use. Default is is the default value

ListenOnFileResult Object

Version added: 0.141

Returned when subscribing to listen to a file.

Parameter	Type	Description
content	string	The current content of the file

WatchedFileChanged Object

Version added: 0.208

Returned when a watched file is changed (as well as when subscribing).

Parameter	Type	Description
eventType	WatchEventType	The type of change that occured
path	string	The current path of the file
newPath (optional)	string	The new file path. Only returned when eventType is Renamed.

WatchEventType Enum

Version added: 0.208

The type of change observed on a watched file.

Options
Registered
Changed
Renamed
Deleted

DirResult Object

Version added: 0.141

List of files and folders.

Parameter	Type	Description
success	boolean	Inherited from the "Result" Object
error	string	Inherited from the "Result" Object
data	FileInDir[]	List of files and folders

Example data

{
   "success":true,
   "path":"C:/Users/Hal9000/Videos/Overwolf",
   "data":[
      {
         "name":"Fortnite 03-19-2020 17-15-56-087.mp4",
         "type":"file"
      },
      {
         "name":"Game Events Simulator",
         "type":"dir"
      },
      {
         "name":"Game Summary",
         "type":"dir"
      }

   ]
}

FileExistsResult Object

Version added: 0.141

The result.

Parameter	Type	Description
success	boolean	Inherited from the "Result" Object
error	string	Inherited from the "Result" Object
found	boolean	Return if the file exist or not

Example data

{
   "success":true,
   "found":true
}

ReadFileContentsResult Object

Version added: 0.141

the status of the request and the file contect.

Parameter	Type	Description
success	boolean	Inherited from the "Result" Object
error	string	Inherited from the "Result" Object
content	string	string with the taraget file’s content

Example data

{"success":true,"content":"Hello World!"}

ListenOnFileResult Object

Version added: 0.141

The result.

Parameter	Type	Description
success	boolean	Inherited from the "Result" Object
error	string	Inherited from the "Result" Object
state	string	Current callback state. Only valid only when "success" is true overwolf.io.enums.fileListenerState
content	string	string with the taraget line content

Example data

{
    "success" : true, // when false the callback will stop listen
    "error": "", // valid only when success = false
    "state": "started|running|terminated|truncated", // valid only when success =true (overwolf.io.enums.fileListenerState) 
    "content": "" //the line  
}

notes

• "state" is from type overwolf.io.enums.fileListenerState.
• Please read what happens when you call stopFileListener().

ExistsResult Object

Version added: 0.141

The result.

Parameter	Type	Description
success	boolean	Inherited from the "Result" Object
error	string	Inherited from the "Result" Object
exist	boolean	Return if the file exist or not

Example data

{
   "success":true,
   "exist":true
}

ReadBinaryFileResult Object

Version added: 0.141

The result.

Parameter	Type	Description
success	boolean	Inherited from the "Result" Object
error	string	Inherited from the "Result" Object
content	string	Return with the file content
info	FileInfo object	Return with the file content

Example data

 {
    "success" : true,
    "error": "", 
    "content": byte[], // the file content in bytes
    "info" : {
        "eof" : true, // is EOF
        "totalRead" : 3000, // total read bytes
        "position" : 3000, // last file position
        "totalLines" :100, // total read lines
    }
}

ReadTextFileResult Object

Version added: 0.141

The result.

Parameter	Type	Description
success	boolean	Inherited from the "Result" Object
error	string	Inherited from the "Result" Object
content	string	Return with the file content
info	FileInfo object	Return with the file content

Example data

 {
    "success" : true,
    "error": "", 
    "content": byte[], // the file content in bytes
    "info" : {
        "eof" : true, // is EOF
        "totalRead" : 3000, // total read bytes
        "position" : 3000, // last file position
        "totalLines" :100, // total read lines
    }
}

FileInfo Object

Version added: 0.141

Container for the file info properties.

Parameter	Type	Description
success	boolean	Inherited from the "Result" Object
error	string	Inherited from the "Result" Object
eof	boolean
totalRead	number
position	number
totalLines	number

FileInDir Object

Version added: 0.141

Container for the list of files and folders in a directory.

Parameter	Type	Description
success	boolean	Inherited from the "Result" Object
error	string	Inherited from the "Result" Object
name	string
type	string

Example data

{
   "name":"Fortnite 03-19-2020 17-15-56-087.mp4",
   "type":"file"
}