@amxts/core 0.1.0

package/amxmodx/base/include/file.inc

@@ -0,0 +1,666 @@
+// vim: set ts=4 sw=4 tw=99 noet:
+//
+// AMX Mod X, based on AMX Mod by Aleksander Naszko ("OLO").
+// Copyright (C) The AMX Mod X Development Team.
+//
+// This software is licensed under the GNU General Public License, version 3 or higher.
+// Additional exceptions apply. For full license details, see LICENSE.txt or visit:
+//     https://alliedmods.net/amxmodx-license
+
+//
+// File Functions
+//
+
+#if defined _file_included
+	#endinput
+#endif
+#define _file_included
+
+/**
+ * @note All paths in AMX Mod X natives are relative to the mod folder
+ * unless otherwise noted.
+ *
+ * Most functions in AMX Mod X (at least, ones that deal with direct 
+ * file manipulation) will support an alternate path specification.
+ */
+ 
+/**
+ * Maximum path length.
+ */
+#define PLATFORM_MAX_PATH  256
+
+/**
+ * File inode types for use with open_dir() and next_file().
+ */
+enum FileType
+{
+	FileType_Unknown,       /* Unknown file type (device/socket) */
+	FileType_Directory,     /* File is a directory */
+	FileType_File,          /* File is a file */
+};
+
+/**
+ * File time modes for use with GetFileTime().
+ */
+enum FileTimeType
+{
+	FileTime_LastAccess,    /* Last access (not available on FAT) */
+	FileTime_Created,       /* Creation (not available on FAT) */
+	FileTime_LastChange,    /* Last modification */
+};
+
+/**
+ * File position modes for use with fseek().
+ */
+#define SEEK_SET 0          /* Seek from start */
+#define SEEK_CUR 1          /* Seek from current position */
+#define SEEK_END 2          /* Seek from end position */
+
+/**
+ * Options for use with file_size() flag parameter.
+ */
+#define FSOPT_BYTES_COUNT  0  /* Returns the file size in number of bytes */
+#define FSOPT_LINES_COUNT  1  /* Returns how many lines there are in this file */
+#define FSOPT_END_WITH_LF  2  /* Returns whether the last line is '\n' */
+
+/**
+ * Data block modes for use with fread*() and fwrite*().
+ */
+#define BLOCK_INT   4
+#define BLOCK_SHORT 2
+#define BLOCK_CHAR  1
+#define BLOCK_BYTE  1
+
+/**
+ * File permissions flags for use with mkdir() and SetFilePermissions().
+ */
+#define FPERM_U_READ       0x0100   /* User can read.    */
+#define FPERM_U_WRITE      0x0080   /* User can write.   */
+#define FPERM_U_EXEC       0x0040   /* User can exec.    */
+#define FPERM_U_RWX        FPERM_U_READ | FPERM_U_WRITE | FPERM_U_EXEC
+
+#define FPERM_G_READ       0x0020   /* Group can read.   */
+#define FPERM_G_WRITE      0x0010   /* Group can write.  */
+#define FPERM_G_EXEC       0x0008   /* Group can exec.   */
+#define FPERM_G_RWX        FPERM_G_READ | FPERM_G_WRITE | FPERM_G_EXEC
+
+#define FPERM_O_READ       0x0004   /* Anyone can read.  */
+#define FPERM_O_WRITE      0x0002   /* Anyone can write. */
+#define FPERM_O_EXEC       0x0001   /* Anyone can exec.  */
+#define FPERM_O_RWX        FPERM_O_READ | FPERM_O_WRITE | FPERM_O_EXEC
+
+#define FPERM_DIR_DEFAULT  FPERM_U_RWX | FPERM_G_RWX | FPERM_O_RWX /* rwx r-x r-x (0755) */
+
+
+/**
+ * Reads content from directory
+ *
+ * @note This native is expensive. Consider the use of open_dir(), next_file() and close_dir() instead.
+ * @note Both the '.' and '..' automatic directory entries will be retrieved for Windows and Linux.
+ *
+ * @param dirname      Path to open
+ * @param pos          Index the element
+ * @param output       String buffer to hold content
+ * @param len          Maximum size of string buffer
+ * @param outlen       Number of characters written to the buffer
+ *
+ * @return             Returns index of next element, otherwiwe 0 when end of dir is reached
+ */
+native read_dir(const dirname[], pos, output[], len, &outlen = 0);
+
+/**
+ * Reads line from file.
+ *
+ * @note This native is expensive. Consider the use of new file natives (fopen(), fgets(), etc.)
+ *       if purpose is to read several lines of a file.
+ *
+ * @param file         Path to open
+ * @param line         Index of the line, starting to 0
+ * @param text         String buffer to hold line read
+ * @param len          Maximum size of string buffer
+ * @param txtlen       Number of characters written to the buffer
+ *
+ * @return             Returns index of next line, otherwise 0 when end of file is reached
+ * @error              Unable to read the file
+ */
+native read_file(const file[], line, text[], len, &txtlen = 0);
+
+/**
+ * Writes text to file.
+ *
+ * @note This native is expensive. Consider the use of new file natives (fopen(), fputs(), etc.)
+ *       if purpose is to write several lines of a file.
+ *
+ * @param file         Path to open
+ * @param text         String to write to
+ * @param line         Index of the line, starting to 0
+ *                     If < 0, content will be appended
+ *
+ * @noreturn
+ * @error              Unable to write [temporary] file
+ */
+native write_file(const file[], const text[], line = -1);
+
+/**
+ * Deletes a file.
+ *
+ * @param file          Path of the file to delete
+ * @param use_valve_fs  If true, the Valve file system will be used instead.
+ *                      This can be used to delete files existing in the Valve
+ *                      search path, rather than solely files existing directly
+ *                      in the gamedir.
+ * @param valve_path_id If use_valve_fs, a search path from gameinfo or NULL_STRING for all search paths.
+ *
+ * @return              1 on success, 0 on failure or if file not immediately removed.
+ */
+native delete_file(const file[], bool:use_valve_fs = false, const valve_path_id[] = "GAMECONFIG");
+
+/**
+ * Checks if a file exists.
+ *
+ * @param file          Path to the file
+ * @param use_valve_fs  If true, the Valve file system will be used instead.
+ *                      This can be used to find files existing in any of
+ *                      the Valve search paths, rather than solely files
+ *                      existing directly in the gamedir.
+ *
+ * @return              1 if the file exists, 0 otherwise
+ */
+native file_exists(const file[], bool:use_valve_fs = false);
+
+/**
+  * Renames a file.
+  *
+  * @param oldname      New path to the file
+  * @param newname      Path to the existing file
+  * @param relative     If true, native  will act like other natives which
+  *                     use the moddir as a base directory. Otherwise, the
+  *                     current directory is undefined (but assumed to be hlds).
+  *
+  * @return             1 on success, 0 otherwise
+  */
+native rename_file(const oldname[], const newname[], relative = 0);
+
+/**
+ * Checks if a directory exists.
+ *
+ * @param dir           Path to the directory
+ * @param use_valve_fs  If true, the Valve file system will be used instead.
+ *                      This can be used to find files existing in any of
+ *                      the Valve search paths, rather than solely files
+ *                      existing directly in the gamedir.
+ *
+ * @return              1 if the directory exists, 0 otherwise
+ */
+native dir_exists(const dir[], bool:use_valve_fs = false);
+
+/**
+ * Get the file size in bytes.
+ *
+ * @param file          Path to the file
+ * @param flag          Flag options, see FSOPT_* constants
+ * @param use_valve_fs  If true, the Valve file system will be used instead.
+ *                      This can be used to find files existing in any of
+ *                      the Valve search paths, rather than solely files
+ *                      existing directly in the gamedir.
+ *                      If used, flag option is ignored.
+ * @param valve_path_id If use_valve_fs, a search path from gameinfo or NULL_STRING for all search paths
+ *
+ * @return              If flag is FSOPT_BYTES_COUNT or use_valve_fs to true, the file size in bytes
+ *                      If flag is FSOPT_LINES_COUNT, the number of lines in the file
+ *                      If flag is FSOPT_END_WITH_LF, 1 is returned if file ends with line feed
+ *                      If file doesn't exist, -1
+ */
+native file_size(const file[], flag = FSOPT_BYTES_COUNT, bool:use_valve_fs = false, const valve_path_id[] = "GAME");
+
+/**
+ * Opens or creates a file, returning a file handle on success. File handles
+ * should be closed with fclose().
+ *
+ * @note The open mode may be one of the following strings:
+ *         "r": Open an existing file for reading.
+ *         "w": Create a file for writing, or truncate (delete the contents of) an
+ *              existing file and then open it for writing.
+ *         "a": Create a file for writing, or open an existing file such that writes
+ *              will be appended to the end.
+ *        "r+": Open an existing file for both reading and writing.
+ *        "w+": Create a file for reading and writing, or truncate an existing file
+ *              and then open it for reading and writing.
+ *        "a+": Create a file for both reading and writing, or open an existing file
+ *              such that writes will be appended to the end.
+ *
+ * @note The open mode may also contain an additional character after "r", "w", or "a",
+ *       but before any "+" sign. This character may be "b" (indicating binary mode) or
+ *       "t" (indicating text mode). By default, "text" mode is implied. On Linux and
+ *       Mac, this has no distinction from binary mode. On Windows, it causes the '\n'
+ *       character (0xA) to be written as "\r\n" (0xD, 0xA).
+ *
+ *       Example: "rb" opens a binary file for writing; "at" opens a text file for
+ *       appending.
+ *
+ * @note Registered paths ID are (in priority order) :
+ *         GAME           All paths related to current mod, including fallback
+ *                        Depending settings, it includes: <gamedir>_lv/_addon/_<language>/_hd
+ *                        and <gamedir> itself
+ *         GAMECONFIG     The default writable directory (<gamedir>)
+ *         GAMEDOWNLOAD   The download directory (<gamedir>_download)
+ *         GAME_FALLBACK  All paths related to fallback game, same as GAME
+ *         DEFAULTGAME    All paths related to the default game which is "valve", same as GAME
+ *         BASE           The base path where server is installed
+ *
+ *         Note that some paths are non-writable. It includes all <gamedir>_* (expect _download)
+ *         and DEFAULTGAME. Any file inside a non-writable path will be ignored if you try to open
+ *         it in writing mode.
+ *
+ * @param filename      File to open
+ * @param mode          Open mode
+ * @param use_valve_fs  If true, the Valve file system will be used instead
+ *                      This can be used to finred files existing in valve
+ *                      search paths, rather than solely files existing directly
+ *                      in the gamedir.
+ * @param valve_path_id If use_valve_fs, a search path from gameinfo or NULL_STRING for all search paths
+ *
+ * @return              A file handle, or null if the file could not be opened.
+ */
+native fopen(const filename[], const mode[], bool:use_valve_fs = false, const valve_path_id[] = "GAME");
+
+/**
+ * Closes a file handle.
+ *
+ * @param file          File handle
+ */
+native fclose(file);
+
+/**
+ * Reads a single binary data from a file.
+ *
+ * @param file          Handle to the file
+ * @param data          Variable to store item read
+ * @param mode          Size of each element, in bytes, to be read
+ *                      See BLOCK_* constants
+ *
+ * @return              Number of elements read
+ */
+native fread(file, &any:data, mode);
+
+/**
+ * Reads binary data from a file.
+ *
+ * @param file          Handle to the file
+ * @param data          Array to store each item read
+ * @param blocks        Number of items to read into the array
+ * @param mode          Size of each element, in bytes, to be read
+ *                      Valid sizes are 1, 2, or 4. See BLOCK_* constants.
+ *
+ * @return              Number of elements read
+ */
+native fread_blocks(file, any:data[], blocks, mode);
+
+/**
+ * Reads raw binary data from a file.
+ *
+ * @param file          Handle to the file
+ * @param stream        Array to store each item read
+ * @param blocksize     Number of items to read into the array
+ * @param blocks        Size of each element, in bytes. The data is read directly.
+ *                      That is, in 1 or 2-byte mode, the lower byte(s) in
+ *                      each cell are used directly, rather than performing
+ *                      any casts from a 4-byte number to a smaller number.
+ *
+ * @return              Number of elements read
+ */
+native fread_raw(file, any:stream[], blocksize, blocks);
+
+/**
+ * Writes a single binary data to a file.
+ *
+ * @param file          Handle to the file
+ * @param data          Item to write
+ * @param mode          Size of each item in the array in bytes
+ *                      Valid sizes are 1, 2, or 4. See BLOCK_* constants
+ *
+ * @return              Number of elements written
+ */
+native fwrite(file, any:data, mode);
+
+/**
+ * Writes binary data to a file.
+ *
+ * @param file          Handle to the file
+ * @param data          Array of items to write
+ * @param blocks        Number of items in the array
+ * @param mode          Size of each item in the array in bytes
+ *                      Valid sizes are 1, 2, or 4. See BLOCK_* constants
+ *
+ * @return              Number of elements written
+ */
+native fwrite_blocks(file, const any:data[], blocks, mode);
+
+/**
+ * Writes raw binary data to a file.
+ *
+ * @param file          Handle to the file.
+ * @param stream        Array of items to write.  The data is written directly.
+ *                      That is, in 1 or 2-byte mode, the lower byte(s) in
+ *                      each cell are used directly, rather than performing
+ *                      any casts from a 4-byte number to a smaller number.
+ * @param blocks        Size of each item in the array in bytes.
+ * @param mode          Number of items in the array.
+ *
+ * @return              Number of elements written
+ */
+native fwrite_raw(file, const any:stream[], blocks, mode);
+
+/**
+ * Tests if the end of file has been reached.
+ *
+ * @param file          Handle to the file
+ *
+ * @return              1 if end of file has been reached, 0 otherwise.
+ */
+native feof(file);
+
+/**
+ * Reads a line from a text file.
+ *
+ * @param file          Handle to the file.
+ * @param buffer        String buffer to hold the line
+ * @param maxlength     Maximum size of string buffer
+ *
+ * @return              Total number of characters written on success, 0 otherwise
+ */
+native fgets(file, buffer[], maxlength);
+
+/**
+ * Writes a line of text to a text file.
+ *
+ * @param file          Handle to the file
+ * @param text          String to write
+ * @param null_term     True to append NULL terminator, false otherwise
+ *
+ * @return              0 on success, -1 otherwise
+ */
+native fputs(file, const text[], bool:null_term = false);
+
+/**
+ * Writes a line of formatted text to a text file.
+ *
+ * @param file          Handle to the file
+ * @param format        Formatting rules
+ * @param ...           Variable number of format parameters
+ *
+ * @return              Total number of characters written on success, 0 otherwise
+ */
+native fprintf(file, const fmt[], any:...);
+
+/**
+ * Sets the file position indicator.
+ *
+ * @param file          Handle to the file
+ * @param position      Position relative to what is specified in whence
+ * @param start         SEEK_ constant value of where to see from
+ *
+ * @return              0 on success, a non-zero value otherwise
+ */
+native fseek(file, position, start);
+
+/**
+ * Gets current position in the file.
+ *
+ * @param file          Handle to the file
+ *
+ * @return              Value for the file position indicator
+ */
+native ftell(file);
+
+/**
+ * Gets character from file.
+ *
+ * @param file          Handle to the file
+ *
+ * @return              Character read on success, -1 otherwise
+ */
+native fgetc(file);
+
+/**
+ * Writes character to file
+ *
+ * @param file          Handle to the file
+ * @param data          Character to put
+ *
+ * @return              Character written on success, -1 otherwise
+ */
+native fputc(file, data);
+
+/**
+ * Ungets character from file.
+ *
+ * @param file          Handle to the file
+ * @param data          Character to unget
+ *
+ * @return              On success, the character put back is returned, -1 otherwise
+ */
+native fungetc(file, data);
+
+/**
+ * Flushes a buffered output stream.
+ *
+ * @param file          File handle, or 0 for all open streams
+ *
+ * @return              0 on success, -1 on failure
+ */
+native fflush(file);
+
+/**
+ * Gets the formatted file size in bytes.
+ *
+ * @param filename      Path to the file
+ * @param ...           Variable number of format parameters
+ *
+ * @return              File size in bytes, otherwise -1 if file not found
+ */
+native filesize(const filename[], any:...);
+
+/**
+ * Removes a directory.
+ *
+ * @note On most Operating Systems you cannot remove a directory which has files inside it.
+ *
+ * @param path          Path to the directory
+ *
+ * @return              1 on success, 0 otherwise
+ */
+native rmdir(const path[]);
+
+/**
+ * Creates a directory.
+ *
+ * @param path          Path to create
+ * @param mode          Permissions (default is o=rx,g=rx,u=rwx).  Note that folders must have
+ *                      the execute bit set on Linux.  On Windows, the mode is ignored.
+ * @param use_valve_fs  If true, the Valve file system will be used instead
+ *                      This can be used to create folders in the game's
+ *                      Valve search paths, rather than directly in the gamedir.
+ * @param valve_path_id If use_valve_fs, a search path from gameinfo or NULL_STRING for default
+ *                      In this case, mode is ignored
+ *
+ * @return              0 on success, -1 otherwise
+ */
+native mkdir(const dirname[], mode = FPERM_DIR_DEFAULT, bool:use_valve_fs = false, const valve_path_id[] = "GAMECONFIG");
+
+/**
+ * Deletes a file (delete_file macro)
+ *
+ * @param filename      Path of the file to delete
+ * @param use_valve_fs  If true, the Valve file system will be used instead.
+ *                      This can be used to delete files existing in the Valve
+ *                      search path, rather than solely files existing directly
+ *                      in the gamedir.
+ * @param valve_path_id If use_valve_fs, a search path from gameinfo or NULL_STRING for all search paths
+ *
+ * @return              1 on success, 0 on failure or if file not immediately removed
+ */
+native unlink(const filename[], bool:use_valve_fs = false, const valve_path_id[] = "GAMECONFIG");
+
+/**
+ * Opens a directory/folder for contents enumeration.
+ *
+ * @note Directories are closed with close_dir().
+ *
+ * @param dir           Path to open.
+ * @param firstfile     String buffer to hold first file name
+ * @param length        Maximum size of the string buffer
+ * @param type          Optional variable to store the file type
+ * @param use_valve_fs  If true, the Valve file system will be used instead.
+ *                      This can be used to find files existing in any of
+ *                      the Valve search paths, rather than solely files
+ *                      existing directly in the gamedir.
+ * @param valve_path_id If use_valve_fs, a search path from gameinfo or NULL_STRING for all search paths.
+ *
+ * @return              Handle to the directory, 0 otherwise
+ */
+native open_dir(const dir[], firstfile[], length, &FileType:type = FileType_Unknown, bool:use_valve_fs = false, const valve_path_id[] = "GAME");
+
+/**
+ * Reads the next directory entry as a local filename.
+ *
+ * @note Contents of buffers are undefined when returning false.
+ * @note Both the '.' and '..' automatic directory entries will be retrieved for Windows and Linux.
+ *
+ * @param dirh          Handle to a directory
+ * @param buffer        String buffer to hold directory name
+ * @param length        Maximum size of string buffer
+ * @param type          Optional variable to store the file type. FileType_* constants
+ *
+ * @return              1 on success, 0 if there are no more files to read.
+ */
+native next_file(dirh, buffer[], length, &FileType:type = FileType_Unknown);
+
+/**
+ * Closes the directory.
+ *
+ * @param dirh          Handle to a directory
+ */
+native close_dir(dirh);
+
+/**
+ * Loads a file using the LoadFileForMe engine function.
+ *
+ * The data is truncated if there is not enough space.  No null-terminator
+ * is applied; the data is the raw contents of the file.
+ *
+ * @param file          File to load (may be a file from the GCF)
+ * @param buffer        Buffer to store file contents
+ * @param maxlength     Maximum size of the file buffer
+ * @param length        Variable to store the file length.  This may return
+ *                      a number larger than the buffer size
+ * @return              -1 if the file could not be loaded.  Otherwise,
+ *                      the number of cells actually written to the buffer
+ *                      are returned.
+ */
+native LoadFileForMe(const file[], buffer[], maxlength, &length = 0);
+
+/**
+ * Returns a file timestamp as a unix timestamp.
+ *
+ * @param file          File name
+ * @param tmode         Time mode, see FileTime_* constants
+ *
+ * @return              Returns a file timestamp as a unix timestamp
+ */
+native GetFileTime(const file[], FileTimeType:tmode);
+
+/**
+ * Changes a file or directories permissions.
+ *
+ * @param path          Path to the file
+ * @param mode          Permissions to set, see FPERM_* constants
+ *
+ * @return              True on success, false otherwise
+ */
+native bool:SetFilePermissions(const path[], mode);
+
+/**
+ * Reads a single int8 (byte) from a file. The returned value is sign-
+ * extended to an int32.
+ *
+ * @param file          Handle to the file
+ * @param data          Variable to store the data read
+ *
+ * @return              True on success, false on failure
+ */
+native bool:FileReadInt8(file, &any:data);
+
+/**
+ * Reads a single uint8 (unsigned byte) from a file. The returned value is
+ * zero-extended to an int32.
+ *
+ * @param file          Handle to the file
+ * @param data          Variable to store the data read
+ *
+ * @return              True on success, false on failure
+ */
+native bool:FileReadUint8(file, &any:data);
+
+/**
+ * Reads a single int16 (short) from a file. The value is sign-extended to
+ * an int32.
+ *
+ * @param file          Handle to the file
+ * @param data          Variable to store the data read
+ *
+ * @return              True on success, false on failure
+ */
+native bool:FileReadInt16(file, &any:data);
+
+/**
+ * Reads a single unt16 (unsigned short) from a file. The value is zero-
+ * extended to an int32.
+ *
+ * @param file          Handle to the file
+ * @param data          Variable to store the data read
+ *
+ * @return              True on success, false on failure
+ */
+native bool:FileReadUint16(file, &any:data);
+
+/**
+ * Reads a single int32 (int/cell) from a file.
+ *
+ * @param file          Handle to the file
+ * @param data          Variable to store the data read
+ *
+ * @return              True on success, false on failure
+ */
+native bool:FileReadInt32(file, &any:data);
+
+/**
+ * Writes a single int8 (byte) to a file.
+ *
+ * @param file          Handle to the file
+ * @param data          Data to write (truncated to an int8)
+ *
+ * @return              True on success, false on failure
+ */
+native bool:FileWriteInt8(file, any:data);
+
+/**
+ * Writes a single int16 (short) to a file.
+ *
+ * @param file          Handle to the file
+ * @param data          Data to write (truncated to an int16)
+ *
+ * @return              True on success, false on failure
+ */
+native bool:FileWriteInt16(file, any:data);
+
+/**
+ * Writes a single int32 (int/cell) to a file.
+ *
+ * @param file          Handle to the file
+ * @param data          Data to write
+ *
+ * @return              True on success, false on failure
+ */
+native bool:FileWriteInt32(file, any:data);
+