dvander@252: /**
ds@475: * vim: set ts=4 :
ds@1330: * =============================================================================
dvander@374: * SourceMod (C)2004-2007 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@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.
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.
ds@475: * @param whence Look at the SEEK_* definitions.
ds@475: * @return True on success, false otherwise.
faluco@274: */
faluco@274: native bool:FileSeek(Handle:file, position, whence);
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.
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.
ds@475: * @return True if the file exists, false otherwise.
faluco@274: */
faluco@274: native bool:FileExists(const String:path[]);
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.
ds@475: * @return File size in bytes, -1 if file not found.
faluco@274: */
faluco@274: native FileSize(const String:path[]);
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:
faluco@274: /**
dvander@812: * Writes a line of text in a file.
faluco@274: * @note This native will append the newline character.
faluco@274: *
ds@475: * @param hndl Handle to the file.
ds@475: * @param format Formatting rules.
ds@475: * @param ... Variable number of format parameters.
ds@475: * @return True on success, false otherwise.
faluco@274: */
ds@634: native bool:WriteFileLine(Handle:hndl, const String:format[], any:...);
dvander@1370:
dvander@1370: /**
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: