IoUtil.cpp

Go to the documentation of this file.

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
// Project: uLib - User mode library.
// Module: I/O utility functions (Migrated from UtilFunc.cpp)
// Author: Copyright (c) Love Nystrom
// License: NNOSL (BSD descendant, see NNOSL.txt in the base directory).
//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

#include <uLib/Common.h>
#include <uLib/UtilFunc.h>
#include <uLib/Debug.h>
#include <uLib/StrFunc.h>
#ifndef NO_NDK_FILES
#include <uLib/NtFunc.h> // GetLdrDllData()
#endif
#include <uLib/_Internal.h>

// TODO: GetFileNameFromHandle() ~ line 830
// TODO: GetNtDeviceName() ~ line 990

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
// I/O functions
//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

bool FileExist( CSTR pathName )
{
    DWORD attr = GetFileAttributes( pathName );
    return (attr != INVALID_FILE_ATTRIBUTES && (attr & FILE_ATTRIBUTE_DIRECTORY) == 0);
}

bool DirExist( CSTR pathName )
{
    DWORD attr = GetFileAttributes( pathName );
    return (attr != INVALID_FILE_ATTRIBUTES && BITS_SET( FILE_ATTRIBUTE_DIRECTORY, attr ));
}

//++---------------------------------------------------------------------------

bool IsDir( LPWIN32_FIND_DATA pFd )
{
    return (HAVE_BITS( pFd->dwFileAttributes, FILE_ATTRIBUTE_DIRECTORY ));
}

bool IsSubdirName( CSTR Dir )
{
    if (Dir[0] == DOT)
    {
        if (Dir[1] == 0) return false; // "." Current dir
        // The Dir[2] condition was added to pass ".nitwit" subdirectory names.
        if (Dir[1] == DOT && Dir[2] == 0) return false; // ".." Parent dir
        //TRACE( DP_VERBOSE, _F("--> %s\n"), Dir ); // ".dimfuckingunixname" directory detected
    }
    return true;
}

bool IsSubdir( LPWIN32_FIND_DATA pFd )
{
    return IsDir( pFd ) && IsSubdirName( pFd->cFileName );
}

//++---------------------------------------------------------------------------

CSTR GetTempPathName( CSTR Prefix, CSTR dotExt ) // Return full filepath name, with specific ext.
{
    static TCHAR pathname[ MAX_PATH ];

    UINT ext = UINT( IsString( dotExt ) ? _tcslen( dotExt ) + 1 : 0 );
    UINT max = dimof(pathname)-14-ext; // Reserve space for GetTempFileName and ext
    UINT len = GetTempPath( max, pathname );
    // Single buffer path/name concatenation.
    UINT rc = GetTempFileName( _T("\\"), Prefix, 0, &pathname[len-1] ); // Direct append
    if (rc && FileExist( pathname )) DeleteFile( pathname ); // If GetTempFileName created an empty file...

  BEGIN_STRSAFE_OVERRIDE
    TSTR pDot = _tcsrchr( pathname, DOT ); // ".tmp"
    if (pDot) { if (ext) _tcsecpy( pDot, dotExt ); else *pDot = 0; }
    else if (ext) _tcscat( pathname, dotExt );
  END_STRSAFE_OVERRIDE

    return pathname;
}

//++---------------------------------------------------------------------------

bool GetWin32FileData( CSTR PathName, LPWIN32_FIND_DATA pFd )
{
    bool ok = ((pFd != NULL) && IsString( PathName ));
    if (!ok) SetLastError( ERROR_INVALID_PARAMETER );
    else {
        IF_DEBUG( memset( pFd, 0, sizeof(WIN32_FIND_DATA) ));
        // Now get the WIN32_FIND_DATA.
        // Note: FindFirstFile doesn't accept a trailing backslash for directories.
        HANDLE hf = FindFirstFile( WithoutBackslash( PathName ), pFd );
        ok = (hf != INVALID_HANDLE_VALUE);
        if (ok) FindClose( hf );
    }
    return ok;
}

//++ SkipNamespacePrefix ++----------------------------------------------------

// TEST...
// ACSTR pzPath;
// pzPath = SkipPathPrefixA( LONG_UNC_PREFIX_A "_Eight" );
// pzPath = SkipPathPrefixA( LONG_PATH_PREFIX_A "_Four1" );
// pzPath = SkipPathPrefixA( DEVICE_NAME_PREFIX_A "_Four2" );
// pzPath = SkipPathPrefixA( UNPARSED_NAME_PREFIX_A "_Four3" );

ACSTR SkipPathPrefixA( ACSTR PathName )
{
    // With 8-bit chars we can turn this into fast integer comparisons ;)

    static const EIGHTCC _uncPfx =
        MK_EIGHTCC( LONG_UNC_PREFIX_A ); // ("\\?\UNC\") Same as "\\?\" but applies to UNC paths.
    static const FOURCC _knownFcc[3] =
    {
        MK_FOURCC( LONG_PATH_PREFIX_A ), // ("\\?\") Disable Win32 name parsing and override the MAX_PATH limit.
        MK_FOURCC( DEVICE_NAME_PREFIX_A ), // ("\\.\") A device in the Win32 device name space.
        MK_FOURCC( UNPARSED_NAME_PREFIX_A ), // ("\??\") "Non-parsed" path name (used for symlinks).
    };
    union { FOURCC* pfcc; EIGHTCC* pecc; };

    pfcc = (FOURCC*) PathName;
    if (*pecc == _uncPfx) PathName += 8;
    else for( UINT ix = 0; ix < 3; ++ix )
        if (*pfcc == _knownFcc[ix])
        {
            PathName += 4;
            break;
        }
    return PathName;
}

WCSTR SkipPathPrefixW( WCSTR PathName )
{
    #ifdef _UNICODE
      #define _TraceFmt _F("Skip '%s' prefix --> '%s'\n")
    #else
      #define _TraceFmt _F("Skip '%S' prefix --> '%S'\n")
    #endif
    struct _pfxRec { CCWSTR Text; WORD Len; }
    static const knownPfx[] =
    {
        { LONG_PATH_PREFIX_W, 4 },    // ("\\?\") Disable Win32 name parsing and override the MAX_PATH limit.
        { DEVICE_NAME_PREFIX_W, 4 },  // ("\\.\") A device in the Win32 device name space.
        { UNPARSED_NAME_PREFIX_W, 4 }, // ("\??\") "Non-parsed" path name.
        { LONG_UNC_PREFIX_W, 8 }      // ("\\?\UNC\") Same as "\\?\" but applies to UNC paths.
    };
    static const WORD nrPfx = dimof(knownPfx);

    for( WORD ix = 0; ix < nrPfx; ++ix )
        if (wcsncmp( PathName, knownPfx[ix].Text, knownPfx[ix].Len ) == 0)
        {
            PathName += knownPfx[ix].Len;
            TRACE( DP_VERBOSE, _TraceFmt, knownPfx[ix].Text, PathName );
            break;
        }
    return PathName;
    #undef _TraceFmt
}

//++ GetFileInformationByName ++-----------------------------------------------

bool GetFileInformationByName( CSTR FileName, LPBY_HANDLE_FILE_INFORMATION pInfo )
{
    bool ok = false;
    HANDLE hFile = CheckHandle( CreateFile(
        FileName, FILE_READ_ATTRIBUTES, FILE_SHARE_ALL, NULL,
        OPEN_EXISTING, FILE_FLAG_BACKUP_SEMANTICS, NULL
        ));
    if (hFile)
    {
        ok = bool_cast( GetFileInformationByHandle( hFile, pInfo ));
        CloseHandle( hFile );
    }
    return ok;
}

//++ GetVolumeGuidOfShare ++-------------------------------------------------------------

bool GetVolumeGuidOfShare(
    IN CSTR ShareName, OUT TSTR VolGuid, WORD ccGuid, OPTOUT TSTR DosDrv, WORD ccDrv )
{
    DWORD error = 0;
    WCHAR Server[80], Share[80];

    // Get the volume GUID of a UNC share, suitable for volume mounting.

    BOOL ok = SplitNetShareName(
        ShareName, Server, dimof(Server), Share, dimof(Share) );
    if (ok)
    {
      #ifdef _UNICODE
        #define wzVolGuid VolGuid
      #else
        WSTR wzVolGuid = mem_AllocWStr( ccGuid );
        ok = __ChkOkGetErr( wzVolGuid != NULL, &error );
      #endif
        if (ok)
        {
            PSHARE_INFO_2 psi = NULL;
            error = NetShareGetInfo( Server, Share, 2, (PBYTE*)&psi );
            if (ok = !error) // Assign and check ok after assignment.
            {
              #ifdef _UNICODE
                if (DosDrv) wcsncpyz( DosDrv, psi->shi2_path, ccDrv );
              #else
                if (DosDrv) WideCharToMultiByte(
                    CP_ACP,0, psi->shi2_path,-1, DosDrv, ccDrv, NULL, NULL );
              #endif

                // TODO: Check that this works with "unmounted" shares as well..
                // If not, then revise this to work with any defined share.

                ok = __ChkOkGetErr( GetVolumeNameForVolumeMountPointW(
                    psi->shi2_path, wzVolGuid, ccGuid
                    ), &error );
            }
          #ifndef _UNICODE
            WideCharToMultiByte( CP_ACP,0, wzVolGuid,-1, VolGuid, ccGuid, NULL, NULL );
            mem_Free( wzVolGuid );
          #endif
            if (psi) NetApiBufferFree( psi );
        }
    }
    if (!ok && error) SetLastError( error );
    return bool_cast( ok );
}

//++ GetVolumeGuidOfDevice ++------------------------------------------------------------

namespace { // Internal callback data
struct __gvg_Data {
    CSTR devName;         // in
    TSTR volGuid, dosDrv; // out
    WORD ccGuid, ccDrv;   // in
    };
} // End internal

static bool __gvgmatch_DevMapping( CSTR dosDev, CSTR devName )
{
    TCHAR Mapping[260];
    DWORD ccRtn = QueryDosDevice( dosDev, Mapping, dimof(Mapping) );
    return (ccRtn && (_tcsicmp( Mapping, devName ) == 0));
}

// PS: Don't get cute and try combining these two callbacks,
// they have different matching entries..

static bool __stdcall __gvgfind_DosVolGuid( TSTR dosDev, PVOID pData )
{
    bool found = false;
    if (_tcsnicmp( dosDev, _T("Volume"), 6 ) == 0)
    {
        __gvg_Data* pd = (__gvg_Data*) pData;
        found = __gvgmatch_DevMapping( dosDev, pd->devName );
        if (found) _stprintf_s( pd->volGuid, pd->ccGuid, _T("\\\\?\\%s\\"), dosDev );
    }
    return !found;
}

static bool __stdcall __gvgfind_DosDrive( TSTR dosDev, PVOID pData )
{
    bool found = false;
    if (dosDev[1] == COLON)
    {
        __gvg_Data* pd = (__gvg_Data*) pData;
        found = __gvgmatch_DevMapping( dosDev, pd->devName );
        if (found) _stprintf_s( pd->dosDrv, pd->ccDrv, _T("%s\\"), dosDev );
    }
    return !found;
}

bool GetVolumeGuidOfDevice(
    IN CSTR DevName, OUT TSTR VolGuid, WORD ccGuid, OPTOUT TSTR DosDrv, WORD ccDrv )
{
    *VolGuid = 0;
    static const int BufSize = 32*1024;
    TSTR DevList = mem_AllocStr( BufSize );
    if (DevList)
    {
        DWORD ccDev = QueryDosDevice( NULL, DevList, BufSize ); // The whole device list
        if (ccDev)
        {
            // PONDER: Detect and replace \\.\ prefix in DevName with \Device\ ..?

            __gvg_Data gvd = { DevName, VolGuid, DosDrv, ccGuid, ccDrv };

            EnumerateMultiSz( DevList, __gvgfind_DosVolGuid, &gvd );
            if (!*VolGuid) SetLastError( ERROR_FILE_NOT_FOUND ); //or ERROR_INVALID_NAME ?
            if (DosDrv) EnumerateMultiSz( DevList, __gvgfind_DosDrive, &gvd );
        }
        mem_Free( DevList );
    }
    return (*VolGuid != 0);
}

//++ GetFilePos/SetFilePos ++--------------------------------------------------

UINT64 GetFilePos( HANDLE hFile )
{
    LARGE_INTEGER fpos = {{0,0}};
    fpos.LowPart = SetFilePointer( hFile, 0, &fpos.HighPart, FILE_CURRENT );
    return fpos.QuadPart;
}

UINT64 SetFilePos( HANDLE hFile, INT64 Offset, UINT How )
{
    LARGE_INTEGER fpos;
    fpos.QuadPart = Offset;
    fpos.LowPart = SetFilePointer( hFile, fpos.LowPart, &fpos.HighPart, How );
    return fpos.QuadPart;
}

//++ Seek/Tell ++--------------------------------------------------------------

bool Seek( HANDLE hFile, LONG Offs, DWORD How )
{
    return (SetFilePointer( hFile, Offs, NULL, How ) != INVALID_SET_FILE_POINTER);
}

UINT Tell( HANDLE hFile )
{
    return SetFilePointer( hFile, 0, NULL, FILE_CURRENT );
}

//++ Get file size as full 64 bit value ++-------------------------------------

UINT64 GetFileSize64( HANDLE hFile )
{
    ULARGE_INTEGER fsize;
    // Symbolic link behavior —> Return the size of the target.
    fsize.LowPart = GetFileSize( hFile, &fsize.HighPart );
    return fsize.QuadPart;
}

UINT64 GetFileSize64Ex( CSTR FName )
{
    UINT64 size = 0;
    HANDLE hFile = CheckHandle( CreateFile( FName,
        FILE_READ_ATTRIBUTES, FILE_SHARE_ALL, NULL, OPEN_EXISTING,
        FILE_FLAG_BACKUP_SEMANTICS, NULL
        ));
    if (hFile)
    {
        size = GetFileSize64( hFile );
        CloseHandle( hFile );
    }
    return size;
}

//++ GetFileSizeByName ++------------------------------------------------------

#if (WINVER >= 0x0500) // GetFileAttributesEx arrived in Win2000
UINT64 GetFileSizeByName( CSTR FName )
{
    ULARGE_INTEGER fsize = {{ 0,0 }};
    WIN32_FILE_ATTRIBUTE_DATA fa;
    // Symbolic link behavior —> Return size of the link (0).
    if (GetFileAttributesEx( FName, GetFileExInfoStandard, &fa ))
    {
        fsize.LowPart = fa.nFileSizeLow;
        fsize.HighPart = fa.nFileSizeHigh;
    }
    return fsize.QuadPart;
}
#else
UINT64 GetFileSizeByName( CSTR FName )
{
    HANDLE hf;
    WIN32_FIND_DATA fd;
    ULARGE_INTEGER fsize = {{ 0,0 }};
    // Symbolic link behavior —> Return size of the link (0).
    hf = FindFirstFile( FName, &fd );
    if (hf) {
        fsize.LowPart = fd.nFileSizeLow;
        fsize.HighPart = fd.nFileSizeHigh;
        FindClose( hf );
    }
    return fsize.QuadPart;
}
#endif //(WINVER >= 0x0500)

//++ Open a FS directory ------------------------------------------------------

HANDLE OpenDirectory( CSTR DirPath, DWORD Flags )
{
    return CheckHandle( CreateFile(
        DirPath, GENERIC_RW, FILE_SHARE_RW, NULL,
        OPEN_EXISTING, Flags | FILE_FLAG_BACKUP_SEMANTICS, NULL
        ));
}

//++ IsEndOfFile ++------------------------------------------------------------

bool IsEndOfFile( HANDLE hFile )
{
    UINT64 fsize = GetFileSize64( hFile );
    UINT64 fpos = GetFilePos( hFile );
    return (fpos >= fsize); // Use >= as a precaution (if FS behaves strange).
}

//++ PeekFile ++---------------------------------------------------------------

UINT PeekFile( HANDLE hFile, PVOID Buf, UINT nBytes )
{
    DWORD cbRd;
    UINT64 fpos = GetFilePos( hFile );
    if (DWORD( fpos ) == INVALID_SET_FILE_POINTER && GetLastError() != 0)
        return 0;
    if (!ReadFile( hFile, Buf, nBytes, &cbRd, NULL )) cbRd = 0;
    SetFilePos( hFile, fpos, FILE_BEGIN );
    return (UINT) cbRd;
}

//++ BlockRead/BlockWrite ++---------------------------------------------------

UINT BlockRead( HANDLE hFile, PVOID Buf, UINT nBytes )
{
    DWORD cbRd;
    if (!ReadFile( hFile, Buf, nBytes, &cbRd, NULL )) cbRd = 0;
    return (UINT) cbRd;
}
UINT BlockWrite( HANDLE hFile, PVOID Buf, UINT nBytes )
{
    DWORD cbWr;
    if (!WriteFile( hFile, Buf, nBytes, &cbWr, NULL )) cbWr = 0;
    return (UINT) cbWr;
}

//++ WriteLine ++--------------------------------------------------------------

BOOL WriteLine( HANDLE hFile, CSTR Buf, UINT ccBuf )
{
    DWORD cb;
    static const TCHAR CrLf[2] = { CR,LF };

    if (!ccBuf) ccBuf = (UINT)_tcslen( Buf );
    #ifdef _UNICODE
    #if 1
      ccBuf += ccBuf; // We need the byte count, not the string length
    #else
      ccBuf *= WCHAR_SIZE; // If or when sizeof(WCHAR) > 2.
    #endif
    #endif
    BOOL ok = WriteFile( hFile, Buf, ccBuf, &cb, NULL );
    if (ok) ok = WriteFile( hFile, CrLf, sizeof(CrLf), &cb, NULL );
    return ok;
}

//++---------------------------------------------------------------------------

#if 0 // MEMO - To change behavior of C RTL nnn_s functions...
// Simple handler that prints on debugger, and doesn't terminate program.
void _dp_InvalidParamHandler(
    const wchar_t* expression, const wchar_t* function, const wchar_t* file,
    unsigned int line, uintptr_t _resv
    )
{
    WCHAR wzBuf[ 512 ];
    CHAR  szBuf[ dimof(wzBuf) ];
    int len = swprintf( wzBuf, dimof(wzBuf),
        L"Invalid parameter in function %s."
        L" File: %s Line: %d\n", function, file, line
        );
    WideCharToMultiByte( CP_ACP, 0, wzBuf,len+1, szBuf,dimof(szBuf), NULL, NULL );
    DPrint( DP_ERROR, szBuf );
}
_invalid_parameter_handler SetupInvalidParamHandler( bool noAssert )
{
    if (noAssert) _CrtSetReportMode( _CRT_ASSERT, 0 ); // Disable msg box for asserts
    return _set_invalid_parameter_handler( _dp_InvalidParamHandler );
}
#endif

//++ WriteStr ++---------------------------------------------------------------

#define _WRSTR_BUFLEN  512  // Design choice: Same as debugger's buffer size

UINT __cdecl WriteStrA( HANDLE hFile, IN const char* Fmt, ... )
{
    char buf[ _WRSTR_BUFLEN ];
    va_list va;
    DWORD cbWr;

    va_start( va, Fmt );
    int len = vsprintf_s( buf, dimof(buf), Fmt, va );
    va_end( va );
    if (!WriteFile( hFile, buf, len, &cbWr, NULL )) cbWr = 0;
    return cbWr;
}

UINT __cdecl WriteStrW( HANDLE hFile, const wchar_t* Fmt, ... )
{
    wchar_t buf[ _WRSTR_BUFLEN ];
    va_list va;
    DWORD cbWr;

    va_start( va, Fmt );
    int len = vswprintf_s( buf, dimof(buf), Fmt, va );
    va_end( va );
    if (!WriteFile( hFile, buf, len*sizeof(wchar_t), &cbWr, NULL )) cbWr = 0;
    else cbWr /= sizeof(wchar_t);
    return cbWr;
}

//++ ReadLine ++---------------------------------------------------------------

UINT ReadLineA( HANDLE hFile, char* Buffer, UINT BufSize, bool TrimCrLf )
{
    DWORD cbRd;
    static const char _LF_ = '\n'; // Override global LF (in case of Unicode build).
    static const char _CR_ = '\r'; // -"- CR
    UINT len = 0; // Return value
    DWORD err = 0; // On error
    LARGE_INTEGER fpos = {{0,0}}; // Remember file position

    fpos.LowPart = SetFilePointer( hFile, 0, &fpos.HighPart, FILE_CURRENT );
    if (fpos.LowPart == INVALID_SET_FILE_POINTER) return 0;

    if (!ReadFile( hFile, Buffer, BufSize, &cbRd, NULL )) {
        err = GetLastError();
        // It is not documented whether ReadFile leaves the the file pointer
        // status quo on all failures, so take the safe road and restore it.
        // >> SetFilePointer done below!
    } else {
        if (cbRd == 0) { // Windows only return EOF as an error if OVERLAPPED!
            // Make life easier for programmers by translating the EOF condition.
            Buffer[0] = 0; // Terminate the buffer.
            err = ERROR_HANDLE_EOF;
            goto exit_ReadLineA;
        }
        Buffer[ cbRd-1 ] = 0; // Terminate the buffer.
        #ifdef _MBCS // MultiByte build
          char* end = (char*)_mbschr( (unsigned char*)Buffer, _LF_ );
        #else
          char* end = strchr( Buffer, _LF_ );
        #endif
        if (!end) {
            if (IsEndOfFile( hFile )) { // Are we actually at end of file?
                end = Buffer + cbRd-1;
                goto readlna_HaveData;
            } else {
                err = ERROR_INSUFFICIENT_BUFFER;
                // Restore file pointer so caller can retry with a bigger buffer.
                // >> SetFilePointer done below!
            }
        } else {
            *(end+1) = 0; // Terminate after LF. (Safe due to Buffer[cbRd-1] = 0).
        readlna_HaveData:
            len = 1 + UINT( end - Buffer ); // Nr of chars incl [CR]LF
            if (TrimCrLf) {
                *end-- = 0; // Cut LF
                if (*end == _CR_) *end = 0; // Cut CR, if any
            }
            // Update file pos to next line after CRLF.
            fpos.QuadPart += len; // SetFilePointer done below!
        }
    }
    SetFilePointer( hFile, fpos.LowPart, &fpos.HighPart, FILE_BEGIN );
exit_ReadLineA:
    if (err) SetLastError( err );
    return len;
}

UINT ReadLineW( HANDLE hFile, wchar_t* Buffer, UINT BufLength, bool TrimCrLf )
{
    DWORD cbRd, cchRd, cbBuf;
    static const wchar_t _LF_ = L'\n'; // Override the global, since this may be a Ansi build.
    static const wchar_t _CR_ = L'\r'; // -"-
    UINT len = 0; // Return value
    DWORD err = 0; // On error

    LARGE_INTEGER fpos = {{0,0}}; // Remember file position
    fpos.LowPart = SetFilePointer( hFile, 0, &fpos.HighPart, FILE_CURRENT ); // GetFilePointer
    if (fpos.LowPart == INVALID_SET_FILE_POINTER) return 0;

    cbBuf = BufLength * sizeof(wchar_t);
    if (!ReadFile( hFile, Buffer, cbBuf, &cbRd, NULL )) {
        err = GetLastError();
    } else {
        if (cbRd == 0) {
            err = ERROR_HANDLE_EOF;
            Buffer[0] = 0; // Terminate the buffer.
            goto exit_ReadLineW;
        }
        cchRd = cbRd / sizeof(wchar_t);
        Buffer[ cchRd-1 ] = 0; // Terminate the buffer.
        wchar_t* end = wcschr( Buffer, _LF_ );
        if (!end) {
            if (IsEndOfFile( hFile )) { // Are we actually at end of file?
                end = Buffer + cchRd-1;
                goto readlnw_HaveData;
            } else {
                err = ERROR_INSUFFICIENT_BUFFER;
            }
        } else {
            *(end+1) = 0; // Terminate after LF. Safe due to Buffer[cbRd-1] = 0.
        readlnw_HaveData:
            len = 1 + UINT( end - Buffer ); // Nr of wchars incl CRLF
            if (TrimCrLf) {
                *end-- = 0; // Cut LF
                if (*end == _CR_) *end = 0; // Cut CR, if any
            }
            fpos.QuadPart += (len * sizeof(wchar_t)); // Update file pos to next line after CRLF.
        }
    }
    SetFilePointer( hFile, fpos.LowPart, &fpos.HighPart, FILE_BEGIN );
exit_ReadLineW:
    if (err) SetLastError( err );
    return len;// / sizeof(wchar_t);
}

//++ GetPathFileName gets a ptr to the filname.ext part of PathName -----------

// NOTE: Do not use GetPathFileName for pathnames without a filename part.
// If PathName denotes just a directory with no ending BSLASH, you'll get
// a pointer to the terminal directory, (if present) which is
// probably not what you want.

TSTR GetPathFileName( TSTR PathName )
{
    TSTR fname = PathName ? _tcsrchr( PathName, BSLASH ) : NULL;
    if (fname) fname++; else fname = PathName;
    return fname;
}

//++ GetFullFilePath - Get full path name of the file ++-----------------------


// AGH: SearchPath does NOT produce the correct drive char !!

//UINT GetFullFilePath( CSTR Name, TSTR pathBuf, UINT bufSize )
//{
//    CSTR pDetail = _tcsrchr( Name, BSLASH );
//    if (!pDetail) // No backslash, it's a filname only
//        return SearchPath( NULL, Name, NULL, bufSize, pathBuf, (TSTR*)&pDetail );
//    else { // The name contains a path spec - Just check file exist
//        if (!FileExist( Name )) {
//            SetLastError( ERROR_FILE_NOT_FOUND );
//            return 0;
//        }
//        UINT len = (UINT)_tcslen( Name );
//        if (len >= bufSize) {
//            SetLastError( ERROR_INSUFFICIENT_BUFFER );
//            return 0;
//        }
//        _tcsncpyz( pathBuf, Name, dimof(pathBuf) );
//        return len;
//    }
//}

//++ GetFileNameFromHandle ++--------------------------------------------------

#if WINVER >= 0x600 // Vista++

UINT GetFileNameFromHandle( HANDLE hFile, TSTR Buffer, UINT BufLen )
// Alphatest passed
{
    UINT ccName = GetFinalPathNameByHandle( hFile, Buffer, BufLen, VOLUME_NAME_DOS );
    if (ccName && (BufLen >= ccName))
    {
        CSTR pzPath = SkipPathPrefix( Buffer ); // I don't want a leading "\\?\".
        UINT ccPfix = (UINT) CharIndex( Buffer, pzPath );
        if (ccPfix)
        {
            ccName -= ccPfix;
            _tcsncpyz( Buffer, pzPath, min_<UINT>( ccName+1, BufLen )); // Remove prefix
        }
        Buffer[0] = _totupper( Buffer[0] ); // Upper case  drive letter looks better.
    }
    return ccName;
}

#elif !defined( NO_NDK_FILES )

// Credits to Mehrdad@stackoverflow.com for pointing out MountPointManager.
#include <ddk/MountMgr.h> // Need the MountPointManager here..

BEGIN_STRSAFE_OVERRIDE
#pragma warning( disable: 4244 4267 ) // cvt from <larger> to 'USHORT'...

UINT GetFileNameFromHandle( HANDLE hFile, TSTR PathName OUT, UINT ccPathName )
// Alphatest pending
{
    UINT ccName = 0;
    if (!_NtQueryInformationFile) InitNtFunc();
    if (_NtQueryInformationFile && _NtQueryObject)
    {
        static const USHORT MAX_UNIBUF = (MAX_PATH + 1) * WCHAR_SIZE;
        // Total buffer size slightly over 2 kB stack space :/
        BYTE objBuf [ sizeof(OBJECT_NAME_INFORMATION) + MAX_UNIBUF ] = {0}; // OBJECT_NAME_INFORMATION
        BYTE nameBuf[ sizeof(FILE_NAME_INFORMATION) + MAX_UNIBUF ] = {0};   // FILE_NAME_INFORMATION
        BYTE trgBuf [ sizeof(MOUNTMGR_TARGET_NAME) + MAX_UNIBUF ] = {0};    // MOUNTMGR_TARGET_NAME
        BYTE pathBuf[ sizeof(MOUNTMGR_VOLUME_PATHS) + MAX_UNIBUF ] = {0};   // MOUNTMGR_VOLUME_PATHS

        POBJECT_NAME_INFORMATION objInfo = (POBJECT_NAME_INFORMATION) objBuf;
        PFILE_NAME_INFORMATION fileInfo = (PFILE_NAME_INFORMATION) nameBuf;
        PMOUNTMGR_TARGET_NAME trgName = (PMOUNTMGR_TARGET_NAME) trgBuf;
        PMOUNTMGR_VOLUME_PATHS trgPath = (PMOUNTMGR_VOLUME_PATHS) pathBuf;

        INIT_PACKED_UNICODE_STRING( &objInfo->Name, sizeof(objBuf) );

        IO_STATUS_BLOCK ioStat = {0};
        NTSTATUS rc;
        ULONG   cbData;

        rc = _NtQueryObject( // Path including disk volume device name.
            hFile, ObjectNameInformation, objInfo, sizeof(objBuf), &cbData
            );
        if (NT_ERROR( rc ))
        {
            SetLastErrorFromNtStatus( rc );
            TRACE( DP_ERROR, _F("NtQueryObject: %s\n"), SysErrorMsg() );
        }
        else
        {
            rc = _NtQueryInformationFile( // File pathname relative to disk volume.
                hFile, &ioStat, fileInfo, sizeof(nameBuf), FileNameInformation
                );
            if (NT_ERROR( rc ))
            {
                SetLastErrorFromNtStatus( rc );
                TRACE( DP_ERROR, _F("NtQueryInformationFile: %s\n"), SysErrorMsg() );
            }
            else if (objInfo->Name.Length <= fileInfo->FileNameLength) // Sanity check
            {
                SetLastError( ERROR_INTERNAL_ERROR );
                TRACE( DP_ERROR, _F("%s. Please contact uLib maintenance.\n"), SysErrorMsg() );
            }
            else
            {
                trgName->DeviceNameLength = objInfo->Name.Length - fileInfo->FileNameLength;
                USHORT ccTrg = trgName->DeviceNameLength / WCHAR_SIZE;
                wcsncpy( trgName->DeviceName, objInfo->Name.Buffer, ccTrg );

                // PONDER: [MSHDC] "If the user has 'SeChangeNotifyPrivilege'
                // NtQueryInformationFile returns the full path in all cases."
                // That would make trgName->DeviceNameLength zero and trgName->DeviceName
                // blank, which would cause the following code to malfunction...
                // Hence the ERROR_INTERNAL_ERROR fail-safe above.
                // TODO: Check if it's true, and if so, FIXME.

                static CCSTR S_MountMgr = _T("\\\\.\\MountPointManager");
                HANDLE hMountPointMgr = CheckHandle( CreateFile(
                    S_MountMgr, 0, FILE_SHARE_ALL, NULL, OPEN_EXISTING, 0, NULL
                    ));
                if (hMountPointMgr)
                {
                    DWORD cbRtn;
                    BOOL ok = DeviceIoControl(
                        hMountPointMgr, IOCTL_MOUNTMGR_QUERY_DOS_VOLUME_PATH,
                        trgName, sizeof(trgBuf), trgPath, sizeof(pathBuf),
                        &cbRtn, NULL
                        );
                    TRACE_IF( !ok, DP_ERROR, _F("DeviceIoControl: %s\n"), SysErrorMsg() );
                    if ( ok )
                    {
                        USHORT ccDrv = (trgPath->MultiSzLength / WCHAR_SIZE) - 2; // Exclude 2 NUL chars
                        USHORT ccFile = fileInfo->FileNameLength / WCHAR_SIZE;
                        ccName = ccDrv + ccFile;
                      #ifdef _UNICODE
                        WSTR wzName = wcsnecpy( PathName, trgPath->MultiSz, ccDrv );
                        wcsncpyz( wzName, fileInfo->FileName, ccPathName-ccDrv );
                      #else
                        WideCharToMultiByte( CP_ACP, 0,
                            trgPath->MultiSz, ccDrv, PathName, ccPathName, NULL, NULL
                            );
                        WideCharToMultiByte( CP_ACP, 0,
                            fileInfo->FileName, ccFile, &PathName[ccDrv], ccPathName-ccDrv, NULL, NULL
                            );
                      #endif
                    }
                    CloseHandleEx( hMountPointMgr );
                }
            }
        }
    }
    return ccName;
}
#pragma warning( default: 4244 4267 )
END_STRSAFE_OVERRIDE

#else // WINVER < 0x600 || NO_NDK_FILES // E.g. XP/ReactOS/Wine, or no NDK

UINT GetFileNameFromHandle( HANDLE hFile, TSTR Buffer, UINT BufLength )
// Alphatest pending
{
    UINT ccPath = 0;

    // Create a file mapping object and map it
    // so we can query the name the address belongs to.

    HANDLE hFileMap = CreateFileMapping( hFile, NULL, PAGE_READONLY, 0, 0, NULL );
    if (hFileMap)
    {
        PVOID pMem = MapViewOfFile( hFileMap, FILE_MAP_READ, 0, 0, 1 );
        if (pMem)
        {
            // GetMappedFileName returns a /device/ path name from object manager,
            // e.g. "\Device\HarddiskVolume2\somepath\file.ext", which we translate.

            if (GetMappedFileName( GetCurrentProcess(), pMem, Buffer, BufLength-1 ))
            {
                UINT ccDrvPath = DevicePathToDosPath( Buffer, Buffer, BufLength );
                ccPath = ccDrvPath ? ccDrvPath : (UINT)_tcslen( Buffer );
            }
            UnmapViewOfFile( pMem );
        }
        CloseHandle( hFileMap );
    }
    return ccPath;
}

#endif // WINVER < 0x600 || NO_NDK_FILES

#ifndef NO_NDK_FILES // Under consideration -- Might migrate to nLib..
#ifndef NO_WINTERNAL // UNICODE_STRING
//++ GetNtDeviceName ++--------------------------------------------------------

// "\Device\Harddisk1"                                      (Harddisk Drive)
// "\Device\HarddiskVolume3"                                (Harddisk Partition)
// "\Device\HarddiskVolume3\Temp"                           (Harddisk Directory)
// "\Device\HarddiskVolume3\Temp\transparent.jpeg"          (Harddisk File)
// "\Device\Harddisk1\DP(1)0-0+6\foto.jpg"                  (USB stick (Ambiguous))
// "\Device\TrueCryptVolumeP\Data\Passwords.txt"            (Truecrypt Volume)
// "\Device\Floppy0\Autoexec.bat"                           (Floppy disk)
// "\Device\CdRom1\VIDEO_TS\VTS_01_0.VOB"                   (DVD drive)
// "\Device\Serial1"                                        (Real COM port)
// "\Device\USBSER000"                                      (Virtual COM port)
// "\Device\Mup\ComputerName\C$\Boot.ini"                   (Network drive share,  Windows 7)
// "\Device\LanmanRedirector\ComputerName\C$\Boot.ini"      (Network drive share,  Windwos XP)
// "\Device\LanmanRedirector\ComputerName\Shares\Dance.m3u" (Network folder share, Windwos XP)
// "\Device\Afd"                                            (Internet socket)
// "\Device\Console000F"                                    (Unique name for any Console handle)
// "\Device\NamedPipe\Pipename"                             (Named pipe)
// "\BaseNamedObjects\Objectname"                           (Named mutex, named event, named semaphore)
// "\REGISTRY\MACHINE\SOFTWARE\Classes\.txt"                (HKEY_CLASSES_ROOT\.txt)

#define IsConsoleHandle(h) (( ULONG_PTR(h) & 0x10000003 ) == 0x3 )

UINT GetNtDeviceName( HANDLE hObj, TSTR pzNTPath, UINT ccNTPath )
// Alphatest ok so far
{
    UINT ccPath = 0;
    if (pzNTPath) *pzNTPath = 0;

    if (BAD_HANDLE( hObj )) SetLastError( ERROR_INVALID_HANDLE );
    else if (!pzNTPath || !ccNTPath) SetLastError( ERROR_INVALID_PARAMETER );
    else
    {
        if (!_NtQueryObject) InitNtFunc();

        // NtQueryObject() returns STATUS_INVALID_HANDLE for Console handles
        if (IsConsoleHandle( hObj ))
        {
            return _stprintf_s( pzNTPath, ccNTPath, _T("\\Device\\Console%04X"), (DWORD_PTR)hObj );
            // PONDER: Should this include the \Sessions\x\ component seen on other handles..?
        }

        // Native (and kernel) parameters are teeedious.. sigh :/
        BYTE Buffer[ sizeof(OBJECT_NAME_INFORMATION) + (MAX_PATH+1)*WCHAR_SIZE ];
        IF_DEBUG( memset( Buffer, 0, sizeof(Buffer) ));
        POBJECT_NAME_INFORMATION objInfo = (POBJECT_NAME_INFORMATION) Buffer;
        INIT_PACKED_UNICODE_STRING( &objInfo->Name, sizeof(Buffer) );
        DWORD cbData = 0;

        NTSTATUS rc = _NtQueryObject(
            hObj, ObjectNameInformation, objInfo, sizeof(Buffer), &cbData
            );
        if (NT_ERROR( rc )) SetLastErrorFromNtStatus( rc );
        else if (!objInfo->Name.Length) SetLastError( ERROR_NOT_FOUND );
        else
        {
            ccPath = objInfo->Name.Length / WCHAR_SIZE;
            objInfo->Name.Buffer[ ccPath ] = 0;

          #ifdef _UNICODE
            wcsncpyz( pzNTPath, objInfo->Name.Buffer, ccNTPath );
          #else
            WideCharToMultiByte( CP_ACP, 0,
                objInfo->Name.Buffer, -1, pzNTPath, ccNTPath, NULL, NULL );
          #endif
        }
    }
    return ccPath;
}

#endif//ndef NO_WINTERNAL
#endif//ndef NO_NDK_FILES

#if 1 // PONDER: GetDosNameFromNtDeviceName() could stand an overhaul..
// "\Device\HarddiskVolume3"                                -> "E:"
// "\Device\HarddiskVolume3\Temp"                           -> "E:\Temp"
// "\Device\HarddiskVolume3\Temp\transparent.jpeg"          -> "E:\Temp\transparent.jpeg"
// "\Device\Harddisk1\DP(1)0-0+6\foto.jpg"                  -> "I:\foto.jpg"
// "\Device\TrueCryptVolumeP\Data\Passwords.txt"            -> "P:\Data\Passwords.txt"
// "\Device\Floppy0\Autoexec.bat"                           -> "A:\Autoexec.bat"
// "\Device\CdRom1\VIDEO_TS\VTS_01_0.VOB"                   -> "H:\VIDEO_TS\VTS_01_0.VOB"
// "\Device\Serial1"                                        -> "COM1"
// "\Device\USBSER000"                                      -> "COM4"
// "\Device\Mup\ComputerName\C$\Boot.ini"                   -> "\\ComputerName\C$\Boot.ini"
// "\Device\LanmanRedirector\ComputerName\C$\Boot.ini"      -> "\\ComputerName\C$\Boot.ini"
// "\Device\LanmanRedirector\ComputerName\Shares\Dance.m3u" -> "\\ComputerName\Shares\Dance.m3u"

DWORD GetDosNameFromNtDeviceName( CSTR NtName, TSTR DosName, UINT ccDosName )
{
    DWORD err = 0;
    HKEY hKey;
    TCHAR szTemp[ MAX_PATH ];
    TSTR pzCat; // Concatenator

    if (_tcsnicmp( NtName, _T("\\Device\\Serial"), 14 ) == 0 // e.g. "Serial1"
    || _tcsnicmp( NtName, _T("\\Device\\UsbSer"), 14 ) == 0) // e.g. "USBSER000"
    {
        err = RegOpenKeyEx( HKEY_LOCAL_MACHINE,
            _T("Hardware\\DeviceMap\\SerialComm"),0, KEY_QUERY_VALUE, &hKey );
        if (!err)
        {
            DWORD type, size = sizeof(szTemp);
            err = RegQueryValueEx( hKey, NtName, 0, &type, (PBYTE)szTemp, &size );

            if (err) err = ERROR_UNKNOWN_PORT;
            else _tcsncpyz( DosName, szTemp, ccDosName );
            RegCloseKey( hKey );
        }
    }
    //"HKLM\HARDWARE\DEVICEMAP\PARALLEL PORTS"
    //"HKLM\HARDWARE\DEVICEMAP\PARALLEL PORTS\\\Device\Parallel0"
    else if (_tcsnicmp( NtName, _T("\\Device\\LanmanRedirector\\"), 25 ) == 0) // Win XP
    {
        pzCat = _tcsecpy( DosName, _T("\\\\") );
        _tcsncpyz( pzCat, &NtName[25], ccDosName - 2 );
    }
    else if (_tcsnicmp( NtName, _T("\\Device\\Mup\\"), 12 ) == 0) // Win 7
    {
        pzCat = _tcsecpy( DosName, _T("\\\\") );
        _tcsncpyz( pzCat, &NtName[12], ccDosName - 2 );
    }
    else
    {
        if (!DevicePathToDosPath( NtName, DosName, ccDosName ))
        {
            err = GetLastError();
            // e.g \Device\Harddisk1
            _tcsncpyz( DosName, NtName, ccDosName );
        }
    }
    return err;
}
#endif

//++ Translate path with device name to absolute path ++-----------------------

namespace { // internal
  struct pfd_Data // internal use with __find_DosDrive.
  {
    CSTR  pzDev;    // in
    TSTR  pzPath;   // out
    UINT  ccPath;   // in/out
    bool  found;    // out
  };
}

BEGIN_STRSAFE_OVERRIDE
static bool __stdcall __find_DosDrive( TSTR pzDrv, PVOID pData ) // EnumerateMultiSz
{
    pfd_Data* pd = (pfd_Data*) pData;
    bool proceed = true;
    TCHAR szDevice[ MAX_PATH ];

    // Query the device path of the enumerated DOS drive.

    UINT ccDevice = QueryDosDevice(
        WithoutBackslash( pzDrv ), szDevice, dimof(szDevice)
        );
    if (ccDevice)
    {
        UINT ccCmp = ccDevice - 2; // ccDevice includes *two* NUL chars.
        CSTR pzSep = &pd->pzDev[ ccCmp ];

        // Check if the device name matches what we're looking for.

        if ((*pzSep == BSLASH) && (0 == _tcsnicmp( szDevice, pd->pzDev, ccCmp )))
        {
            pd->found = true;

            // Remove the device name and replace it with the drive letter,
            // followed by the original file pathname.

            _tcsncpy( pd->pzPath, pzDrv, 2 ); // "X:"
            _tcsncpyz( &pd->pzPath[2], pzSep, pd->ccPath - 2 );

            pd->ccPath = (UINT)_tcslen( pd->pzPath );
            proceed = false; // Stop enumerating.
        }
    }
    return proceed;
}
END_STRSAFE_OVERRIDE

// Alphatest passed.

UINT DevicePathToDosPath( IN CSTR DevPath, OUT TSTR PathBuf, UINT ccPathBuf )
{
    UINT ccPath = 0;
    TCHAR szDrives[ 128 ] = S_BLANK; // > 26*4

    if (GetLogicalDriveStrings( dimof(szDrives), szDrives ))
    {
        pfd_Data data = { DevPath, PathBuf, ccPathBuf, false };

        EnumerateMultiSz( szDrives, __find_DosDrive, &data );

        if (data.found) ccPath = data.ccPath;
        else SetLastError( ERROR_BAD_PATHNAME );
    }
    return ccPath;
}

//++ ChangeDirectory ++--------------------------------------------------------

CSTR ChangeDirectory( CSTR Dir )
{
    WORD ccPath = (WORD) GetCurrentDirectory( 0, NULL );
    TSTR SaveDir = newStrBuf( ccPath ); // Comply with deleteStr.
    if (!SaveDir)
        SetLastError( ERROR_OUTOFMEMORY );
    else {
        BOOL ok = (GetCurrentDirectory( ccPath, SaveDir ) > 0);
        if (ok) ok = SetCurrentDirectory( WithBackslash( Dir ));
        if (!ok) SaveDir = (TSTR) deleteStr( SaveDir ); // Return NULL to indicate error.
    }
    return SaveDir;
}

CSTR DoneDirectory( CSTR oldDir )
{
    SetCurrentDirectory( oldDir );
    return deleteStr( oldDir );
}

//++ FindMoreFiles ++----------------------------------------------------------

bool FindMoreFiles( HANDLE hFind, WIN32_FIND_DATA* Found, BYTE nTries, BYTE msWait )
{
    UINT nerr = 0;
    DWORD err = 0;
try_Find:
    if (!FindNextFile( hFind, Found )) {
        err = GetLastError();
        if (err == ERROR_NO_MORE_FILES) {
            done_Files: FindClose( hFind );
            if (err) SetLastError( err ); // Re-store error code after closing.
            return false;
        } else {
            DP_StdFailMsg( _T("FindNextFile") );
            if (++nerr >= nTries) goto done_Files;
            // Allow others a while to finish their work and release the lock.
            if (msWait) Sleep( msWait );
            goto try_Find;
        }
    }
    return true;
}

//++ FindCloseEx ++------------------------------------------------------------

HANDLE FindCloseEx( HANDLE hFind )
{
    if (hFind == _BAD_HANDLE) hFind = NULL;
    else if (hFind && FindClose( hFind )) hFind = NULL;
    return hFind;
}

#if (WINVER >= 0x0600) // FindFirstStreamW requires Vista.
//++ EnumerateFileStreams ++---------------------------------------------------

// Alphatest passed: Gives full path from relative input path on current drive.

UINT EnumerateFileStreams( CSTR FileName, PFnEnumStreams Action, PVOID usrData )
{
    UINT nStreams = 0;
    WIN32_FIND_STREAM_DATA sd = { 0,0,0 };
    static const UINT bufLen = dimof(sd.cStreamName);

    // FindFirstStream/FindNextStream doesn't produce a path name (as was apparently
    // intended), so do some value added processing to give the user absolute paths.

  #ifdef _UNICODE
    #define wzFile FileName
  #else // We need two char conversion buffers, since the APIs are W only.
    WSTR wzFile = mem_WDupAStr( FileName, CP_ACP ); // Convert FileName to unicode
    TSTR pzStmPath = mem_AllocAStr( bufLen ); // Buffer for the Action call-out
  #endif
    WSTR wzStmPath = mem_AllocWStr( bufLen ); // Not on stack, for safety's sake.

    // FIXME: GetFullPathName is not good enough for this!
    // Use PathIsRelative() to bypass GetFullPathName() when not needed..?

    UINT ccStmPath = GetFullPathNameW( wzFile, MAX_PATH, wzStmPath, NULL );

    UINT ccBufAvail = bufLen - ccStmPath;
    WSTR pwzStream = wzStmPath + ccStmPath;
    wzStmPath[0] = towupper( wzStmPath[0] ); // Upper case drive letter please..

    HANDLE hStream = CheckHandle( FindFirstStreamW( wzFile, FindStreamInfoStandard, &sd, 0 ));
    while( hStream )
    {
        wcscpy_s( pwzStream, ccBufAvail, sd.cStreamName );
      #ifdef _UNICODE
        bool proceed = Action( wzStmPath, sd.StreamSize.QuadPart, usrData );
      #else
        WideCharToMultiByte( CP_ACP, 0, wzStmPath, -1, pzStmPath, bufLen, NULL, NULL );
        bool proceed = Action( pzStmPath, sd.StreamSize.QuadPart, usrData );
      #endif
        ++nStreams;
        if (!proceed || !FindNextStreamW( hStream, &sd ))
            hStream = FindCloseEx( hStream );
    }
    mem_Free( wzStmPath );
  #ifndef _UNICODE
    mem_Free( pzStmPath );
    mem_Free( wzFile );
  #endif
    return nStreams;
}
#endif//(WINVER >= 0x0600)

//++ LoadAndMapFile ++---------------------------------------------------------

typedef struct MappedFile*  PMappedFile; // HMAPFILE;
struct MappedFile // Internal data struct
{
    HANDLE  hFile;
    UINT64  cbFile;
    HANDLE  hMap;
    PBYTE   pMap;
    PBYTE   pCurr; // 2017 - Used by Peek/Read/WriteMappedFile, et c...
};

// According to some, it is not necessary to retain the hMap and hFile,
// since the OS will not close those until the last view of it is closed.
// However, my tests showed that the mapping/view fails if the hFile is closed.
// This may be version dependant, and warrant more testing.
// If it's true they can be closed, the brunt of the MappedFile struct can be eliminated.
// LN

HMAPFILE LoadAndMapFile( CSTR FName, DWORD PageAccess, PBYTE* ppData )
{
    DWORD       FileAccess, MapAccess, err;
    HANDLE      hFile, hMap;
    PVOID       pMap;
    UINT64      cbFile;

    PMappedFile pHnd = NULL;
    if (ppData) *ppData = NULL;

  #if !ALLOW_EXECUTABLE_FILEMAPPING
    // Executable mappings are supported since XP2, but I choose to decline.
    // This decision may change in the future (if I or a contributor see fit).

    if (BITS_SET( PAGE_EXECUTE_READ, PageAccess )
    || BITS_SET( PAGE_EXECUTE_READWRITE, PageAccess ))
    {
        err = ERROR_INVALID_PARAMETER;
        goto exit_Error; //return NULL;
    }
  #endif

    FileAccess = GENERIC_READ;
    MapAccess = FILE_MAP_READ;

    if (BITS_SET( PAGE_READWRITE, PageAccess )
    || BITS_SET( PAGE_WRITECOPY, PageAccess ))
    {
        FileAccess |= GENERIC_WRITE;
        MapAccess |= BITS_SET( PAGE_WRITECOPY, PageAccess ) ? FILE_MAP_COPY : FILE_MAP_WRITE;
    }

    // Open the file and map it for reading, et c..

    hFile = CheckHandle( CreateFile(
        FName, FileAccess, FILE_SHARE_READ, NULL, OPEN_EXISTING, 0, NULL
        ));
    if (!hFile)
    {
        err = GetLastError(); // Preserve error code (past the DPrint I/O).
        TRACE( DP_ERROR, _F("Can't open '%s': %s\n"), FName, SysErrorMsg( err ));
      exit_Error:
        SetLastError( err );
        goto hmf_Exit; //return NULL;
    }
    cbFile = GetFileSize64( hFile );

    hMap = CreateFileMapping( hFile, NULL, PageAccess, 0,0, NULL );
    if (!hMap)
    {
        err = GetLastError(); // Preserve error code (past CloseHandle et c..)
        TRACE( DP_ERROR, _F("Can't map '%s': %s\n"), FName, SysErrorMsg( err ));
      exit_CloseFile:
        CloseHandle( hFile );
        goto exit_Error;
    }

    pMap = MapViewOfFile( hMap, MapAccess, 0,0, 0 );
    if (!pMap)
    {
        err = GetLastError(); // Preserve error code..
        TRACE( DP_ERROR, _F("Can't map view of '%s': %s\n"), FName, SysErrorMsg( err ));
        CloseHandle( hMap );
        goto exit_CloseFile;
    }

    // I might consider exposing the handle data at some future time,
    // but for now the internal data structure remains opaque.

    pHnd = (PMappedFile) mem_Alloc( sizeof(MappedFile) );
    pHnd-> hFile = hFile;
    pHnd-> cbFile = cbFile;
    pHnd-> hMap = hMap;
    pHnd-> pMap = (PBYTE) pMap;
    pHnd-> pCurr = (PBYTE) pMap;

    if (ppData) *ppData = (PBYTE) pMap;

hmf_Exit:
    return (HMAPFILE) pHnd; // Return the handle
}

BOOL UnloadMappedFile( HMAPFILE hMap )
{
    DWORD errCode = 0;
    BOOL Ok = (hMap != NULL);
    if (!Ok) errCode = ERROR_INVALID_HANDLE;
    else
    {
        PMappedFile pHnd = (PMappedFile) hMap;

        Ok = UnmapViewOfFile( pHnd->pMap );
        if (!Ok) errCode = GetLastError();

        pHnd->hMap = CloseHandleEx( pHnd->hMap );
        pHnd->hFile = CloseHandleEx( pHnd->hFile );
        pHnd = (PMappedFile) mem_Free( pHnd ); // Free the control struct
    }
    if (errCode) SetLastError( errCode ); // Indicate the primary error
    return Ok;
}

PVOID GetMappedFilePointer( HMAPFILE hMap ) // In case "someone" got sloppy
{
    if (hMap) return PMappedFile(hMap)-> pMap;
    SetLastError( ERROR_INVALID_HANDLE );
    return NULL;
}

UINT64 GetMappedFileSize( HMAPFILE hMap )
{
    if (hMap) return PMappedFile(hMap)-> cbFile;
    SetLastError( ERROR_INVALID_HANDLE );
    return 0;
}

// 2017 addendum - Read/Peek/WriteFile facsimiles ...

size_t PeekMappedFile( HMAPFILE hMapFile, PVOID Buffer, size_t cbRead )
{
    if (!cbRead)
        SetLastError( ERROR_INVALID_PARAMETER );
    else if (!hMapFile) {
        SetLastError( ERROR_INVALID_HANDLE );
        cbRead = 0;
    } else {
        PMappedFile pFile = (PMappedFile) hMapFile;
       #ifndef HAVE_STRUCTURED_EH
       #pragma message("ALERT: PeekMappedFile not using SEH for filemap access.")
        memcpy( Buffer, pFile->pCurr, cbRead );
       #else
        __try { memcpy( Buffer, pFile->pCurr, cbRead ); } // May except..
        __except_execute
        {
            SetLastError( ERROR_READ_FAULT );
            cbRead = 0;
        }
       #endif
    }
    return cbRead;
}

size_t ReadMappedFile( HMAPFILE hMapFile, PVOID Buffer, size_t cbRead )
{
    cbRead = PeekMappedFile( hMapFile, Buffer, cbRead );
    if (cbRead) PMappedFile(hMapFile)->pCurr += cbRead;
    return cbRead;
}

size_t WriteMappedFile( HMAPFILE hMapFile, PVOID Buffer, size_t cbWrite )
{
    if (!cbWrite)
        SetLastError( ERROR_INVALID_PARAMETER );
    else if (!hMapFile) {
        SetLastError( ERROR_INVALID_HANDLE );
        cbWrite = 0;
    } else {
        PMappedFile pFile = (PMappedFile) hMapFile;
       #ifndef HAVE_STRUCTURED_EH
       #pragma message("ALERT: WriteMappedFile not using SEH for filemap access.")
        memcpy( pFile->pCurr, Buffer, cbWrite );
        pFile->pCurr += cbWrite;
       #else
        __try
        {
            memcpy( pFile->pCurr, Buffer, cbWrite ); // May except..
            pFile->pCurr += cbWrite; // In which case this is never assigned
        }
        __except_execute
        {
            SetLastError( ERROR_WRITE_FAULT );
            cbWrite = 0;
        }
      #endif
    }
    return cbWrite;
}

PBYTE GetMappedFilePtr( HMAPFILE hMapFile )
{
    PBYTE pData = NULL;
    if (hMapFile) pData = PMappedFile(hMapFile)->pCurr;
    else SetLastError( ERROR_INVALID_HANDLE );
    return pData;
}

PBYTE SetMappedFilePtr( HMAPFILE hMapFile, INT64 Offset, UINT How )
{
    PBYTE pData = NULL; //INVALID_SET_FILE_POINTER;
    if (!hMapFile) SetLastError( ERROR_INVALID_HANDLE );
    else
    {
        PMappedFile pFile = (PMappedFile) hMapFile;
        INT64 newOffs, fileOffs = (pFile->pCurr - pFile->pMap);

        switch( How )
        {
            case FILE_BEGIN: newOffs = Offset; break;
            case FILE_CURRENT: newOffs = fileOffs + Offset; break;
            case FILE_END: newOffs = pFile->cbFile + Offset; break; // NB: Typcally + negative Offset
            default:
                SetLastError( ERROR_INVALID_PARAMETER );
                goto __exit;
        }

        if (newOffs < 0 || newOffs > (INT64)pFile->cbFile)
            SetLastError( ERROR_SEEK );
        else
        {
            pFile->pCurr = pFile->pMap + newOffs;
            pData = pFile->pCurr;
        }
    }
__exit:
    return pData;
}

UINT64 GetMappedFilePos( HMAPFILE hMapFile )
{
    PBYTE pCurr = GetMappedFilePtr( hMapFile );
    return pCurr ? (pCurr - PMappedFile(hMapFile)->pMap) : 0;
}

UINT64 SetMappedFilePos( HMAPFILE hMapFile, INT64 Offset, UINT How )
{
    UINT64 fpos = INVALID_SET_FILE_POINTER;
    PBYTE fptr = SetMappedFilePtr( hMapFile, Offset, How );
    if (fptr) fpos = (fptr - PMappedFile(hMapFile)->pMap);
    return fpos;
}

// EOF