GetFileTime

Description

Retrieves the date and time that a file or directory was created, last accessed, and last modified.

C++ Syntax

PowerBASIC Syntax

Parameters

hFile

[in] A handle to the file or directory for which dates and times are to be retrieved. The handle must have been created using the CreateFile function with the GENERIC_READ access right.

lpCreationTime

[out, optional] A pointer to a FILETIME structure to receive the date and time the file or directory was created. This parameter can be NULL if the application does not require this information.

lpLastAccessTime

[out, optional] A pointer to a FILETIME structure to receive the date and time the file or directory was last accessed. The last access time includes the last time the file or directory was written to, read from, or, in the case of executable files, run. This parameter can be NULL if the application does not require this information.

lpLastWriteTime

[out, optional] A pointer to a FILETIME structure to receive the date and time the file or directory was last written to, truncated, or overwritten (for example, with WriteFile or SetEndOfFile). This date and time is not updated when file attributes or security descriptors are changed. This parameter can be NULL if the application does not require this information.

Return Value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Not all file systems can record creation and last access times and not all file systems record them in the same manner. For example, on FAT, create time has a resolution of 10 milliseconds, write time has a resolution of 2 seconds, and access time has a resolution of 1 day (really, the access date). Therefore, the GetFileTime function may not return the same file time information set using SetFileTime. NTFS delays updates to the last access time for a file by up to one hour after the last access.

For more information, see File Times.

If you rename or delete a file, then restore it shortly thereafter, Windows searches the cache for file information to restore. Cached information includes its short/long name pair and creation time.

Example

The following example uses the GetFileTime function to retrieve the last-write time for a file. It converts the time to local time based on the current time-zone settings, and creates a date and time string that can be shown to the user.

C++ code

#include <windows.h>

#include <tchar.h>

#include <strsafe.h>

// GetLastWriteTime - Retrieves the last-write time and converts

//                    the time to a string

//

// Return value - TRUE if successful, FALSE otherwise

// hFile      - Valid file handle

// lpszString - Pointer to buffer to receive string

BOOL GetLastWriteTime(HANDLE hFile, LPTSTR lpszString, DWORD dwSize)

{

  FILETIME ftCreate, ftAccess, ftWrite;

  SYSTEMTIME stUTC, stLocal;

  DWORD dwRet;

  // Retrieve the file times for the file.

  if (!GetFileTime(hFile, &ftCreate, &ftAccess, &ftWrite))

      return FALSE;

  // Convert the last-write time to local time.

  FileTimeToSystemTime(&ftWrite, &stUTC);

  SystemTimeToTzSpecificLocalTime(NULL, &stUTC, &stLocal);

  // Build a string showing the date and time.

  dwRet = StringCchPrintf(lpszString, dwSize,

      TEXT("%02d/%02d/%d  %02d:%02d"),

      stLocal.wMonth, stLocal.wDay, stLocal.wYear,

      stLocal.wHour, stLocal.wMinute);

  if( S_OK == dwRet )

      return TRUE;

  else return FALSE;

}

int _tmain(int argc, TCHAR *argv[])

{

  HANDLE hFile;

  TCHAR szBuf[MAX_PATH];

  if( argc != 2 )

  {

      printf("This sample takes a file name as a parameter\n");

      return 0;

  }

  hFile = CreateFile(argv[1], GENERIC_READ, FILE_SHARE_READ, NULL,

      OPEN_EXISTING, 0, NULL);

  if(hFile == INVALID_HANDLE_VALUE)

  {

      printf("CreateFile failed with %d\n", GetLastError());

      return 0;

  }

  if(GetLastWriteTime( hFile, szBuf, MAX_PATH ))

      _tprintf(TEXT("Last write time is: %s\n"), szBuf);

  CloseHandle(hFile);  

}

PowerBASIC code

#COMPILE EXE

#DIM ALL

#INCLUDE "windows.inc"

FUNCTION GetLastWriteTime (BYVAL hFile AS DWORD, BYREF strDateTime AS STRING) AS LONG

 LOCAL ftCreate, ftAccess, ftWrite AS FILETIME

 LOCAL stUTC, stLocal AS SYSTEMTIME

 ' // Retrieve the file times for the file.

 IF GetFileTime(hFile, ftCreate, ftAccess, ftWrite) = 0 THEN EXIT FUNCTION

 ' // Convert the last-write time to local time.

 FileTimeToSystemTime(ftWrite, stUTC)

 SystemTimeToTzSpecificLocalTime(BYVAL %NULL, stUTC, stLocal)

 ' // Build a string showing the date and time.

 IF ISMISSING(strDateTime) THEN EXIT FUNCTION

 strDateTime = FORMAT$(stLocal.wMonth) & "-" & FORMAT$(stLocal.wDay) & "-" & _

               FORMAT$(stLocal.wYear) & " " & FORMAT$(stLocal.wHour) & ":" & _

               FORMAT$(stLocal.wMinute)

 FUNCTION = %TRUE

END FUNCTION

FUNCTION PBMAIN () AS LONG

 LOCAL hFile AS DWORD

 LOCAL strBuf AS STRING

 LOCAL nError AS LONG

 ' // Change the file name as needed

 hFile = CreateFile("test.txt", %GENERIC_READ, %FILE_SHARE_READ, BYVAL %NULL, _

         %OPEN_EXISTING, 0, %NULL)

 IF hFile = %INVALID_HANDLE_VALUE THEN

    nError = GetLastError

    PRINT "CreateFile failed with ", nError

 ELSE

    IF GetLastWriteTime(hFile, strBuf) THEN

       PRINT "Last write time is: " & strBuf

    END IF

    CloseHandle(hFile)

 END IF

 WAITKEY$

END FUNCTION