SA-MP Forums Archive
[Include] FileEx (Extended file functions controlling and debugging script) - Printable Version

+- SA-MP Forums Archive (https://sampforum.blast.hk)
+-- Forum: SA-MP Scripting and Plugins (https://sampforum.blast.hk/forumdisplay.php?fid=8)
+--- Forum: Filterscripts (https://sampforum.blast.hk/forumdisplay.php?fid=17)
+---- Forum: Includes (https://sampforum.blast.hk/forumdisplay.php?fid=83)
+---- Thread: [Include] FileEx (Extended file functions controlling and debugging script) (/showthread.php?tid=443564)



FileEx (Extended file functions controlling and debugging script) - BigETI - 12.06.2013

[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::OK
      • Result is okay.
    • 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[]
      • Optional error message.
  • 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
Quote:
file_ex.inc
file_ex_remote_def.inc
file_ex_remote.inc
Quote:
file_ex_sniffer.pwn

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



Re: FileEx (Extended file functions controlling and debugging script) - daniel2499 - 12.06.2013

thanks you !


Re: FileEx (Extended file functions controlling and debugging script) - Niko_boy - 12.06.2013

good job!


AW: FileEx (Extended file functions controlling and debugging script) - BigETI - 28.08.2013

Added a sniffer filterscript to use the remote feature much easier.


Re: FileEx (Extended file functions controlling and debugging script) - Kyle - 28.08.2013

I'd quite like to see a directory file search function.