Posts: 1,046
Threads: 29
Joined: Mar 2010
12.06.2013, 16:19
(
Last edited by BigETI; 07/10/2013 at 07:22 PM.
)
[Include] file_ex.inc / file_ex_remote_def.inc / file_ex_remote.inc
FileEx (Extended file functions controlling and debugging script)
About
This include allows you to control or debug file functions known from file.inc, and gives you the opportunity to send error messages to other scripts. ( see FILE_EX_ENABLE_REMOTE! )
Why?
Because I still see people using the file functions wrongly or explaining people how to use them wrongly.
Someday it will cause to crash their servers, and mostly they don't know why it happens. (Such crashes can be still detected using the crashdetect plugin anyway...)
Also people with less knowledge can use this include to handle with server files much easily.
Documentation
Definitions
Needed definitions have to be defined like
pawn Code:
// Include based definitions...
#include <file_ex>
// Your script...
Quote:
|
FILE_EX_NO_TRACKING - Description:
- Disables all tracking features of this include.
- It makes result feedback and debugging useless.
- Usage:
-
pawn Code:
#define FILE_EX_NO_TRACKING
|
Quote:
|
FILE_EX_DEBUG_LEVEL - Description:
- Defines the current debug level your script should debug the file functions.
- Useless, if defined FILE_EX_NO_TRACKING.
- Levels:
- Level 0 (Default):
- Nothing will be debugged!
- Level 1:
- Functions like fopen, ftemp, fclose, fremove will be debugged.
- Level 2:
- All other file functions will be debugged, also the ones from level 1.
- Level 3 and above:
- Prints fwrite, fread, fputchar, fgetchar, fblockwrite, fblockread, fseek, fexist, and flenght inputs and outputs.
- Also does the same as level 2 and level 1.
- Usage:
- Example:
pawn Code:
#define FILE_EX_DEBUG_LEVEL 1
|
Quote:
|
FILE_EX_ENABLE_REMOTE - Description:
- Error reports will be send to other scripts.
- If needed use atleast a script with file_ex_remote.inc included
- Define FILE_EX_SCRIPT_ID with an unique ID to identify your script from your other scripts!
- Usage:
-
pawn Code:
#define FILE_EX_ENABLE_REMOTE
|
Quote:
|
FILE_EX_SCRIPT_ID - Description:
- Gives your script an unique ID to be indentified from other scripts
- Usage:
- Example:
-
pawn Code:
#define FILE_EX_SCRIPT_ID 5
|
Quote:
|
FILE_EX_FGETCHAR_FIX - Description:
- Fixes the native fgetchar's arguments.
- Removes the second useless argument.
- fgetchar(File:handle, bool:utf8 = true) instead of fgetchar(File:handle, value, bool:utf8 = true)
- Do not use this, if you get compatiblitiy issues with your script.
- Usage
-
pawn Code:
#define FILE_EX_FGETCHAR_FIX
|
Macros
Quote:
|
F_EX::file_read(const file_name[])<variable_name> - Description:
- Handles a file stream safely inside brackets.
- Read only mode!
- Much easier to open and close files.
- It does not require fclose inside, hence DO NOT USE THIS IN THIS CASE!
- Supports all file stream modes from file.inc
- "variable_name" defines the variable, which will hold the file stream handle.
- A variable in "variable_name" will be declared inside this macro, so do not declare a variable for this!
- Usage:
- Example:
pawn Code:
F_EX::file_read("example.txt")<example_txt_handle>
{
new buffer[128];
fread(example_txt_handle, buffer);
print(buffer);
}
|
Quote:
|
F_EX::file_write(const file_name[])<variable_name> - Description:
- Handles a file stream safely inside brackets.
- Write only mode!
- Much easier to open and close files.
- It does not require fclose inside, hence DO NOT USE THIS IN THIS CASE!
- Supports all file stream modes from file.inc
- "variable_name" defines the variable, which will hold the file stream handle.
- A variable in "variable_name" will be declared inside this macro, so do not declare a variable for this!
- Usage:
- Example:
pawn Code:
F_EX::file_write("example.txt")<example_txt_handle>
{
fwrite(example_txt_handle, "Hello world!\r\n");
}
|
Quote:
|
F_EX::file_readwrite(const file_name[])<variable_name> - Description:
- Handles a file stream safely inside brackets.
- Read and write mode.
- Much easier to open and close files.
- It does not require fclose inside, hence DO NOT USE THIS IN THIS CASE!
- Supports all file stream modes from file.inc
- "variable_name" defines the variable, which will hold the file stream handle.
- A variable in "variable_name" will be declared inside this macro, so do not declare a variable for this!
- Usage:
- Example:
pawn Code:
F_EX::file_readwrite("example.txt")<example_txt_handle>
{
fwrite(example_txt_handle, "Hello world!\r\n");
new buffer[128];
fread(example_txt_handle, buffer);
print(buffer);
}
|
Quote:
|
F_EX::file_append(const file_name[])<variable_name> - Description:
- Handles a file stream safely inside brackets.
- Append only mode!
- Much easier to open and close files.
- It does not require fclose inside, hence DO NOT USE THIS IN THIS CASE!
- Supports all file stream modes from file.inc
- "variable_name" defines the variable, which will hold the file stream handle.
- A variable in "variable_name" will be declared inside this macro, so do not declare a variable for this!
- Usage:
- Example:
pawn Code:
F_EX::file_append("example.txt")<example_txt_handle>
{
fwrite(example_txt_handle, "Hello world!\r\n");
}
|
Quote:
|
F_EX::temp_file<variable_name> - Description:
- Handles a temporary file stream safely inside brackets.
- Much easier to open and close temporary files.
- It does not require fclose inside, hence DO NOT USE THIS IN THIS CASE!
- Supports all file stream modes from file.inc
- "variable_name" defines the variable, which will hold the file stream handle.
- A variable in "variable_name" will be declared inside this macro, so do not declare a variable for this!
- Usage:
- Example:
pawn Code:
F_EX::temp_file<temp_file_handle>
{
new buffer = EOF;
F:EX::open_read("example.txt", example_txt_handle) while((buffer = fgetchar(example_txt_handle, 0, false)) != EOF) fputchar(temp_file_handle, false);
fseek(temp_file_handle);
F:EX::open_write("example2.txt", example2_txt_handle)
{
buffer = EOF;
while((buffer = fgetchar(temp_file_handle, 0, false)) != EOF) fputchar(example2_txt_handle, false);
}
}
|
Enums
Quote:
|
F_EX_RES::ENUM - Description:
- Used to identify specified results as numbers.
- Items:
- F_EX_RES::INV_FILE_ACCESS
- Result shows an invalid file access.
- F_EX_RES::INV_TEMP_FILE_ACCESS
- Result shows an invalid temporary file access.
- F_EX_RES::INV_FILE_S_PTR
- Result shows an invalid file pointer access.
- F_EX_RES::EOF
- Result shows that the end of a file has been reached.
|
Stocks
Quote:
|
stock F_EX_RES::ENUM: F_EX::get_result(bool:keep_result = true) - Description:
- Gets the last result ID.
- If bool:keep_result is true it will not reset the last result.
- Useless, if defined FILE_EX_NO_TRACKING.
- Usage:
- Example:
pawn Code:
F_EX::fopen_read("example.txt", my_file)
{
print("Current result: %d", _:F_EX::get_result();
}
|
Quote:
|
stock F_EX::print_result(bool:ignore_ok = true, bool:keep_result = true) - Description:
- Prints the last result properly into the console.
- Does not print in OK results, if bool:ignore_ok is set to true.
- If bool:keep_result is true it will not reset the last result.
- Useless, if defined FILE_EX_NO_TRACKING.
- Usage:
- Example:
pawn Code:
F_EX::fopen_read("example.txt", my_file)
{
F_EX::print_result(false);
}
|
Callbacks (Remote only)
Quote:
|
public OnFileExError(script_id, F_EX_RES::ENUM:result_id, func_name[], File:file_handle, msg[]) - Description:
- Gets called, if an error occurs at another script, which uses file.inc.
- Only usable, if the reporting script has remote error report enabled. ( FILE_EX_ENABLE_REMOTE )
- Usage:
- script_id
- The script ID of the sender, defined with FILE_EX_SCRIPT_ID.
- F_EX_RES::ENUM:result_id
- The result ID of the send issue. See F_EX_RES::ENUM
- func_name[]
- The function name the error was detected as string.
- File:file_handle
- The file handle the error was detected.
- msg[]
- Example:
pawn Code:
public OnFileExError(script_id, F_EX_RES::ENUM:result_id, func_name[], File:file_handle, msg[])
{
// ...
}
|
Hooked natives (without defining FILE_EX_NO_TRACKING)
pawn Code:
native File:fopen(const name[], filemode: mode = io_readwrite);
native bool:fclose(File: handle);
native File:ftemp();
native bool:fremove(const name[]);
native fwrite(File: handle, const string[]);
native fread(File: handle, string[], size = sizeof string, bool: pack = false);
native bool:fputchar(File: handle, value, bool: utf8 = true);
native fgetchar(File: handle, value, bool: utf8 = true);
native fblockwrite(File: handle, const buffer[], size = sizeof buffer);
native fblockread(File: handle, buffer[], size = sizeof buffer);
native fseek(File: handle, position = 0, seek_whence: whence = seek_start);
native flength(File: handle);
native fexist(const pattern[]);
Setup
Basic usage:
pawn Code:
// On top of your script
#include <file_ex> // Includes file_ex.inc
// ...
Enables file safety, and the usage of those macros.
Set debugging:
pawn Code:
// On top of your script
#define FILE_EX_DEBUG_LEVEL 1 // Sets debugging level
#include <file_ex> // Includes file_ex.inc
// ...
Basic debugging... See FILE_EX_DEBUG_LEVEL for more information!
Set no tracking:
pawn Code:
// On top of your script
#define FILE_EX_NO_TRACKING // Disables tracking feature
#include <file_ex> // Includes file_ex.inc
// ...
Disables file safety, removes hooks, and does not make the stocks usable at all. But it still allows you to use the macros.
Set remote:
pawn Code:
// MAIN SCRIPT!
// On top of your script
#define FILE_EX_ENABLE_REMOTE // Enables sending error messages to other scripts
#define FILE_EX_SCRIPT_ID 1 // unique script ID
#include <file_ex> // Includes file_ex.inc
// ...
pawn Code:
// Example script 2
// On top of your script
#define FILE_EX_ENABLE_REMOTE // Enables sending error messages to other scripts
#define FILE_EX_SCRIPT_ID 2 // unique script ID
#include <file_ex> // Includes file_ex.inc
// ...
pawn Code:
// Sniffer script
// On top of your script
#include <file_ex_remote> // Includes file_ex_remote.inc
// ...
public OnFileExError(script_id, F_EX_RES::ENUM:result_id, func_name[], File:file_handle, msg[])
{
// ...
}
Enables the ability to send error messages to other scripts.
Downloads
Changelog
Quote:
- v1.0 -> Initial release ( 12.06.2013 )
|
Credits
Quote:
- BigETI for these includes
- The ceators of file.inc and a_samp.inc
- ****** for the _ALS_ hooking method
|
Posts: 1,046
Threads: 29
Joined: Mar 2010
Added a sniffer filterscript to use the remote feature much easier.
Posts: 2,262
Threads: 260
Joined: Mar 2009
Reputation:
0
I'd quite like to see a directory file search function.
