GoFiler Legato Script Reference   Legato v 1.5d Application v 5.25a

Table of Contents	< < Previous	Next >>

 

Chapter Six — File Functions (continued)

GetFirstFile Function

Overview

The GetFirstFile function searches for the first file within a folder that matches a specified name and if a match is found, returns a handle to a Folder Enumeration Object.

Syntax/Parameters

Syntax

handle = GetFirstFile ( string name );

Parameters

name

A string containing a fully qualified path ending in a filename or wildcard mask. The filename portion of the name can include wildcard characters (for example, an asterisk (*) or a question mark (?)). This parameter supports UTF encoding for filenames with Unicode characters.

Return Value

Returns a handle to a Folder Enumeration Object or NULL_HANDLE on failure. Use the GetLastError function to retrieve error information.

Remarks

The GetFirstFile function opens a search object and loads information about the first file with a name that matches the specified pattern. This may or may not be the first file or directory that appears in a directory listing application (such as the “dir” command or in Windows Explorer) when given the same file name string pattern. The GetFirstFile function does not sort the search results.

The Folder Enumeration Object returned by the GetFirstFile function contains the first item in the folder that matches any wildcard match specified or the file if the name parameter contained a filename. In that case, the file specified by the name parameter is the only item in the object. The properties of the item can be retrieved with functions such as the GetFilename and GetFileSize functions. To move to the next entry in the folder, use the GetNextFile function.

Depending on the filename, the wildcard mask, and the file system to which the function is directed, one or two additional folders will be returned: ‘.’, which is the current folder, and ‘..’, which is the parent folder. It is up to the script to determine how to process these entries.

The GetFirstFile function does not currently support UNICODE.

Note: According to the Windows SDK, in rare cases or on a heavily loaded system, file attribute information on NTFS file systems may not be current at the time this function is called.

Related Functions

CloseHandle — Closes an object handle and releases any associated resources.

EnumerateFiles — Enumerates files with relative paths to an array.

EnumerateFolders — Enumerates folders with relative paths to an array.

GetName — Gets the name of an object or entry, value depends on the object handle type.

GetNextFile — Gets the next file from a list started with the GetFirstFile function.

GetFileAttributeBits — Gets file attributes as a bitwise set of flags from a specified handle or filename.

GetFileAttributeString — Gets file attributes in string form using a filename or handle for a file or an enumeration object.

GetFileCreateTime — Gets file creation time as a file time qword.

GetFileCreateTimeString — Gets file creation time as a string with optional date/time modes.

GetFileModifiedTime — Gets the file modified time as a file time qword.

GetFileModifiedTimeString — Gets file modified time as a string with optional date/time modes.

GetFileSize — Gets the size of a file from a file handle, file enumeration handle, folder, or FTP object.

Platform Support

Go13, Go16, GoFiler Complete, GoFiler Corporate, GoFiler, GoFiler Lite, GoXBRL

Legato IDE, Legato Basic

 

Table of Contents	< < Previous	Next >>

GoFiler Legato Script Reference — Generated on 12/16/2024

© 2012-2024 Novaworks, LLC. All rights reserved worldwide. Unauthorized use, duplication or transmission prohibited by law. Portions of the software are protected by US Patents 10,095,672, 10,706,221 and 11,210,456. GoFiler™ and Legato™ are trademarks of Novaworks, LLC. EDGAR® is a federally registered trademark of the U.S. Securities and Exchange Commission. Novaworks is not affiliated with or approved by the U.S. Securities and Exchange Commission. All other trademarks are property of their respective owners. Use of the features specified in this language are subject to terms, conditions and limitations of the Software License Agreement.