SA-MP Forums

Go Back   SA-MP Forums > SA-MP Scripting and Plugins > Filterscripts > Includes

Reply
 
Thread Tools Display Modes
Old 12/06/2013, 04:19 PM   #1
BigETI
Banned
 
Join Date: Mar 2010
Location: Germany
Posts: 1,053
Reputation: 359
Flowers FileEx (Extended file functions controlling and debugging script)

[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



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

Last edited by BigETI; 07/10/2013 at 07:22 PM.
BigETI is offline   Reply With Quote
Old 12/06/2013, 04:22 PM   #2
daniel2499
Little Clucker
 
Join Date: May 2012
Posts: 30
Reputation: -4
Default Re: FileEx (Extended file functions controlling and debugging script)

thanks you !
__________________
Well ..
daniel2499 is offline   Reply With Quote
Old 12/06/2013, 04:45 PM   #3
Niko_boy
High-roller
 
Niko_boy's Avatar
 
Join Date: Aug 2010
Location: Somewhere i belong
Posts: 1,338
Reputation: 138
Default Re: FileEx (Extended file functions controlling and debugging script)

good job!
__________________
nope[IMG]http://*******/1r0SOkH_[/IMG]
•••[CLOSED]LCS•Freeroam•DM•Stunts•••AutoArena [0.3z][No SkinShot][sixtytiger.com]Want a decent Attack Defend Gamemode?
N/A176.31.229.148:7830Get This! Attack-Defend(v2.3.1)
Niko_boy is offline   Reply With Quote
Old 28/08/2013, 11:23 AM   #4
BigETI
Banned
 
Join Date: Mar 2010
Location: Germany
Posts: 1,053
Reputation: 359
Default AW: FileEx (Extended file functions controlling and debugging script)

Added a sniffer filterscript to use the remote feature much easier.
BigETI is offline   Reply With Quote
Old 28/08/2013, 11:47 AM   #5
Kyle
High-roller
 
Join Date: Mar 2009
Location: United Kingdom
Posts: 2,277
Reputation: 330
Default Re: FileEx (Extended file functions controlling and debugging script)

I'd quite like to see a directory file search function.
Kyle is offline   Reply With Quote
Reply

Thread Tools
Display Modes

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off


Similar Threads
Thread Thread Starter Forum Replies Last Post
[Include] FCNPC Extended Functions Pottus Includes 3 27/05/2014 03:37 AM
File Functions + String Functions NoaM[W] Scripting Help 2 19/12/2012 08:13 PM
Help with File Functions! electrux Scripting Help 5 14/12/2012 12:26 PM
I/O functions file load from ini file razol Scripting Help 4 30/04/2012 01:21 PM
File Functions lansior34 Help Archive 0 18/08/2009 05:44 PM


All times are GMT. The time now is 11:38 AM.


Powered by vBulletin® Version 3.8.6
Copyright ©2000 - 2019, Jelsoft Enterprises Ltd.