3 * =============================================================================
4 * SourceMod (C)2004-2007 AlliedModders LLC. All rights reserved.
5 * =============================================================================
7 * This file is part of the SourceMod/SourcePawn SDK.
9 * This program is free software; you can redistribute it and/or modify it under
10 * the terms of the GNU General Public License, version 3.0, as published by the
11 * Free Software Foundation.
13 * This program is distributed in the hope that it will be useful, but WITHOUT
14 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
15 * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
18 * You should have received a copy of the GNU General Public License along with
19 * this program. If not, see <http://www.gnu.org/licenses/>.
21 * As a special exception, AlliedModders LLC gives you permission to link the
22 * code of this program (as well as its derivative works) to "Half-Life 2," the
23 * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
24 * by the Valve Corporation. You must obey the GNU General Public License in
25 * all respects for all other code used. Additionally, AlliedModders LLC grants
26 * this exception to all derivative works. AlliedModders LLC defines further
27 * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
28 * or <http://www.sourcemod.net/license.php>.
33 #if defined _files_included
36 #define _files_included
39 * @global All paths in SourceMod natives are relative to the mod folder
40 * unless otherwise noted.
42 * Most functions in SourceMod (at least, ones that deal with direct
43 * file manipulation) will support an alternate path specification.
45 * If the path starts with the string "file://" and the PathType is
46 * not relative, then the "file://" portion is stripped off, and the
47 * rest of the path is used without any modification (except for
48 * correcting slashes). This can be used to override the path
49 * builder to supply alternate absolute paths. Examples:
51 * file://C:/Temp/file.txt
52 * file:///tmp/file.txt
60 FileType_Unknown = 0, /* Unknown file type (device/socket) */
61 FileType_Directory = 1, /* File is a directory */
62 FileType_File = 2, /* File is a file */
70 FileTime_LastAccess = 0, /* Last access (does not work on FAT) */
71 FileTime_Created = 1, /* Creation (does not work on FAT) */
72 FileTime_LastChange = 2, /* Last modification */
75 #define PLATFORM_MAX_PATH 256 /**< Maximum path length. */
77 #define SEEK_SET 0 /**< Seek from start. */
78 #define SEEK_CUR 1 /**< Seek from current position. */
79 #define SEEK_END 2 /**< Seek from end position. */
86 Path_SM, /**< SourceMod root folder */
90 * Builds a path relative to the SourceMod folder. This should be used instead of
91 * directly referencing addons/sourcemod, in case users change the name of their
94 * @param type Type of path to build as the base.
95 * @param buffer Buffer to store the path.
96 * @param maxlength Maximum length of buffer.
97 * @param fmt Format string.
98 * @param ... Format arguments.
99 * @return Number of bytes written to buffer (not including null terminator).
101 native BuildPath(PathType:type, String:buffer[], maxlength, const String:fmt[], any:...);
104 * Opens a directory/folder for contents enumeration.
106 * @note Directories are closed with CloseHandle().
107 * @note Directories Handles can be cloned.
108 * @note OpenDirectory() supports the "file://" notation.
110 * @param path Path to open.
111 * @return A Handle to the directory, INVALID_HANDLE on open error.
113 native Handle:OpenDirectory(const String:path[]);
116 * Reads the current directory entry as a local filename, then moves to the next file.
118 * @note Contents of buffers are undefined when returning false.
119 * @note Both the '.' and '..' automatic directory entries will be retrieved for Windows and Linux.
121 * @param dir Handle to a directory.
122 * @param buffer String buffer to hold directory name.
123 * @param maxlength Maximum size of string buffer.
124 * @param type Optional variable to store the file type.
125 * @return True on success, false if there are no more files to read.
126 * @error Invalid or corrupt Handle.
128 native bool:ReadDirEntry(Handle:dir, String:buffer[], maxlength, &FileType:type=FileType_Unknown);
133 * @note Files are closed with CloseHandle().
134 * @note File Handles can be cloned.
135 * @note OpenFile() supports the "file://" notation.
137 * @param file File to open.
138 * @param mode Open mode.
139 * @return A Handle to the file, INVALID_HANDLE on open error.
141 native Handle:OpenFile(const String:file[], const String:mode[]);
146 * @param path Path of the file to delete.
147 * @return True on success, false otherwise.
149 native bool:DeleteFile(const String:path[]);
152 * Reads a line from a text file.
154 * @param hndl Handle to the file.
155 * @param buffer String buffer to hold the line.
156 * @param maxlength Maximum size of string buffer.
157 * @return True on success, false otherwise.
159 native bool:ReadFileLine(Handle:hndl, String:buffer[], maxlength);
162 * Tests if the end of file has been reached.
164 * @param file Handle to the file.
165 * @return True if end of file has been reached, false otherwise.
167 native bool:IsEndOfFile(Handle:file);
170 * Sets the file position indicator.
172 * @param file Handle to the file.
173 * @param position Position relative to what is specified in whence.
174 * @param whence Look at the SEEK_* definitions.
175 * @return True on success, false otherwise.
177 native bool:FileSeek(Handle:file, position, whence);
180 * Get current position in the file.
182 * @param file Handle to the file.
183 * @return Value for the file position indicator.
185 native FilePosition(Handle:file);
188 * Checks if a file exists.
190 * @param path Path to the file.
191 * @return True if the file exists, false otherwise.
193 native bool:FileExists(const String:path[]);
198 * @param newpath New path to the file.
199 * @param oldpath Path to the existing file.
200 * @return True on success, false otherwise.
202 native bool:RenameFile(const String:newpath[], const String:oldpath[]);
205 * Checks if a directory exists.
207 * @param path Path to the directory.
208 * @return True if the directory exists, false otherwise.
210 native bool:DirExists(const String:path[]);
213 * Get the file size in bytes.
215 * @param path Path to the file.
216 * @return File size in bytes, -1 if file not found.
218 native FileSize(const String:path[]);
221 * Flushes a file's buffered output; any buffered output
222 * is immediately written to the file.
224 * @param file Handle to the file.
225 * @return True on success, false on failure.
227 native FlushFile(Handle:file);
230 * Removes a directory.
231 * @note On most Operating Systems you cannot remove a directory which has files inside it.
233 * @param path Path to the directory.
234 * @return True on success, false otherwise.
236 native bool:RemoveDir(const String:path[]);
239 * Writes a line of text in a file.
240 * @note This native will append the newline character.
242 * @param hndl Handle to the file.
243 * @param format Formatting rules.
244 * @param ... Variable number of format parameters.
245 * @return True on success, false otherwise.
247 native bool:WriteFileLine(Handle:hndl, const String:format[], any:...);
250 * Returns a file timestamp as a unix timestamp.
252 * @param file File name.
253 * @param tmode Time mode.
254 * @return Time value, or -1 on failure.
256 native GetFileTime(const String:file[], FileTimeMode:tmode);
259 * Same as LogToFile(), except uses an open file Handle. The file must
260 * be opened in text appending mode.
262 * @param hndl Handle to the file.
263 * @param message Message format.
264 * @param ... Message format parameters.
266 * @error Invalid Handle.
268 native LogToOpenFile(Handle:hndl, const String:message[], any:...);
271 * Same as LogToFileEx(), except uses an open file Handle. The file must
272 * be opened in text appending mode.
274 * @param hndl Handle to the file.
275 * @param message Message format.
276 * @param ... Message format parameters.
278 * @error Invalid Handle.
280 native LogToOpenFileEx(Handle:hndl, const String:message[], any:...);
