1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/plugins/include/files.inc Sun Mar 30 07:00:22 2008 +0000
1.3 @@ -0,0 +1,388 @@
1.4 +/**
1.5 + * vim: set ts=4 :
1.6 + * =============================================================================
1.7 + * SourceMod (C)2004-2008 AlliedModders LLC. All rights reserved.
1.8 + * =============================================================================
1.9 + *
1.10 + * This file is part of the SourceMod/SourcePawn SDK.
1.11 + *
1.12 + * This program is free software; you can redistribute it and/or modify it under
1.13 + * the terms of the GNU General Public License, version 3.0, as published by the
1.14 + * Free Software Foundation.
1.15 + *
1.16 + * This program is distributed in the hope that it will be useful, but WITHOUT
1.17 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
1.18 + * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
1.19 + * details.
1.20 + *
1.21 + * You should have received a copy of the GNU General Public License along with
1.22 + * this program. If not, see <http://www.gnu.org/licenses/>.
1.23 + *
1.24 + * As a special exception, AlliedModders LLC gives you permission to link the
1.25 + * code of this program (as well as its derivative works) to "Half-Life 2," the
1.26 + * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
1.27 + * by the Valve Corporation. You must obey the GNU General Public License in
1.28 + * all respects for all other code used. Additionally, AlliedModders LLC grants
1.29 + * this exception to all derivative works. AlliedModders LLC defines further
1.30 + * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
1.31 + * or <http://www.sourcemod.net/license.php>.
1.32 + *
1.33 + * Version: $Id$
1.34 + */
1.35 +
1.36 +#if defined _files_included
1.37 + #endinput
1.38 +#endif
1.39 +#define _files_included
1.40 +
1.41 +/**
1.42 + * @global All paths in SourceMod natives are relative to the mod folder
1.43 + * unless otherwise noted.
1.44 + *
1.45 + * Most functions in SourceMod (at least, ones that deal with direct
1.46 + * file manipulation) will support an alternate path specification.
1.47 + *
1.48 + * If the path starts with the string "file://" and the PathType is
1.49 + * not relative, then the "file://" portion is stripped off, and the
1.50 + * rest of the path is used without any modification (except for
1.51 + * correcting slashes). This can be used to override the path
1.52 + * builder to supply alternate absolute paths. Examples:
1.53 + *
1.54 + * file://C:/Temp/file.txt
1.55 + * file:///tmp/file.txt
1.56 + */
1.57 +
1.58 +/**
1.59 + * File inode types.
1.60 + */
1.61 +enum FileType
1.62 +{
1.63 + FileType_Unknown = 0, /* Unknown file type (device/socket) */
1.64 + FileType_Directory = 1, /* File is a directory */
1.65 + FileType_File = 2, /* File is a file */
1.66 +};
1.67 +
1.68 +/**
1.69 + * File time modes.
1.70 + */
1.71 +enum FileTimeMode
1.72 +{
1.73 + FileTime_LastAccess = 0, /* Last access (does not work on FAT) */
1.74 + FileTime_Created = 1, /* Creation (does not work on FAT) */
1.75 + FileTime_LastChange = 2, /* Last modification */
1.76 +};
1.77 +
1.78 +#define PLATFORM_MAX_PATH 256 /**< Maximum path length. */
1.79 +
1.80 +#define SEEK_SET 0 /**< Seek from start. */
1.81 +#define SEEK_CUR 1 /**< Seek from current position. */
1.82 +#define SEEK_END 2 /**< Seek from end position. */
1.83 +
1.84 +/**
1.85 + * Path types.
1.86 + */
1.87 +enum PathType
1.88 +{
1.89 + Path_SM, /**< SourceMod root folder */
1.90 +};
1.91 +
1.92 +/**
1.93 + * Builds a path relative to the SourceMod folder. This should be used instead of
1.94 + * directly referencing addons/sourcemod, in case users change the name of their
1.95 + * folder layout.
1.96 + *
1.97 + * @param type Type of path to build as the base.
1.98 + * @param buffer Buffer to store the path.
1.99 + * @param maxlength Maximum length of buffer.
1.100 + * @param fmt Format string.
1.101 + * @param ... Format arguments.
1.102 + * @return Number of bytes written to buffer (not including null terminator).
1.103 + */
1.104 +native BuildPath(PathType:type, String:buffer[], maxlength, const String:fmt[], any:...);
1.105 +
1.106 +/**
1.107 + * Opens a directory/folder for contents enumeration.
1.108 + *
1.109 + * @note Directories are closed with CloseHandle().
1.110 + * @note Directories Handles can be cloned.
1.111 + * @note OpenDirectory() supports the "file://" notation.
1.112 + *
1.113 + * @param path Path to open.
1.114 + * @return A Handle to the directory, INVALID_HANDLE on open error.
1.115 + */
1.116 +native Handle:OpenDirectory(const String:path[]);
1.117 +
1.118 +/**
1.119 + * Reads the current directory entry as a local filename, then moves to the next file.
1.120 + *
1.121 + * @note Contents of buffers are undefined when returning false.
1.122 + * @note Both the '.' and '..' automatic directory entries will be retrieved for Windows and Linux.
1.123 + *
1.124 + * @param dir Handle to a directory.
1.125 + * @param buffer String buffer to hold directory name.
1.126 + * @param maxlength Maximum size of string buffer.
1.127 + * @param type Optional variable to store the file type.
1.128 + * @return True on success, false if there are no more files to read.
1.129 + * @error Invalid or corrupt Handle.
1.130 + */
1.131 +native bool:ReadDirEntry(Handle:dir, String:buffer[], maxlength, &FileType:type=FileType_Unknown);
1.132 +
1.133 +/**
1.134 + * Opens a file.
1.135 + *
1.136 + * @note Files are closed with CloseHandle().
1.137 + * @note File Handles can be cloned.
1.138 + * @note OpenFile() supports the "file://" notation.
1.139 + *
1.140 + * @param file File to open.
1.141 + * @param mode Open mode.
1.142 + * @return A Handle to the file, INVALID_HANDLE on open error.
1.143 + */
1.144 +native Handle:OpenFile(const String:file[], const String:mode[]);
1.145 +
1.146 +/**
1.147 + * Deletes a file.
1.148 + *
1.149 + * @param path Path of the file to delete.
1.150 + * @return True on success, false otherwise.
1.151 + */
1.152 +native bool:DeleteFile(const String:path[]);
1.153 +
1.154 +/**
1.155 + * Reads a line from a text file.
1.156 + *
1.157 + * @param hndl Handle to the file.
1.158 + * @param buffer String buffer to hold the line.
1.159 + * @param maxlength Maximum size of string buffer.
1.160 + * @return True on success, false otherwise.
1.161 + */
1.162 +native bool:ReadFileLine(Handle:hndl, String:buffer[], maxlength);
1.163 +
1.164 +/**
1.165 + * Reads binary data from a file.
1.166 + *
1.167 + * @param hndl Handle to the file.
1.168 + * @param items Array to store each item read.
1.169 + * @param num_items Number of items to read into the array.
1.170 + * @param size Size of each element, in bytes, to be read.
1.171 + * Valid sizes are 1, 2, or 4.
1.172 + * @return Number of elements read, or -1 on error.
1.173 + */
1.174 +native ReadFile(Handle:hndl, items[], num_items, size);
1.175 +
1.176 +/**
1.177 + * Reads a UTF8 or ANSI string from a file.
1.178 + *
1.179 + * @param hndl Handle to the file.
1.180 + * @param buffer Buffer to store the string.
1.181 + * @param max_size Maximum size of the string buffer.
1.182 + * @param stop If true, reading will stop once max_size-1 bytes have
1.183 + * been read. If false, reading will stop once a NUL
1.184 + * terminator is reached. The buffer will simply be
1.185 + * terminated in either case, the difference is in how
1.186 + * the far the file position is changed.
1.187 + * @return Number of characters written to the buffer, or -1
1.188 + * if an error was encountered.
1.189 + * @error Invalid Handle, or read_count > max_size.
1.190 + */
1.191 +native ReadFileString(Handle:hndl, String:buffer[], max_size, read_count=-1);
1.192 +
1.193 +/**
1.194 + * Writes binary data to a file.
1.195 + *
1.196 + * @param hndl Handle to the file.
1.197 + * @param items Array of items to write. The data is read directly.
1.198 + * That is, in 1 or 2-byte mode, the lower byte(s) in
1.199 + * each cell are used directly, rather than performing
1.200 + * any casts from a 4-byte number to a smaller number.
1.201 + * @param num_items Number of items in the array.
1.202 + * @param size Size of each item in the array in bytes.
1.203 + * Valid sizes are 1, 2, or 4.
1.204 + * @return True on success, false on error.
1.205 + * @error Invalid Handle.
1.206 + */
1.207 +native bool:WriteFile(Handle:hndl, const items[], num_items, size);
1.208 +
1.209 +/**
1.210 + * Writes a binary string to a file.
1.211 + *
1.212 + * @param hndl Handle to th efile.
1.213 + * @param buffer String to write.
1.214 + * @param term True to append NUL terminator, false otherwise.
1.215 + * @return True on success, false on error.
1.216 + * @error Invalid Handle.
1.217 + */
1.218 +native bool:WriteFileString(Handle:hndl, const String:buffer[], bool:term);
1.219 +
1.220 +/**
1.221 + * Writes a line of text to a text file. A newline is automatically appended.
1.222 + *
1.223 + * @param hndl Handle to the file.
1.224 + * @param format Formatting rules.
1.225 + * @param ... Variable number of format parameters.
1.226 + * @return True on success, false otherwise.
1.227 + * @error Invalid Handle.
1.228 + */
1.229 +native bool:WriteFileLine(Handle:hndl, const String:format[], any:...);
1.230 +
1.231 +/**
1.232 + * Reads a single binary cell from a file.
1.233 + *
1.234 + * @param hndl Handle to the file.
1.235 + * @param data Variable to store the data read.
1.236 + * @param size Size of the data to read in bytes. Valid
1.237 + * sizes are 1, 2, or 4 bytes.
1.238 + * @return Number of elements read (max 1), or -1 on error.
1.239 + * @error Invalid Handle.
1.240 + */
1.241 +stock ReadFileCell(Handle:hndl, &data, size)
1.242 +{
1.243 + new array[1], ret;
1.244 +
1.245 + if ((ret = ReadFile(hndl, array, 1, size)) == 1)
1.246 + {
1.247 + data = array[0];
1.248 + }
1.249 +
1.250 + return ret;
1.251 +}
1.252 +
1.253 +/**
1.254 + * Writes a single binary cell to a file.
1.255 + *
1.256 + * @param hndl Handle to the file.
1.257 + * @param data Cell to write to the file.
1.258 + * @param size Size of the data to read in bytes. Valid
1.259 + * sizes are 1, 2, or 4 bytes. If the size
1.260 + * is less than 4 bytes, the data is truncated
1.261 + * rather than casted. That is, only the lower
1.262 + * bits will be read.
1.263 + * @return True on success, false on error.
1.264 + * @error Invalid Handle.
1.265 + */
1.266 +stock bool:WriteFileCell(Handle:hndl, data, size)
1.267 +{
1.268 + new array[1];
1.269 +
1.270 + array[0] = data;
1.271 +
1.272 + return WriteFile(hndl, array, 1, size);
1.273 +}
1.274 +
1.275 +/**
1.276 + * Tests if the end of file has been reached.
1.277 + *
1.278 + * @param file Handle to the file.
1.279 + * @return True if end of file has been reached, false otherwise.
1.280 + * @error Invalid Handle.
1.281 + */
1.282 +native bool:IsEndOfFile(Handle:file);
1.283 +
1.284 +/**
1.285 + * Sets the file position indicator.
1.286 + *
1.287 + * @param file Handle to the file.
1.288 + * @param position Position relative to what is specified in whence.
1.289 + * @param where SEEK_ constant value of where to see from.
1.290 + * @return True on success, false otherwise.
1.291 + * @error Invalid Handle.
1.292 + */
1.293 +native bool:FileSeek(Handle:file, position, where);
1.294 +
1.295 +/**
1.296 + * Get current position in the file.
1.297 + *
1.298 + * @param file Handle to the file.
1.299 + * @return Value for the file position indicator.
1.300 + * @error Invalid Handle.
1.301 + */
1.302 +native FilePosition(Handle:file);
1.303 +
1.304 +/**
1.305 + * Checks if a file exists.
1.306 + *
1.307 + * @param path Path to the file.
1.308 + * @param use_valve_fs If true, the Valve file system will be used instead.
1.309 + * This can be used to check for the existance of files
1.310 + * inside GCFs or the game cache, rather than solely files
1.311 + * that are on disk.
1.312 + * @return True if the file exists, false otherwise.
1.313 + */
1.314 +native bool:FileExists(const String:path[], bool:use_valve_fs=false);
1.315 +
1.316 +/**
1.317 + * Renames a file.
1.318 + *
1.319 + * @param newpath New path to the file.
1.320 + * @param oldpath Path to the existing file.
1.321 + * @return True on success, false otherwise.
1.322 + */
1.323 +native bool:RenameFile(const String:newpath[], const String:oldpath[]);
1.324 +
1.325 +/**
1.326 + * Checks if a directory exists.
1.327 + *
1.328 + * @param path Path to the directory.
1.329 + * @return True if the directory exists, false otherwise.
1.330 + */
1.331 +native bool:DirExists(const String:path[]);
1.332 +
1.333 +/**
1.334 + * Get the file size in bytes.
1.335 + *
1.336 + * @param path Path to the file.
1.337 + * @return File size in bytes, -1 if file not found.
1.338 + */
1.339 +native FileSize(const String:path[]);
1.340 +
1.341 +/**
1.342 + * Flushes a file's buffered output; any buffered output
1.343 + * is immediately written to the file.
1.344 + *
1.345 + * @param file Handle to the file.
1.346 + * @return True on success, false on failure.
1.347 + */
1.348 +native FlushFile(Handle:file);
1.349 +
1.350 +/**
1.351 + * Removes a directory.
1.352 + * @note On most Operating Systems you cannot remove a directory which has files inside it.
1.353 + *
1.354 + * @param path Path to the directory.
1.355 + * @return True on success, false otherwise.
1.356 + */
1.357 +native bool:RemoveDir(const String:path[]);
1.358 +
1.359 +/**
1.360 + * Returns a file timestamp as a unix timestamp.
1.361 + *
1.362 + * @param file File name.
1.363 + * @param tmode Time mode.
1.364 + * @return Time value, or -1 on failure.
1.365 + */
1.366 +native GetFileTime(const String:file[], FileTimeMode:tmode);
1.367 +
1.368 +/**
1.369 + * Same as LogToFile(), except uses an open file Handle. The file must
1.370 + * be opened in text appending mode.
1.371 + *
1.372 + * @param hndl Handle to the file.
1.373 + * @param message Message format.
1.374 + * @param ... Message format parameters.
1.375 + * @noreturn
1.376 + * @error Invalid Handle.
1.377 + */
1.378 +native LogToOpenFile(Handle:hndl, const String:message[], any:...);
1.379 +
1.380 +/**
1.381 + * Same as LogToFileEx(), except uses an open file Handle. The file must
1.382 + * be opened in text appending mode.
1.383 + *
1.384 + * @param hndl Handle to the file.
1.385 + * @param message Message format.
1.386 + * @param ... Message format parameters.
1.387 + * @noreturn
1.388 + * @error Invalid Handle.
1.389 + */
1.390 +native LogToOpenFileEx(Handle:hndl, const String:message[], any:...);
1.391 +
