Skip to main content

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​

Types Reference​

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.

ParameterTypeDescription
filePathstringPath to check for
callbackfunctionReturns the result
callback(Result: FileExistsResult) => voidReturns 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.

ParameterTypeDescription
filePathstringPath to check for
contentstringContent to write
encodingeEncoding enumEncoding to use
triggerUacIfRequiredboolIf additional permissions are required, triggers the Windows UAC dialog
callback(Result) => voidReturns with the result

readFileContents(filePath, encoding, callback)​

Version added: 0.93​

Permissions required: FileSystem​

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

ParameterTypeDescription
filePathstringFull path of the targeted file
encodingeEncoding enumEncoding to use
callback(Result: ReadFileContentsResult) => voidReturns 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.

ParameterTypeDescription
srcstringA relative file path from your extension's root folder, or a full overwolf-extension:// URI to the source file
dststringDestination absolute path to copy to including filename. See usage example below
overrideFilebool"true" if you want an existing file to be overwritten, "false" otherwise
reservedboolFor future use
callback(Result) => voidReturns 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.

ParameterTypeDescription
pathstringThe target path
callback(Result: DirResult) => voidReturns 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.

ParameterTypeDescription
pathstringThe target path
optionsReadFileOptions object
callback(Result: ReadBinaryFileResult) => voidReturns 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.

ParameterTypeDescription
pathstringThe target path
optionsReadFileOptions object
callback(Result: ReadTextFileResult) => voidReturns with the result

exist(path, callback)​

Version added: 0.141​

Permissions required: FileSystem​

Is path exist.

ParameterTypeDescription
pathstringThe target path
callback(Result: ExistsResult) => voidReturns 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.

ParameterTypeDescription
idstringlisten Id
pathstringfile path
optionsListenFileOptions Object
callback(Result: ListenOnFileResult) => voidReturns 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).

ParameterTypeDescription
idstringlisten 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.

ParameterTypeDescription
filePathstringPath to the file to watch
callback(Result: WatchedFileChanged) => voidCallback 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

ParameterTypeDescription
filePathstringPath to the file to stop watching
callback(Reuslt) => voidCallback 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.

ParameterTypeDescription
encodingeEncoding enum
maxBytesToReadintdefault is 0 => read all file
offsetintstart reading point, default is 0

ListenFileOptions Object​

Version added: 0.141​

Describes the different options to listen to a file.

ParameterTypeDescription
skipToEndboolshould skip directly to end of file. default if false
encodingencoding enumEncoding to use. Default is is the default value

ListenOnFileResult Object​

Version added: 0.141​

Returned when subscribing to listen to a file.

ParameterTypeDescription
contentstringThe current content of the file

WatchedFileChanged Object​

Version added: 0.208​

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

ParameterTypeDescription
eventTypeWatchEventTypeThe type of change that occured
pathstringThe current path of the file
newPath (optional)stringThe 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.

ParameterTypeDescription
successbooleanInherited from the "Result" Object
errorstringInherited from the "Result" Object
dataFileInDir[]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.

ParameterTypeDescription
successbooleanInherited from the "Result" Object
errorstringInherited from the "Result" Object
foundbooleanReturn 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.

ParameterTypeDescription
successbooleanInherited from the "Result" Object
errorstringInherited from the "Result" Object
contentstringstring with the taraget file’s content

Example data​

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

ListenOnFileResult Object​

Version added: 0.141​

The result.

ParameterTypeDescription
successbooleanInherited from the "Result" Object
errorstringInherited from the "Result" Object
statestringCurrent callback state. Only valid only when "success" is true overwolf.io.enums.fileListenerState
contentstringstring 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​

ExistsResult Object​

Version added: 0.141​

The result.

ParameterTypeDescription
successbooleanInherited from the "Result" Object
errorstringInherited from the "Result" Object
existbooleanReturn if the file exist or not

Example data​

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

ReadBinaryFileResult Object​

Version added: 0.141​

The result.

ParameterTypeDescription
successbooleanInherited from the "Result" Object
errorstringInherited from the "Result" Object
contentstringReturn with the file content
infoFileInfo objectReturn 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.

ParameterTypeDescription
successbooleanInherited from the "Result" Object
errorstringInherited from the "Result" Object
contentstringReturn with the file content
infoFileInfo objectReturn 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.

ParameterTypeDescription
successbooleanInherited from the "Result" Object
errorstringInherited from the "Result" Object
eofboolean
totalReadnumber
positionnumber
totalLinesnumber

FileInDir Object​

Version added: 0.141​

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

ParameterTypeDescription
successbooleanInherited from the "Result" Object
errorstringInherited from the "Result" Object
namestring
typestring

Example data​

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