FileOpen: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
No edit summary
m (Portuguese version indexed)
 
(6 intermediate revisions by 5 users not shown)
Line 1: Line 1:
__NOTOC__
__NOTOC__
{{Server client function}}
{{Server client function}}
Opens an existing file for reading and writing.
Opens an existing file for reading and writing.
 
{{Note|To prevent memory leaks, ensure each successful call to [[fileOpen]] has a matching call to [[fileClose]].}}
'''Note:''' The file functions should not be used to implement configuration files. It is encouraged to use the XML functions for this instead.
{{Tip|The file functions should not be used to implement configuration files. It is encouraged to use the XML functions for this instead.}}
{{MessageBox|bordercolorhex=FFB2B2|bgcolorhex=FFE5E5|image=File:Dialog-warning.png|title=Warning:|message=As of 1.5.4 [https://buildinfo.mtasa.com/?Author=&Branch=&Revision=10413 r10413], this function will fail when trying to access a script file of another resource, even with ''general.ModifyOtherObjects'' rights granted, which uses a ''mysql'' connection through [[dbConnect]] when [[Server_mtaserver.conf#database_credentials_protection|''database_credentials_protection'']] is enabled in the server configuration. Additionally, meta.xml will be un-writable and will always open in read-only mode.}} <!-- The {Warning} template didn't want to work with an external link to buildinfo, so I had to use the {MessageBox} template -->


==Syntax==
==Syntax==
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
file fileOpen ( string filePath [, bool readOnly = false ])
file fileOpen ( string filePath [, bool readOnly = false ])
</syntaxhighlight>
</syntaxhighlight>
{{OOP|The function will only attempt to open the file, it won't create it.|[[File]]}}


===Required Arguments===
{{New feature/item|9.0156|1.5.6|11865|
*'''filePath:''' The [[filepath]] of the file in the following format: '''":resourceName/path"'''. 'resourceName' is the name of the resource the file is in, and 'path' is the path from the root directory of the resource to the file.
{{OOP|This is a static function underneath the File class. Using '''File(...)''' to open a file will attempt to create the file, if it doesn't exist|[[File]].open}}
:For example, if there is a file named 'coolObjects.txt' in the resource 'objectSearch', it can be opened from another resource this way: ''fileOpen(":objectSearch/coolObjects.txt")''.
}}
:If the file is in the current resource, only the file path is necessary, e.g. ''fileOpen("coolObjects.txt")''.
 
===Optional Arguments===
*'''readOnly:''' By default, the file is opened with reading and writing access. You can specify ''true'' for this parameter if you only need reading access.
 
</section>
{{New feature|3.0110|1.1|
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
file fileOpen ( string filePath [, bool readOnly = false ] )
</syntaxhighlight>


===Required Arguments===
===Required Arguments===
Line 34: Line 23:
===Optional Arguments===
===Optional Arguments===
*'''readOnly:''' By default, the file is opened with reading and writing access. You can specify ''true'' for this parameter if you only need reading access.
*'''readOnly:''' By default, the file is opened with reading and writing access. You can specify ''true'' for this parameter if you only need reading access.
</section>
}}


===Returns===
===Returns===
Line 56: Line 43:
</syntaxhighlight>
</syntaxhighlight>


Notice that you can't simply do ''buffer = fileRead("test.txt", 500)''. Instead, file functions operate on a '''file handle''', which is a special object representing an open file. fileOpen gives us such a handle.
This example show how to append data to an existing file:
 
<syntaxhighlight lang="lua">
It is also important to remember to close a file after you've finished all your operations on it, especially if you've been writing to the file. If you don't close a file and your resource crashes, all changes to the file may be lost.
local hFile = fileOpen("test.txt")             -- attempt to open the file (read and write mode)
if hFile then                                  -- check if it was successfully opened
    fileSetPos( hFile, fileGetSize( hFile ) )  -- move position to the end of the file
    fileWrite(hFile, "hello" )                -- append data
    fileFlush(hFile)                          -- Flush the appended data into the file.
    fileClose(hFile)                          -- close the file once we're done with it
else
    outputConsole("Unable to open test.txt")
end
</syntaxhighlight>


==See Also==
==See Also==
{{File functions}}
{{File functions}}
[[pt-br:fileOpen]]

Latest revision as of 19:25, 20 December 2023

Opens an existing file for reading and writing.

[[{{{image}}}|link=|]] Note: To prevent memory leaks, ensure each successful call to fileOpen has a matching call to fileClose.
[[{{{image}}}|link=|]] Tip: The file functions should not be used to implement configuration files. It is encouraged to use the XML functions for this instead.
Dialog-warning.png Warning: As of 1.5.4 r10413, this function will fail when trying to access a script file of another resource, even with general.ModifyOtherObjects rights granted, which uses a mysql connection through dbConnect when database_credentials_protection is enabled in the server configuration. Additionally, meta.xml will be un-writable and will always open in read-only mode.

Syntax

file fileOpen ( string filePath [, bool readOnly = false ])

OOP Syntax Help! I don't understand this!

Note: The function will only attempt to open the file, it won't create it.
Method: File(...)


ADDED/UPDATED IN VERSION 1.5.6 r11865:

OOP Syntax Help! I don't understand this!

Note: This is a static function underneath the File class. Using File(...) to open a file will attempt to create the file, if it doesn't exist
Method: File.open(...)


Required Arguments

  • filePath: The filepath of the file in the following format: ":resourceName/path". 'resourceName' is the name of the resource the file is in, and 'path' is the path from the root directory of the resource to the file.
For example, if there is a file named 'coolObjects.txt' in the resource 'objectSearch', it can be opened from another resource this way: fileOpen(":objectSearch/coolObjects.txt").
If the file is in the current resource, only the file path is necessary, e.g. fileOpen("coolObjects.txt").

Optional Arguments

  • readOnly: By default, the file is opened with reading and writing access. You can specify true for this parameter if you only need reading access.

Returns

If successful, returns a file handle for the file. Otherwise returns false (f.e. if the file doesn't exist).

Example

This example opens the file test.txt that is in the root of the current resource, and outputs its contents to the console.

local hFile = fileOpen("test.txt", true)       -- attempt to open the file (read only)
if hFile then                                  -- check if it was successfully opened
    local buffer
    while not fileIsEOF(hFile) do              -- as long as we're not at the end of the file...
        buffer = fileRead(hFile, 500)          -- ... read the next 500 bytes...
        outputConsole(buffer)                  -- ... and output them to the console
    end
    fileClose(hFile)                           -- close the file once we're done with it
else
    outputConsole("Unable to open test.txt")
end

This example show how to append data to an existing file:

local hFile = fileOpen("test.txt")             -- attempt to open the file (read and write mode)
if hFile then                                  -- check if it was successfully opened
    fileSetPos( hFile, fileGetSize( hFile ) )  -- move position to the end of the file
    fileWrite(hFile, "hello" )                 -- append data
    fileFlush(hFile)                           -- Flush the appended data into the file.
    fileClose(hFile)                           -- close the file once we're done with it
else
    outputConsole("Unable to open test.txt")
end

See Also