dvander@252: /**
ds@475: * vim: set ts=4 :
ds@1330: * =============================================================================
ds@1947: * SourceMod (C)2004-2008 AlliedModders LLC. All rights reserved.
ds@1330: * =============================================================================
ds@1330: *
ds@1330: * This file is part of the SourceMod/SourcePawn SDK.
dvander@374: *
ds@1330: * This program is free software; you can redistribute it and/or modify it under
ds@1330: * the terms of the GNU General Public License, version 3.0, as published by the
ds@1330: * Free Software Foundation.
ds@1330: *
ds@1330: * This program is distributed in the hope that it will be useful, but WITHOUT
ds@1330: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
ds@1330: * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
ds@1330: * details.
ds@1330: *
ds@1330: * You should have received a copy of the GNU General Public License along with
ds@1330: * this program. If not, see .
ds@1330: *
ds@1330: * As a special exception, AlliedModders LLC gives you permission to link the
ds@1330: * code of this program (as well as its derivative works) to "Half-Life 2," the
ds@1330: * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
ds@1330: * by the Valve Corporation. You must obey the GNU General Public License in
ds@1330: * all respects for all other code used. Additionally, AlliedModders LLC grants
ds@1330: * this exception to all derivative works. AlliedModders LLC defines further
ds@1330: * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
ds@1330: * or .
dvander@374: *
dvander@374: * Version: $Id$
dvander@252: */
dvander@252:
dvander@252: #if defined _files_included
dvander@252: #endinput
dvander@252: #endif
dvander@252: #define _files_included
dvander@252:
dvander@1729: /**
dvander@1729: * @global All paths in SourceMod natives are relative to the mod folder
dvander@1729: * unless otherwise noted.
dvander@1729: *
dvander@1729: * Most functions in SourceMod (at least, ones that deal with direct
dvander@1729: * file manipulation) will support an alternate path specification.
dvander@1729: *
dvander@1729: * If the path starts with the string "file://" and the PathType is
dvander@1729: * not relative, then the "file://" portion is stripped off, and the
dvander@1729: * rest of the path is used without any modification (except for
dvander@1729: * correcting slashes). This can be used to override the path
dvander@1729: * builder to supply alternate absolute paths. Examples:
dvander@1729: *
dvander@1729: * file://C:/Temp/file.txt
dvander@1729: * file:///tmp/file.txt
dvander@1729: */
dvander@619:
dvander@619: /**
dvander@619: * File inode types.
dvander@619: */
dvander@252: enum FileType
dvander@252: {
dvander@252: FileType_Unknown = 0, /* Unknown file type (device/socket) */
dvander@252: FileType_Directory = 1, /* File is a directory */
dvander@252: FileType_File = 2, /* File is a file */
dvander@252: };
dvander@252:
dvander@1370: /**
dvander@1370: * File time modes.
dvander@1370: */
dvander@1370: enum FileTimeMode
dvander@1370: {
dvander@1370: FileTime_LastAccess = 0, /* Last access (does not work on FAT) */
dvander@1370: FileTime_Created = 1, /* Creation (does not work on FAT) */
dvander@1370: FileTime_LastChange = 2, /* Last modification */
dvander@1370: };
dvander@1370:
dvander@619: #define PLATFORM_MAX_PATH 256 /**< Maximum path length. */
dvander@252:
dvander@619: #define SEEK_SET 0 /**< Seek from start. */
dvander@619: #define SEEK_CUR 1 /**< Seek from current position. */
dvander@619: #define SEEK_END 2 /**< Seek from end position. */
faluco@274:
dvander@619: /**
dvander@619: * Path types.
dvander@619: */
dvander@345: enum PathType
dvander@345: {
dvander@619: Path_SM, /**< SourceMod root folder */
dvander@345: };
dvander@345:
dvander@345: /**
dvander@1729: * Builds a path relative to the SourceMod folder. This should be used instead of
dvander@1729: * directly referencing addons/sourcemod, in case users change the name of their
dvander@1729: * folder layout.
dvander@345: *
dvander@345: * @param type Type of path to build as the base.
dvander@345: * @param buffer Buffer to store the path.
dvander@345: * @param maxlength Maximum length of buffer.
dvander@345: * @param fmt Format string.
dvander@345: * @param ... Format arguments.
dvander@345: * @return Number of bytes written to buffer (not including null terminator).
dvander@345: */
ds@634: native BuildPath(PathType:type, String:buffer[], maxlength, const String:fmt[], any:...);
dvander@345:
dvander@252: /**
dvander@812: * Opens a directory/folder for contents enumeration.
dvander@1729: *
dvander@252: * @note Directories are closed with CloseHandle().
dvander@252: * @note Directories Handles can be cloned.
dvander@1729: * @note OpenDirectory() supports the "file://" notation.
dvander@252: *
dvander@252: * @param path Path to open.
dvander@345: * @return A Handle to the directory, INVALID_HANDLE on open error.
dvander@252: */
dvander@252: native Handle:OpenDirectory(const String:path[]);
dvander@252:
dvander@252: /**
dvander@812: * Reads the current directory entry as a local filename, then moves to the next file.
dvander@1729: *
dvander@252: * @note Contents of buffers are undefined when returning false.
dvander@252: * @note Both the '.' and '..' automatic directory entries will be retrieved for Windows and Linux.
dvander@252: *
dvander@252: * @param dir Handle to a directory.
dvander@252: * @param buffer String buffer to hold directory name.
dvander@252: * @param maxlength Maximum size of string buffer.
dvander@252: * @param type Optional variable to store the file type.
dvander@345: * @return True on success, false if there are no more files to read.
dvander@252: * @error Invalid or corrupt Handle.
dvander@252: */
dvander@257: native bool:ReadDirEntry(Handle:dir, String:buffer[], maxlength, &FileType:type=FileType_Unknown);
faluco@274:
faluco@274: /**
dvander@812: * Opens a file.
dvander@1729: *
faluco@274: * @note Files are closed with CloseHandle().
faluco@274: * @note File Handles can be cloned.
dvander@1729: * @note OpenFile() supports the "file://" notation.
faluco@274: *
ds@475: * @param file File to open.
ds@475: * @param mode Open mode.
ds@475: * @return A Handle to the file, INVALID_HANDLE on open error.
faluco@274: */
faluco@274: native Handle:OpenFile(const String:file[], const String:mode[]);
faluco@274:
faluco@274: /**
dvander@812: * Deletes a file.
faluco@274: *
ds@475: * @param path Path of the file to delete.
ds@475: * @return True on success, false otherwise.
faluco@274: */
faluco@274: native bool:DeleteFile(const String:path[]);
faluco@274:
faluco@274: /**
dvander@812: * Reads a line from a text file.
faluco@274: *
faluco@274: * @param hndl Handle to the file.
faluco@274: * @param buffer String buffer to hold the line.
faluco@274: * @param maxlength Maximum size of string buffer.
dvander@345: * @return True on success, false otherwise.
faluco@274: */
faluco@274: native bool:ReadFileLine(Handle:hndl, String:buffer[], maxlength);
faluco@274:
faluco@274: /**
dvander@1796: * Reads binary data from a file.
dvander@1796: *
dvander@1796: * @param hndl Handle to the file.
dvander@1796: * @param items Array to store each item read.
dvander@1796: * @param num_items Number of items to read into the array.
dvander@1796: * @param size Size of each element, in bytes, to be read.
dvander@1796: * Valid sizes are 1, 2, or 4.
dvander@1796: * @return Number of elements read, or -1 on error.
dvander@1796: */
dvander@1796: native ReadFile(Handle:hndl, items[], num_items, size);
dvander@1796:
dvander@1796: /**
dvander@1796: * Reads a UTF8 or ANSI string from a file.
dvander@1796: *
dvander@1796: * @param hndl Handle to the file.
dvander@1796: * @param buffer Buffer to store the string.
dvander@1796: * @param max_size Maximum size of the string buffer.
dvander@2445: * @param read_count If -1, reads until a null terminator is encountered in
dvander@2445: * the file. Otherwise, read_count bytes are read
dvander@2445: * into the buffer provided. In this case the buffer
dvander@2445: * is not explicitly null terminated, and the buffer
dvander@2445: * will contain any null terminators read from the file.
dvander@1796: * @return Number of characters written to the buffer, or -1
dvander@1796: * if an error was encountered.
dvander@1796: * @error Invalid Handle, or read_count > max_size.
dvander@1796: */
dvander@1796: native ReadFileString(Handle:hndl, String:buffer[], max_size, read_count=-1);
dvander@1796:
dvander@1796: /**
dvander@1796: * Writes binary data to a file.
dvander@1796: *
dvander@1796: * @param hndl Handle to the file.
dvander@1796: * @param items Array of items to write. The data is read directly.
dvander@1796: * That is, in 1 or 2-byte mode, the lower byte(s) in
dvander@1796: * each cell are used directly, rather than performing
dvander@1796: * any casts from a 4-byte number to a smaller number.
dvander@1796: * @param num_items Number of items in the array.
dvander@1796: * @param size Size of each item in the array in bytes.
dvander@1796: * Valid sizes are 1, 2, or 4.
dvander@1796: * @return True on success, false on error.
dvander@1797: * @error Invalid Handle.
dvander@1796: */
dvander@1796: native bool:WriteFile(Handle:hndl, const items[], num_items, size);
dvander@1796:
dvander@1796: /**
dvander@1796: * Writes a binary string to a file.
dvander@1796: *
dvander@1796: * @param hndl Handle to th efile.
dvander@1796: * @param buffer String to write.
dvander@1796: * @param term True to append NUL terminator, false otherwise.
dvander@1796: * @return True on success, false on error.
dvander@1797: * @error Invalid Handle.
dvander@1796: */
dvander@1796: native bool:WriteFileString(Handle:hndl, const String:buffer[], bool:term);
dvander@1796:
dvander@1796: /**
dvander@1796: * Writes a line of text to a text file. A newline is automatically appended.
dvander@1796: *
dvander@1796: * @param hndl Handle to the file.
dvander@1796: * @param format Formatting rules.
dvander@1796: * @param ... Variable number of format parameters.
dvander@1796: * @return True on success, false otherwise.
dvander@1797: * @error Invalid Handle.
dvander@1796: */
dvander@1796: native bool:WriteFileLine(Handle:hndl, const String:format[], any:...);
dvander@1796:
dvander@1796: /**
dvander@1796: * Reads a single binary cell from a file.
dvander@1796: *
dvander@1796: * @param hndl Handle to the file.
dvander@1796: * @param data Variable to store the data read.
dvander@1796: * @param size Size of the data to read in bytes. Valid
dvander@1796: * sizes are 1, 2, or 4 bytes.
dvander@1796: * @return Number of elements read (max 1), or -1 on error.
dvander@1797: * @error Invalid Handle.
dvander@1796: */
dvander@1796: stock ReadFileCell(Handle:hndl, &data, size)
dvander@1796: {
dvander@1796: new array[1], ret;
dvander@1796:
dvander@1796: if ((ret = ReadFile(hndl, array, 1, size)) == 1)
dvander@1796: {
dvander@1796: data = array[0];
dvander@1796: }
dvander@1796:
dvander@1796: return ret;
dvander@1796: }
dvander@1796:
dvander@1796: /**
dvander@1796: * Writes a single binary cell to a file.
dvander@1796: *
dvander@1796: * @param hndl Handle to the file.
dvander@1796: * @param data Cell to write to the file.
dvander@1796: * @param size Size of the data to read in bytes. Valid
dvander@1796: * sizes are 1, 2, or 4 bytes. If the size
dvander@1796: * is less than 4 bytes, the data is truncated
dvander@1796: * rather than casted. That is, only the lower
dvander@1796: * bits will be read.
dvander@1796: * @return True on success, false on error.
dvander@1797: * @error Invalid Handle.
dvander@1796: */
dvander@1796: stock bool:WriteFileCell(Handle:hndl, data, size)
dvander@1796: {
dvander@1796: new array[1];
dvander@1796:
dvander@1796: array[0] = data;
dvander@1796:
dvander@1796: return WriteFile(hndl, array, 1, size);
dvander@1796: }
dvander@1796:
dvander@1796: /**
dvander@812: * Tests if the end of file has been reached.
faluco@274: *
ds@475: * @param file Handle to the file.
ds@475: * @return True if end of file has been reached, false otherwise.
dvander@1797: * @error Invalid Handle.
faluco@274: */
faluco@274: native bool:IsEndOfFile(Handle:file);
faluco@274:
faluco@274: /**
dvander@812: * Sets the file position indicator.
faluco@274: *
ds@475: * @param file Handle to the file.
ds@475: * @param position Position relative to what is specified in whence.
dvander@1796: * @param where SEEK_ constant value of where to see from.
ds@475: * @return True on success, false otherwise.
dvander@1797: * @error Invalid Handle.
faluco@274: */
dvander@1796: native bool:FileSeek(Handle:file, position, where);
faluco@274:
faluco@274: /**
dvander@812: * Get current position in the file.
faluco@274: *
ds@475: * @param file Handle to the file.
ds@475: * @return Value for the file position indicator.
dvander@1797: * @error Invalid Handle.
faluco@274: */
faluco@274: native FilePosition(Handle:file);
faluco@274:
faluco@274: /**
dvander@812: * Checks if a file exists.
faluco@274: *
ds@475: * @param path Path to the file.
dvander@1854: * @param use_valve_fs If true, the Valve file system will be used instead.
skamonkey@4199: * This can be used to find files existing in any of
skamonkey@4199: * the GAME search paths, rather than solely files
skamonkey@4199: * existing directly in the gamedir.
ds@475: * @return True if the file exists, false otherwise.
faluco@274: */
dvander@1854: native bool:FileExists(const String:path[], bool:use_valve_fs=false);
faluco@274:
faluco@274: /**
dvander@812: * Renames a file.
faluco@274: *
faluco@274: * @param newpath New path to the file.
faluco@274: * @param oldpath Path to the existing file.
dvander@345: * @return True on success, false otherwise.
faluco@274: */
faluco@274: native bool:RenameFile(const String:newpath[], const String:oldpath[]);
faluco@274:
faluco@274: /**
dvander@812: * Checks if a directory exists.
faluco@274: *
ds@475: * @param path Path to the directory.
ds@475: * @return True if the directory exists, false otherwise.
faluco@274: */
faluco@274: native bool:DirExists(const String:path[]);
faluco@274:
faluco@274: /**
dvander@812: * Get the file size in bytes.
faluco@274: *
ds@475: * @param path Path to the file.
skamonkey@4199: * @param use_valve_fs If true, the Valve file system will be used instead.
skamonkey@4199: * This can be used to find files existing in any of
skamonkey@4199: * the GAME search paths, rather than solely files
skamonkey@4199: * existing directly in the gamedir.
ds@475: * @return File size in bytes, -1 if file not found.
faluco@274: */
skamonkey@4199: native FileSize(const String:path[], bool:use_valve_fs=false);
faluco@274:
faluco@274: /**
dvander@821: * Flushes a file's buffered output; any buffered output
dvander@821: * is immediately written to the file.
dvander@821: *
dvander@821: * @param file Handle to the file.
dvander@821: * @return True on success, false on failure.
dvander@821: */
dvander@821: native FlushFile(Handle:file);
dvander@821:
dvander@821: /**
dvander@812: * Removes a directory.
faluco@274: * @note On most Operating Systems you cannot remove a directory which has files inside it.
faluco@274: *
ds@475: * @param path Path to the directory.
ds@475: * @return True on success, false otherwise.
faluco@274: */
faluco@274: native bool:RemoveDir(const String:path[]);
faluco@274:
dvander@2307: #define FPERM_U_READ 0x0100 /* User can read. */
dvander@2307: #define FPERM_U_WRITE 0x0080 /* User can write. */
dvander@2307: #define FPERM_U_EXEC 0x0040 /* User can exec. */
dvander@2307: #define FPERM_G_READ 0x0020 /* Group can read. */
dvander@2307: #define FPERM_G_WRITE 0x0010 /* Group can write. */
dvander@2307: #define FPERM_G_EXEC 0x0008 /* Group can exec. */
dvander@2307: #define FPERM_O_READ 0x0004 /* Anyone can read. */
dvander@2307: #define FPERM_O_WRITE 0x0002 /* Anyone can write. */
dvander@2307: #define FPERM_O_EXEC 0x0001 /* Anyone can exec. */
dvander@2307:
dvander@2307: /**
dvander@2307: * Creates a directory.
dvander@2307: *
dvander@2307: * @param path Path to create.
dvander@2307: * @param mode Permissions (default is o=rx,g=rx,u=rwx). Note that folders must have
dvander@2307: * the execute bit set on Linux. On Windows, the mode is ignored.
dvander@2307: */
dvander@2307: native bool:CreateDirectory(const String:path[], mode);
dvander@2307:
faluco@274: /**
dvander@1370: * Returns a file timestamp as a unix timestamp.
dvander@1370: *
dvander@1370: * @param file File name.
dvander@1370: * @param tmode Time mode.
dvander@1370: * @return Time value, or -1 on failure.
dvander@1370: */
dvander@1370: native GetFileTime(const String:file[], FileTimeMode:tmode);
dvander@1378:
dvander@1378: /**
dvander@1378: * Same as LogToFile(), except uses an open file Handle. The file must
dvander@1378: * be opened in text appending mode.
dvander@1378: *
dvander@1378: * @param hndl Handle to the file.
dvander@1378: * @param message Message format.
dvander@1378: * @param ... Message format parameters.
dvander@1378: * @noreturn
dvander@1378: * @error Invalid Handle.
dvander@1378: */
dvander@1378: native LogToOpenFile(Handle:hndl, const String:message[], any:...);
dvander@1378:
dvander@1378: /**
dvander@1378: * Same as LogToFileEx(), except uses an open file Handle. The file must
dvander@1378: * be opened in text appending mode.
dvander@1378: *
dvander@1378: * @param hndl Handle to the file.
dvander@1378: * @param message Message format.
dvander@1378: * @param ... Message format parameters.
dvander@1378: * @noreturn
dvander@1378: * @error Invalid Handle.
dvander@1378: */
dvander@1378: native LogToOpenFileEx(Handle:hndl, const String:message[], any:...);
dvander@1378: