XLua2 API Ref XPLMUtilities Latest - 4.4.0-d4

File Utilities

The XPLMUtilities file APIs provide some basic file and path functions for use with X-Plane.

Directory Separators

The XPLM has two modes it can work in:

X-Plane native paths: all paths are UTF8 strings, using the unix forward slash (/) as the directory separating character. In native path mode, you use the same path format for all three operating systems.
Legacy OS paths: the directroy separator is \ for Windows, : for OS X, and / for Linux; OS paths are encoded in MacRoman for OS X using legacy HFS conventions, use the application code page for multi-byte encoding on Unix using DOS path conventions, and use UTF-8 for Linux.

While legacy OS paths are the default, we strongly encourage you to opt in to native paths using the XPLMEnableFeature API.

All OS X plugins should enable native paths all of the time; if you do not do this, you will have to convert all paths back from HFS to Unix (and deal with MacRoman) - code written using native paths and the C file APIs "just works" on OS X.
For Linux plugins, there is no difference between the two encodings.
Windows plugins will need to convert the UTF8 file paths to UTF16 for use with the "wide" APIs. While it might seem tempting to stick with legacy OS paths (and just use the "ANSI" Windows APIs), X-Plane is fully unicode-capable, and will often be installed in paths where the user's directories have no ACP encoding.

Full and Relative Paths

Some of these APIs use full paths, but others use paths relative to the user's X-Plane installation. This is documented on a per-API basis.

XPLMDataFileType

enum XPLM200

These enums define types of data files you can load or unload using the SDK.

Name	Value	Description
xplm_DataFile_Situation	1	A situation (.sit) file, which starts off a flight in a given configuration.
xplm_DataFile_ReplayMovie	2	A situation movie (.smo) file, which replays a past flight.

Used by:

XPLMLoadDataFile
XPLMSaveDataFile

XPLMGetSystemPath

function

This function returns the full path to the X-System folder. Note that this is a directory path, so it ends in a trailing : or / .

The buffer you pass should be at least 512 characters long. The path is returned using the current native or OS path conventions.

XPLMGetSystemPath(
    outSystemPath     -- char
)

XPLMGetPrefsPath

function

This routine returns a full path to a file that is within X-Plane's preferences directory. (You should remove the file name back to the last directory separator to get the preferences directory using XPLMExtractFileAndPath).

The buffer you pass should be at least 512 characters long. The path is returned using the current native or OS path conventions.

XPLMGetPrefsPath(
    outPrefsPath     -- char
)

XPLMGetDirectorySeparator

function

This routine returns a string with one char and a null terminator that is the directory separator for the current platform. This allows you to write code that concatenates directory paths without having to #ifdef for platform. The character returned will reflect the current file path mode.

-- returns string -> assign to local/var
local my_result = XPLMGetDirectorySeparator(
)

XPLMLoadDataFile

function XPLM200

Loads a data file of a given type. Paths must be relative to the X-System folder. To clear the replay, pass a NULL file name (this is only valid with replay movies, not sit files).

-- returns boolean -> assign to local/var
local my_result = XPLMLoadDataFile(
    inFileType,    -- XPLMDataFileType
    inFilePath     -- string
)

See associated types:

XPLMDataFileType

XPLMSaveDataFile

function XPLM200

Saves the current situation or replay; paths are relative to the X-System folder.

-- returns boolean -> assign to local/var
local my_result = XPLMSaveDataFile(
    inFileType,    -- XPLMDataFileType
    inFilePath     -- string
)

See associated types:

XPLMDataFileType