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