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 * Reads binary data from a file.
164 * @param hndl Handle to the file.
165 * @param items Array to store each item read.
166 * @param num_items Number of items to read into the array.
167 * @param size Size of each element, in bytes, to be read.
168 * Valid sizes are 1, 2, or 4.
169 * @return Number of elements read, or -1 on error.
171 native ReadFile(Handle:hndl, items[], num_items, size);
174 * Reads a UTF8 or ANSI string from a file.
176 * @param hndl Handle to the file.
177 * @param buffer Buffer to store the string.
178 * @param max_size Maximum size of the string buffer.
179 * @param stop If true, reading will stop once max_size-1 bytes have
180 * been read. If false, reading will stop once a NUL
181 * terminator is reached. The buffer will simply be
182 * terminated in either case, the difference is in how
183 * the far the file position is changed.
184 * @return Number of characters written to the buffer, or -1
185 * if an error was encountered.
186 * @error Invalid Handle, or read_count > max_size.
188 native ReadFileString(Handle:hndl, String:buffer[], max_size, read_count=-1);
191 * Writes binary data to a file.
193 * @param hndl Handle to the file.
194 * @param items Array of items to write. The data is read directly.
195 * That is, in 1 or 2-byte mode, the lower byte(s) in
196 * each cell are used directly, rather than performing
197 * any casts from a 4-byte number to a smaller number.
198 * @param num_items Number of items in the array.
199 * @param size Size of each item in the array in bytes.
200 * Valid sizes are 1, 2, or 4.
201 * @return True on success, false on error.
202 * @error Invalid Handle.
204 native bool:WriteFile(Handle:hndl, const items[], num_items, size);
207 * Writes a binary string to a file.
209 * @param hndl Handle to th efile.
210 * @param buffer String to write.
211 * @param term True to append NUL terminator, false otherwise.
212 * @return True on success, false on error.
213 * @error Invalid Handle.
215 native bool:WriteFileString(Handle:hndl, const String:buffer[], bool:term);
218 * Writes a line of text to a text file. A newline is automatically appended.
220 * @param hndl Handle to the file.
221 * @param format Formatting rules.
222 * @param ... Variable number of format parameters.
223 * @return True on success, false otherwise.
224 * @error Invalid Handle.
226 native bool:WriteFileLine(Handle:hndl, const String:format[], any:...);
229 * Reads a single binary cell from a file.
231 * @param hndl Handle to the file.
232 * @param data Variable to store the data read.
233 * @param size Size of the data to read in bytes. Valid
234 * sizes are 1, 2, or 4 bytes.
235 * @return Number of elements read (max 1), or -1 on error.
236 * @error Invalid Handle.
238 stock ReadFileCell(Handle:hndl, &data, size)
242 if ((ret = ReadFile(hndl, array, 1, size)) == 1)
251 * Writes a single binary cell to a file.
253 * @param hndl Handle to the file.
254 * @param data Cell to write to the file.
255 * @param size Size of the data to read in bytes. Valid
256 * sizes are 1, 2, or 4 bytes. If the size
257 * is less than 4 bytes, the data is truncated
258 * rather than casted. That is, only the lower
260 * @return True on success, false on error.
261 * @error Invalid Handle.
263 stock bool:WriteFileCell(Handle:hndl, data, size)
269 return WriteFile(hndl, array, 1, size);
273 * Tests if the end of file has been reached.
275 * @param file Handle to the file.
276 * @return True if end of file has been reached, false otherwise.
277 * @error Invalid Handle.
279 native bool:IsEndOfFile(Handle:file);
282 * Sets the file position indicator.
284 * @param file Handle to the file.
285 * @param position Position relative to what is specified in whence.
286 * @param where SEEK_ constant value of where to see from.
287 * @return True on success, false otherwise.
288 * @error Invalid Handle.
290 native bool:FileSeek(Handle:file, position, where);
293 * Get current position in the file.
295 * @param file Handle to the file.
296 * @return Value for the file position indicator.
297 * @error Invalid Handle.
299 native FilePosition(Handle:file);
302 * Checks if a file exists.
304 * @param path Path to the file.
305 * @return True if the file exists, false otherwise.
307 native bool:FileExists(const String:path[]);
312 * @param newpath New path to the file.
313 * @param oldpath Path to the existing file.
314 * @return True on success, false otherwise.
316 native bool:RenameFile(const String:newpath[], const String:oldpath[]);
319 * Checks if a directory exists.
321 * @param path Path to the directory.
322 * @return True if the directory exists, false otherwise.
324 native bool:DirExists(const String:path[]);
327 * Get the file size in bytes.
329 * @param path Path to the file.
330 * @return File size in bytes, -1 if file not found.
332 native FileSize(const String:path[]);
335 * Flushes a file's buffered output; any buffered output
336 * is immediately written to the file.
338 * @param file Handle to the file.
339 * @return True on success, false on failure.
341 native FlushFile(Handle:file);
344 * Removes a directory.
345 * @note On most Operating Systems you cannot remove a directory which has files inside it.
347 * @param path Path to the directory.
348 * @return True on success, false otherwise.
350 native bool:RemoveDir(const String:path[]);
353 * Returns a file timestamp as a unix timestamp.
355 * @param file File name.
356 * @param tmode Time mode.
357 * @return Time value, or -1 on failure.
359 native GetFileTime(const String:file[], FileTimeMode:tmode);
362 * Same as LogToFile(), except uses an open file Handle. The file must
363 * be opened in text appending mode.
365 * @param hndl Handle to the file.
366 * @param message Message format.
367 * @param ... Message format parameters.
369 * @error Invalid Handle.
371 native LogToOpenFile(Handle:hndl, const String:message[], any:...);
374 * Same as LogToFileEx(), except uses an open file Handle. The file must
375 * be opened in text appending mode.
377 * @param hndl Handle to the file.
378 * @param message Message format.
379 * @param ... Message format parameters.
381 * @error Invalid Handle.
383 native LogToOpenFileEx(Handle:hndl, const String:message[], any:...);
