UtilFunc.h

Go to the documentation of this file.

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
// Project: uLib - User mode utility library.
// Module: Utility functions (hence the u in uLib)
// Author: Copyright (c) Love Nystrom
// License: NNOSL (BSD descendant, see NNOSL.txt in the base directory).
//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

#ifndef __UtilFunc_h_incl__
#define __UtilFunc_h_incl__

#include <uLib/Common.h>

// The original UtilFunc.cpp had grown so large it's now split into smaller units.
// However, the declarations are all here, in UtilFunc.h.
// > UtilFunc.cpp   - Some fundamentals..
// > IoUtil.cpp     - I/O related functions.
// > UserUtil.cpp   - User32 related functions.
// > GdiUtil.cpp    - GDI32 related functions.
// > KernelUtil.cpp - Kernel32 related functions.
// > SecUtil.cpp    - Security related functions. (See also UmLsa.cpp)
// > ShellUtil.cpp  - Shell32 related functions.

//+============================================================================
//+============================================================================

BEGIN_EXTERN_C

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

POINT  MkPoint( LONG x, LONG y );     
POINTS MkPointS( SHORT x, SHORT y );  
SIZE   MkSize( LONG cx, LONG cy );    
SIZES  MkSizeS( SHORT cx, SHORT cy ); 
RECT   MkRect( LONG L, LONG T, LONG R, LONG B ); 
RECTS  MkRectS( SHORT L, SHORT T, SHORT R, SHORT B ); 

#ifdef __cplusplus
BEGIN_EXTERN_CPP // Operator and function overloading requires C++ linkage

  POINT MkPoint( const POINTS& p ); 
  POINTS MkPointS( const POINT& p );

  BEGIN_NAMESPACE( uLib ) // Point comparators
  bool operator == ( POINT P1, POINT P2 );
  bool operator != ( POINT P1, POINT P2 );
  bool operator == ( POINTS P1, POINTS P2 );
  bool operator != ( POINTS P1, POINTS P2 );
  END_NAMESPACE( uLib )

END_EXTERN_CPP
#else
// In C You may use POINTSTOPOINT() and POINTTOPOINTS()
#endif

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


void DiffRect( PRECT Borders, LPCRECT Outer, LPCRECT Inner );


void InflateBorders( PRECT Target, LPCRECT Borders );


void AbsDiffRect( PRECT Borders, LPCRECT Outer, LPCRECT Inner );


void AbsInflateBorders( PRECT Target, LPCRECT Borders );

//==---------------------------------------------------------------------------
// Some rect conversions. Returns the (modified) argument for ease of chaining.
//==---------------------------------------------------------------------------


LPRECT AbsToDimRect( LPRECT pRect );


LPRECT DimToAbsRect( LPRECT pRect );


LPRECT AbsToRelRect( LPRECT pRect );


LPRECT NegateRect( LPRECT pRect );


void FitRect( IN PRECT pRc, IN PRECT pBounds, OUT PRECT pOut );

//==---------------------------------------------------------------------------
// Rect macros inherited from somewhere I can't remember, probably a MS sample.
//==---------------------------------------------------------------------------

#ifndef RECT_WIDTH
  #define RECT_WIDTH(r)   ((r).right - (r).left)
  #define RECT_HEIGHT(r)  ((r).bottom - (r).top)
#endif

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


extern IMalloc* ShMalloc; // In ShellUtil.cpp


bool InitShellFunc( bool useOle DEF_(false), DWORD coFlag DEF_(COINIT_APARTMENTTHREADED) );
void DoneShellFunc();        
bool ShellFuncInitialized(); 


PVOID ShellFreeEx( PVOID pBlk );


LPITEMIDLIST GetPathNamePIDL( CSTR Dir, ULONG* pAttrib OPTIONAL DEF_(NULL) );


bool RecycleFile( CSTR Name, bool Confirm DEF_(true), bool Single DEF_(true) );

#ifdef __GNUC__ // MinGW is missing these SHFileOperation flags:
  #ifndef FOF_NO_UI
  #define FOF_NO_CONNECTED_ELEMENTS  0x2000  
  #define FOF_NORECURSION  0x1000  
  #define FOF_WANTNUKEWARNING 0x4000  
  #define FOF_NORECURSEREPARSE 0x8000  
  #define FOF_NO_UI (FOF_SILENT | FOF_NOCONFIRMATION | FOF_NOERRORUI | FOF_NOCONFIRMMKDIR) 
  #endif
#endif // __GNUC__


DWORD GetDLLVersion( CSTR FName );
#define PACKVERSION( maj,min ) ((DWORD)MAKELONG( min,maj )) 


typedef struct _LINKDATA
{
    // Mandatory members

    LPTSTR  Pathname;   
    DWORD   Flags;      

    // Optional members

    LPTSTR  Desc;       
    LPTSTR  Args;       
    LPTSTR  IconPath;   
    int     IconIndex;  
    LPTSTR  WorkingDir; 
    int     ShowCmd;    
    WORD    Hotkey;     
    LPITEMIDLIST IdList; 
}
*PLINKDATA, LINKDATA;

#define LDF_DESC     0x00000001 
#define LDF_ARGS     0x00000002 
#define LDF_ICON     0x00000004 
#define LDF_WORKDIR  0x00000008 
#define LDF_HOTKEY   0x00000010 
#define LDF_SHOWCMD  0x00000020 
#define LDF_PIDL     0x00000040 
#define LDF_ALL ( \
    LDF_DESC | LDF_ARGS | LDF_ICON | LDF_WORKDIR | LDF_HOTKEY | LDF_SHOWCMD \
    )


HRESULT Shell_CreateLink( CSTR LinkFilePathname, IN const PLINKDATA pLink );


HRESULT Shell_ResolveLink( HWND hWnd, CSTR LinkFilePathname, OUT PLINKDATA pLink );


HRESULT ShowShareFolderUI( HWND hParent, CSTR Path );


HRESULT CreateStreamOnFile( IN CSTR FName,
    OUT IStream** ppStrm, OPTOUT DWORD* pSize DEF_(NULL)
    );

#if USE_VISUALSTYLE_HACK // DeactivateActCtx is not available on Win2000

bool EnableVisualStyles( bool Enable );
#endif

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


extern UINT WM_TaskbarCreated;  // In ShellUtil.cpp


void InitTaskbarSupport();


BOOL SetTrayIconNotification(
    UINT Action, HWND hNfy, UINT Id, HICON hIcon, CSTR Hint, UINT cbkMsg DEF_(WM_APP)
    );
#if 0 // Old name "ShellNotify" is too ambiguous and is going away...
#define ShellNotify( hNfy,Act,hIcon,Hint,Msg ) \
    SetTrayIconNotification( Act,hNfy,1,hIcon,Hint,Msg )
#endif

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


bool InitializeSecDesc( PSECURITY_DESCRIPTOR pSecDesc, PACL AccsList DEF_(NULL) );


bool EnableProcessPrivilege( CSTR prvName, bool Enable DEF_(true) ); // Single


bool EnableProcessPrivileges( bool Enable, CSTR prvName1, ... );


PTOKEN_PRIVILEGES AllocPrivileges( UINT Count, OPTOUT PDWORD pSize DEF_(NULL) );
PTOKEN_PRIVILEGES FreePrivileges( PTOKEN_PRIVILEGES pPrv );


bool EnablePrivilege(
    HANDLE hToken, CSTR Privilege, bool Enable, OPTOUT PLUID_AND_ATTRIBUTES pSave
    );
bool RestorePrivilege( HANDLE hToken, PTOKEN_PRIVILEGES pSaved );


bool EnablePrivileges( 
    IN HANDLE hToken, IN bool Enable, OPTOUT PTOKEN_PRIVILEGES* ppSave,
    ... // NULL terminated list of privilege names
    );


bool RestorePrivileges( HANDLE hToken, PTOKEN_PRIVILEGES pSaved, bool Dispose );

//--->> LSA authorization et c has migrated to UmLsa.h/cpp

//==---------------------------------------------------------------------------
// Under consideration: Always obtain a thread token, even if none in PEB.
//==---------------------------------------------------------------------------

DECLARE_HANDLE( HTOKENEX ); // Opaque control block..


HTOKENEX OpenThreadTokenEx( HANDLE hThread, ACCESS_MASK tokenAccess );


HTOKENEX CloseThreadTokenEx( HTOKENEX hToken );


HANDLE GetThreadExToken( HTOKENEX hTok );

//+============================================================================
//|
//|
//+============================================================================

#ifndef DOS_EXEPAGE_SIZE
  #define DOS_EXEPAGE_SIZE  512
#endif

UINT   GlobalPurgeAtom( CSTR Name ); 
CSTR   GlobalAtomName( ATOM atom );  
CSTR   LocalAtomName( ATOM atom );   

// GetCurrent[Process/Thread]Handle converts the corresponding pseudo handles
// to real ones. Don't forget to close them when done. See also *DuplicateHandle()*.

HANDLE GetCurrentThreadHandle();  
HANDLE GetCurrentProcessHandle(); 

HANDLE CloseHandleEx( HANDLE H ); 
HANDLE CheckHandle( HANDLE Hnd ); 


bool   WaitFor( HANDLE hObj, DWORD msWait );

// Additional global heap functions (supplement the WindowsX macros)
// Primarily intended for the clipboard and DDE.

ASTR   GlobalAllocStrA( UINT nChr );  
WSTR   GlobalAllocStrW( UINT nChr );  
ASTR   GlobalDupStrA( ACSTR Str, bool isMz DEF_(false) ); 
WSTR   GlobalDupStrW( WCSTR Str, bool isMz DEF_(false) ); 
#ifdef _UNICODE
  #define GlobalAllocStr GlobalAllocStrW
  #define GlobalDupStr   GlobalDupStrW
#else
  #define GlobalAllocStr GlobalAllocStrA
  #define GlobalDupStr   GlobalDupStrA
#endif


HANDLE GlobalUnlockedHandle( PVOID Ptr, PUINT pCount DEF_(NULL) );


bool IsBadReadWritePtr( const PVOID address, UINT_PTR size );


HANDLE Launch(
    CSTR ExePath, CSTR CmdLn, CSTR StartDir DEF_(NULL),
    int iShow DEF_(SW_SHOW), DWORD Flags DEF_(NORMAL_PRIORITY_CLASS)
    );


HANDLE CreateCapturedProcess(
    IN     CSTR    cmdLn,      
    INOUT  LPSTARTUPINFO pSi,  
    IN     DWORD   Flags,      
    OPTOUT PHANDLE pRdHnd,     
    OPTOUT PHANDLE pWrHnd,     
    OPTOUT PHANDLE pErrHnd,    
    OPTOUT PHANDLE phThread DEF_(NULL) 
    );


HANDLE CreateCapturedProcessEx(
    OPTIN  CSTR    ExePath,   
    OPTIN  CSTR    CmdLn,     
    OPTIN  CSTR    EnvStr,    
    OPTIN  CSTR    WorkDir,   
    INOUT  LPSTARTUPINFO pSI, 
    IN     DWORD   Flags,     
    OPTOUT PHANDLE pRdHnd,    
    OPTOUT PHANDLE pWrHnd,    
    OPTOUT PHANDLE pErrHnd,   
    OPTOUT PHANDLE phThread   
    );


HANDLE CloseCapturedProcess(
    IN HANDLE hProc,      
    IN LPSTARTUPINFO pSi, 
    OPTIN PHANDLE pRdHnd, 
    OPTIN PHANDLE pWrHnd, 
    OPTIN PHANDLE pErrHnd 
    );


HANDLE TerminateCapturedProcess(
    OPTIN HANDLE hProc,   
    IN LPSTARTUPINFO pSi, 
    IN PHANDLE pRdHnd,    
    IN PHANDLE pWrHnd,    
    IN PHANDLE pErrHnd,   
    IN UINT RetCode DEF_(EXIT_SUCCESS) 
    );


HMODULE GetOrLoadModule( CSTR modName ); // Might be superfluous..


HMODULE LoadProcLibrary( HANDLE hProcess, LPCSTR DllPathName, DWORD msWait DEF_(5000) );


BOOL UnloadProcLibrary( HANDLE hProcess, HMODULE hRemoteLib, DWORD msWait DEF_(5000) );

#ifndef NO_NDK_FILES


SHORT GetProcDLLRefCount( HANDLE hProcess, WCSTR DllName ); // NtFunc, preliminary


HMODULE GetProcDLLHandle( HANDLE hProcess, WCSTR DllName ); // NtFunc, preliminary

#endif // ndef NO_NDK_FILES

//==---------------------------------------------------------------------------


SYSTEMTIME* SystemTimeToLocalTime( INOUT SYSTEMTIME* Time );


SYSTEMTIME* LocalTimeToSystemTime( INOUT SYSTEMTIME* Time );


FILETIME FileTimeToLocalTime( FILETIME utc );

BEGIN_NAMESPACE( uLib ) // subgroup ftime
//( Placed in uLib namespace (due to their terse id's), to avoid id clashes. )


enum eTimeType
{
    LOCAL_TIME = 0, 
    SYSTEM_TIME     
};


FILETIME Now( eTimeType Domain DEF_(LOCAL_TIME) );


FILETIME AddTime( IN FILETIME Time, SHORT Hr, SHORT Min, SHORT Sec, SHORT mSec );

#if 1 // WIP.. Not public yet.
FILETIME AddFiletime( FILETIME Time, const FILETIME Add );
#endif


FILETIME MakeDateTime( WORD Year, WORD Month, WORD Day, WORD Hr, WORD Min, WORD Sec );

#ifdef __cplusplus // FILETIME comparators...
BEGIN_EXTERN_CPP // Operator overloading requires C++ linkage
// Note: These are possible because C++ allow global operators for structs.

bool operator > ( FILETIME const& A, FILETIME const& B );
bool operator < ( FILETIME const& A, FILETIME const& B );
bool operator >= ( FILETIME const& A, FILETIME const& B );
bool operator <= ( FILETIME const& A, FILETIME const& B );
bool operator == ( FILETIME const& A, FILETIME const& B );
bool operator != ( FILETIME const& A, FILETIME const& B );

END_EXTERN_CPP
#endif

extern const FILETIME NullFileTime;

END_NAMESPACE( uLib ) // subgroup ftime

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


#define DeleteEnvironmentVar( pwEnv,Name )  SetEnvironmentVar( pwEnv, Name, NULL )


bool GetEnvironmentSize( WSTR pwEnv, PUINT pSize, PUINT pUsed );


WSTR CloneEnvironment( OPTOUT PUINT pLength, OPTOUT PUINT pUsed );
WSTR FreeEnvironment( WSTR Env ); 

#ifndef NO_WINTERNAL // UNICODE_STRING

bool SetEnvironmentVar( OPTIO WSTR* pwEnv, IN CSTR Name, IN CSTR Value );


bool GetEnvironmentVar( 
    OPTIN WSTR pwEnv, IN CSTR Name, OUT TSTR Value, INOUT PUINT ccValBuf
    );

//   See also DeduplicateCharSeparatedText().


UINT ModifyEnvironmentVar(
    OPTIO WSTR* pwEnv, IN BYTE Option, IN CSTR Name, IN CSTR Addendum, OPTIN TCHAR Sep
    );

enum eModenvFlags {
    MEF_PREPEND = 0, 
    MEF_APPEND  = 1  
    };
#endif//ndef NO_WINTERNAL


#ifndef _UNICODE
UINT DeduplicatePathStr( INOUT TSTR Path );
#endif



WORD  GetTargetMachine( CSTR ExeName ); // Uses ReadNTHeaders


bool Is64BitExecutable( CSTR ExeName );

//( Written to support GetTargetMachine. )

bool  ReadNTHeaders( CSTR ExeName, IMAGE_NT_HEADERS* Hdr, bool GetOptHdr );


WORD  GetInstanceTargetMachine( HINSTANCE hInst );
bool  Is64BitInstance( HINSTANCE hInst ); 
bool  Is32BitInstance( HINSTANCE hInst ); 

// Human readable machine type and subsystem strings.
// (Might belong in a string module, but lives here for proximity reasons.)

CSTR GetMachineStr( WORD Machine ); 
CSTR GetSubSystemStr( WORD SubSys ); 

//+============================================================================
//|
//|
//+============================================================================

#ifndef SYSMET
  #define SYSMET( Id )  GetSystemMetrics( SM_##Id )
#endif
#ifndef GWL
  #define GWL( hwnd,Item )  GetWindowLong( hwnd, GWL_##Item )
  #define GWLP( hwnd,Item ) GetWindowLongPtr( hwnd, GWLP_##Item )
#endif
#ifndef SYSICO
  #define SYSICO( Id )  LoadIcon( NULL, IDI_##Id )
  #define SYSCUR( Id )  LoadCursor( NULL, IDC_##Id )
#endif
#ifndef LOADICO // Load from global hInstance
  #define LOADICO( Id ) LoadIcon( hInstance, CSTR( Id ))
#endif

#ifndef WS_VISICHILD
  #define WS_VISICHILD  (WS_CHILD | WS_VISIBLE)
  #define WS_SCROLL     (WS_VSCROLL | WS_HSCROLL)
#endif
#ifndef CS_REDRAW
  #define CS_REDRAW (CS_HREDRAW | CS_VREDRAW)
#endif

#ifndef WM_Cut
#define WM_Cut( hCtl )   SendMessage( hCtl, WM_CUT, 0,0 )
#define WM_Copy( hCtl )  SendMessage( hCtl, WM_COPY, 0,0 )
#define WM_Paste( hCtl ) SendMessage( hCtl, WM_PASTE, 0,0 )
#define WM_Clear( hCtl ) SendMessage( hCtl, WM_CLEAR, 0,0 )
#endif//ndef WM_Cut

#define SimpleBeep()                MessageBeep( -1 )
#define GetAcceleratorCount( hacc ) CopyAcceleratorTable( (HACCEL)(hacc), NULL, 0 )


UINT DispatchMessagesFor( HWND hWnd );

//:=-------------------------------------------------------------------------=:
//:=-------------------------------------------------------------------------=:


bool OpenEmptyClipboard( HWND hWnd );


typedef bool (__stdcall *PFClipFmtAction)( UINT FmtTag, PVOID UserData );


UINT EnumerateClipFormats( HWND hCBOwner, PFClipFmtAction Action, PVOID UserData );


bool PutClipHandle( HWND clipboardOwner, HANDLE hClip, UINT clipFmt );


HANDLE GetClipHandle( UINT clipFmt );


bool PutClipboardStringA( HWND clipboardOwner, ACSTR Text );
bool PutClipboardStringW( HWND clipboardOwner, WCSTR Text ); 
#ifdef _UNICODE
    #define PutClipboardString  PutClipboardStringW
#else
    #define PutClipboardString  PutClipboardStringA
#endif


CSTR DupClipboardString();


PVOID DupClipboardData( UINT clipFmt, PUINT pSize OPTOUT );

//:=-------------------------------------------------------------------------=:

void   SetWindowFloat( HWND hWnd, int Index, float Value );   
void   SetWindowDouble( HWND hWnd, int Index, double Value ); 
float  GetWindowFloat( HWND hWnd, int Index );                
double GetWindowDouble( HWND hWnd, int Index );               

void   SetClassFloat( HWND hWnd, int gcl_Ix, float Value );   
void   SetClassDouble( HWND hWnd, int gcl_Ix, double Value ); 
float  GetClassFloat( HWND hWnd, int gcl_Ix );                
double GetClassDouble( HWND hWnd, int gcl_Ix );               

//:=-------------------------------------------------------------------------=:
// Window size

UINT GetWndHeight( HWND hWnd );
UINT GetWndWidth( HWND hWnd );
bool GetWndSize( HWND hWnd, SIZE* pSize ); 
bool GetWndPos( HWND hWnd, POINT* pPos ); 


BOOL GetWindowMinimizeRect( HWND hTrayApp, RECT* pRect );

// More window handling support...

bool CenterWindow( HWND hWnd, HWND hOwner ); 

void GetChildWndRect( HWND hCtrl, RECT* pRc ); 
bool EnableChildWnd( HWND Owner, UINT Id, bool Enable );
HWND GetChildWndWithId( HWND hParent, UINT ChildId ); 


HWND SetParentWnd( HWND hWnd, HWND newParent );


HWND CreateWindowIndirect( LPCREATESTRUCT pc );


INT_PTR DialogBoxParamEx(
    HINSTANCE hInst,    
    CSTR    Template,   
    HWND    hParent,    
    DLGPROC DlgProc,    
    LPARAM  lParam,     
    LANGID  Language    
    );


HWND CreateDialogParamEx(
    HINSTANCE hInst,    
    CSTR    Template,   
    HWND    hParent,    
    DLGPROC DlgProc,    
    LPARAM  lParam,     
    LANGID  Language    
    );

#if 1 // WIP..

bool GetRequiredWindowSize( HWND hWnd, IN const PSIZE pClient, OUT PSIZE pWindow );


bool GetWindowClientSize( HWND hWnd, IN const PSIZE pWindow, OUT PSIZE pClient );
#endif

bool RefreshWnd( HWND hWnd ); 
bool RedrawWnd( HWND hWnd, UINT Flags ); 
bool RedrawWndRect( HWND hWnd, PRECT pRect, UINT Flags ); 
bool RedrawWndRgn( HWND hWnd, HRGN hRgn, UINT Flags ); 
bool MoveWnd( HWND hWnd, int X, int Y, bool Repaint ); 
bool ResizeWnd( HWND hWnd, int W, int H, bool Repaint ); 

#define GetWndStyle( hwnd )         GetWindowLong( hwnd, GWL_STYLE )
#define SetWndStyle( hwnd,style )   SetWindowLong( hwnd, GWL_STYLE, style )
#define GetWndExStyle( hwnd )       GetWindowLong( hwnd, GWL_EXSTYLE )
#define SetWndExStyle( hwnd,style ) SetWindowLong( hwnd, GWL_EXSTYLE, style )

#ifndef WM_GetFont
  #define WM_GetFont( hwnd )           (HFONT)SendMessage( hwnd, WM_GETFONT, 0,0 )
  #define WM_SetFont( hwnd,hfnt,rdrw ) (void)SendMessage( hwnd, WM_SETFONT, (WPARAM)hfnt, rdrw )
#endif

#ifndef WM_SetRedraw
  #define WM_SetRedraw( hwnd,on )  SendMessage( hwnd, WM_SETREDRAW, on, 0 )
#endif


bool __cdecl SetCaption( HWND hwnd, CSTR fmt, ... );


void WINAPI SetRedraw( HWND hwnd, bool on );


HICON WINAPI LoadSmallIcon( HINSTANCE hInst, CSTR Id );


PVOID WINAPI LoadCustomResource(
    HMODULE hModule, CSTR Id, CSTR Type, UINT* pSize OPTOUT DEF_(NULL)
    );


PVOID WINAPI LoadCustomResourceEx(
    HMODULE hModule, CSTR Id, CSTR Type, LANGID Language OPTIN DEF_(0),
    UINT* pSize OPTOUT DEF_(NULL)
    );


IPicture* WINAPI LoadPictureResource( HMODULE hModule, CSTR Id, CSTR Type );


IPicture* WINAPI LoadPictureFile( CSTR FName );

//> Some WinGDI that live here due to their relation to LoadPictureResource.

void WINAPI PaintPicture( IPicture* pPic,
    HDC hdc, int x, int y, int cx DEF_(0), int cy DEF_(0)
    );


bool WINAPI PaintPictureEx( IPicture* pPic,
    HDC hdc, long x, long y, long cx DEF_(0), long cy DEF_(0),
    long imx DEF_(0), long imy DEF_(0), long imw DEF_(0), long imh DEF_(0),
    PRECT prMeta DEF_(NULL)
    );

// Convert between HiMetric and Pixel measures.

long WINAPI HiMetricToPix( long hiMetric ); 
long WINAPI PixToHiMetric( long Pix ); 

//:=-------------------------------------------------------------------------=:
//:=-------------------------------------------------------------------------=:


int __cdecl MsgBox( HWND Owner, UINT Type, CSTR Cap, CSTR Fmt, ... );

#define MB_INFO        MB_OK| MB_ICONINFORMATION 
#define MB_QUERY       MB_YESNO| MB_ICONQUESTION 
#define MB_QUERYCANCEL MB_YESNOCANCEL| MB_ICONQUESTION 
#define MB_WARNING     MB_OK| MB_ICONEXCLAMATION 
#define MB_ERROR       MB_OK| MB_ICONSTOP 


HANDLE __cdecl AsyncMsgBox( UINT Type, PINT_PTR pResult, CSTR Title, CSTR Fmt, ... );


HANDLE __cdecl AsyncMsgBoxEx(
    HWND Owner, UINT Flags, CSTR Title,
    HINSTANCE hInst, CSTR IconId, DWORD LangId,
    DWORD_PTR HelpId, MSGBOXCALLBACK Callback,
    PINT_PTR pResult,
    CSTR TextFmt, ...
    );


#define CloseAsyncMsgBox( hBox ) SendMessage( hBox, WM_SYSCOMMAND, SC_CLOSE, 0 )

//:=-------------------------------------------------------------------------=:
//:=-------------------------------------------------------------------------=:

bool IsWndClass( HWND hWnd, CSTR clsName ); 
CSTR GetWndClassName( HWND hWnd );          

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


HMENU LoadMenuEx( HMODULE hModule, CSTR Id, LANGID Language );


#define MIIM_ALL \
    ( MIIM_STRING | MIIM_ID | MIIM_FTYPE | MIIM_STATE \
    | MIIM_SUBMENU | MIIM_DATA | MIIM_BITMAP | MIIM_CHECKMARKS )


HMENU AddSubMenu(
    HMENU hMenu, UINT Index, CSTR Text,
    WORD Id DEF_(0), WORD State DEF_(0), PVOID Data DEF_(NULL),
    HBITMAP Image DEF_(NULL)
    );


bool AddMenuItem(
    HMENU hMenu, UINT Index, CSTR Text, WORD cmdId,
    WORD State DEF_(0), PVOID Data DEF_(NULL),
    HBITMAP Image DEF_(NULL)
    );

#define AddMenuSeparator( hSubMenu ) \
    AddMenuItem( hSubMenu, 999, NULL, (-1), 0, NULL, NULL )


int GetMenuItemIdByName( HMENU hMenu, CSTR Name );


LPMENUITEMINFO GetMenuItemByName( HMENU hMenu, CSTR Name );


PVOID GetMenuItemData( HMENU hMenu, UINT Id );


bool SetMenuItemCheck( HMENU hMenu, UINT Id, bool Check );


typedef bool (__stdcall *PFnMenuItemAction)( 
    HMENU hMenu, MENUITEMINFO* pInfo, PVOID Ctx
    );


UINT EnumerateMenuItems( HMENU hMenu, PFnMenuItemAction Action, PVOID Ctx );

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


double  GetWndReal( HWND hCtl );
double  GetDlgItemReal( HWND hDlg, UINT Id ); 


bool SetWndReal( HWND hCtl, double Value, BYTE nDeci, CSTR Suffix DEF_(NULL) );
bool SetDlgItemReal( HWND hDlg, UINT Id, double Value, BYTE nDeci, CSTR Suffix DEF_(NULL) );

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

#define MDI_CLIENTCLASS _T("MDIClient") 


HWND GetMDIClient( HWND hMdiFrame );

// MDI message macros, send to hMdiClient...

#ifndef MDITileH // from wCore
#define MDITileH( hcli )            (BOOL) SendMessage( hcli, WM_MDITILE, MDITILE_HORIZONTAL,0 )
#define MDITileV( hcli )            (BOOL) SendMessage( hcli, WM_MDITILE, MDITILE_VERTICAL,0 )
#define MDICascade( hcli )          (BOOL) SendMessage( hcli, WM_MDICASCADE, 0,0 )
#define MDIArrangeIcons( hcli )     (void) SendMessage( hcli, WM_MDIICONARRANGE, 0,0 )
#define MDIActivate( hcli,hchild )  (void) SendMessage( hcli, WM_MDIACTIVATE, (WPARAM)(hchild), 0 )
#define MDIGetActive( hcli,maxed )  (HWND) SendMessage( hcli, WM_MDIGETACTIVE, 0, (LPARAM)(PBOOL)(maxed) )
#define MDIDestroy( hcli,hchild )   (void) SendMessage( hcli, WM_MDIDESTROY, (WPARAM)(hchild), 0 )
#endif // ndef MDITileH

#define MDIActivateNext( hcli,hchild )  (void) SendMessage( hcli, WM_MDINEXT, (WPARAM)(hchild),0 )
#define MDIActivatePrev( hcli,hchild )  (void) SendMessage( hcli, WM_MDINEXT, (WPARAM)(hchild),1 )

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

bool ButtonChecked( HWND hBtn ); 
bool ButtonCtrlChecked( HWND hDlg, UINT Id ); 
bool CheckButton( HWND hBtn, bool Check ); 
bool CheckButtonCtrl( HWND hDlg, UINT Id, bool Check ); 

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


int __cdecl AddListString( HWND hLB, CSTR Fmt, ... );


int AddListItem( HWND hLB, CSTR Text, LPARAM Data DEF_(0) );

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

// @dt A combo has 3 window handles, one for the aggregate, and two handles
// for the editor and listbox parts. Retrieve the editor and list handles.

HWND GetComboEditor( HWND hCombo ); 
HWND GetComboList( HWND hCombo ); 

// AddComboString and AddComboItem works exactly like AddListString and AddListItem.

int __cdecl AddComboString( HWND hCB, CSTR Fmt, ... ); 
int         AddComboItem( HWND hCB, CSTR Text, LPARAM Data DEF_(0) ); 

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


HWND CreateStatusbar( HWND hParent, UINT Id, CSTR Text, UINT Style );


bool __cdecl SetStatusParts( HWND hStat, UINT nParts, ... );


bool __cdecl SetStatusWidths( HWND hStat, UINT nParts, int* Width );


bool __cdecl SetStatusText( HWND hStat, UINT Part, CSTR Fmt, ... );

#define SB_SetParts( hctl,npart,ppart ) (BOOL) SendMessage( hctl,SB_SETPARTS,(WPARAM)(npart),(LPARAM)(ppart) )
#define SB_SetText( hctl,part,text )    (BOOL) SendMessage( hctl,SB_SETTEXT,(WPARAM)(part),(LPARAM)(text) )
#define SB_SetIcon( hctl,part,hico )    (BOOL) SendMessage( hctl,SB_SETICON,(WPARAM)(part),(LPARAM)(hico) )

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

#ifndef I_NOIMAGE
  #define I_NOIMAGE (I_IMAGECALLBACK-1) /* Oops.. flew past I_IMAGENONE (also -2) */
#endif


typedef bool (__stdcall *PFLvItemAction)( HWND hList, LPLVITEM pItem, PVOID pCtx );


UINT ListView_ForEach( HWND hLv, PFLvItemAction Action, PVOID pCtx );

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


bool GetTrackbarInfo( HWND hCtl, LPSCROLLINFO psi );
bool SetTrackbarInfo( HWND hCtl, LPSCROLLINFO psi, bool Redraw );

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

//+ ImageList_CreateMapped

HIMAGELIST ImageList_CreateMapped(
    HINSTANCE hInst, UINT Id, LPCOLORMAP Map, UINT nMap, 
    UINT cxImg, UINT Flags, UINT nGrow
    );

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

// To display correctly with CreateWindowEx, the strings must be TEXT transmutable.
// However, if using CreateToolbarEx, they must always be Unicode.


#define _TBS(s) (INT_PTR)_T(s)  // CreateWindowEx
//#define _TBS(s) (INT_PTR)L##s // CreateToolbarEx


HWND CreateToolbar(
    HWND hParent,           
    UINT Id,                
    UINT x, UINT y, UINT w, 
    UINT h,                 
    UINT cxBtn, UINT cyBtn, 
    HIMAGELIST hImages,     
    LPTBBUTTON Buttons,     
    UINT nButtons,          
    DWORD Style,            
    DWORD ExStyle           
    );

// Since the toolbars don't honor user specified sizing no matter what,
// we might as well bloody hardcode the button size and bar height above
// and reduce the parameter count... Agh :(

#define TBTN_HEIGHT 22 
#define TBTN_WIDTH  22 
#define TBAR_HEIGHT 26 


HWND CreateStdToolbar(
    HWND hParent, UINT Id, UINT x, UINT y, UINT w, UINT h,
    UINT imgType, LPTBBUTTON Buttons, UINT nButtons, DWORD Style, DWORD ExStyle
    );

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

bool TreeView_GetItemText( HWND hTree, HTREEITEM hItem, TSTR Buf, UINT BufLen );

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


WORD RebarBandInfoSize();

// TODO: Design a flexible/easy AddRebarBand()...
// E.g: bool AddRebarBand( HWND hRebar, CSTR Title, WORD Id, HWND hChild );

//++- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Tab controls ... et c.

    // None so far... (You may request a new API)

//+============================================================================
//|
//|
//+============================================================================

#ifndef SYSHBR
  #define SYSHBR(id) GetSysColorBrush( COLOR_##id )
  #define SYSRGB(id) GetSysColor( COLOR_##id )
#endif

#ifndef BKGHBR 
  #define BKGHBR(id) (HBRUSH)( 1 + COLOR_##id )
#endif

#ifndef RGBA 
  #define RGBA( R,G,B,A ) \
    ((COLORREF) ((BYTE)(R)|((WORD)((BYTE)(G))<<8)|(((DWORD)(BYTE)(B))<<16)|(((DWORD)(BYTE)(A))<<24)))
  #define GetAValue( rgba )   ((BYTE)((COLORREF)(rgba) >> 24))  
  #define GetRGBValue( rgba ) ((COLORREF)((rgba) & 0x00FFFFFF)) 
#endif

#ifndef R4_MASKBLT
  #define R4_MASKBLT  MAKEROP4( SRCCOPY, DSTCOPY )
#endif
#ifndef DSTCOPY 
  #define DSTCOPY   0x00AA0029L // Id est: NOP
#endif

#ifndef VLine
  #define VLine( dc,x, y1,y2 ) Line( dc, x,y1, x,y2 )
  #define HLine( dc,y, x1,x2 ) Line( dc, x1,y, x2,y )
#endif

#ifndef GetSystemPalette
  #define GetSystemPalette() (HPALETTE)GetStockObject( DEFAULT_PALETTE )
#endif
#ifndef GetPaletteLength
  #define GetPaletteLength( hPal ) GetPaletteEntries( hPal,0,0,NULL )
#endif


HGDIOBJ WINAPI DeleteObjectEx( HGDIOBJ hObj );

#define DeleteFontEx(h)   (HFONT) DeleteObjectEx( (HFONT)h )
#define DeletePenEx(h)    (HPEN) DeleteObjectEx( (HPEN)h )
#define DeleteBrushEx(h)  (HBRUSH) DeleteObjectEx( (HBRUSH)h )
#define DeleteBitmapEx(h) (HBITMAP) DeleteObjectEx( (HBITMAP)h )
#define DeleteRegionEx(h) (HRGN) DeleteObjectEx( (HRGN)h )


void WINAPI Line( HDC hdc, int x1, int y1, int x2, int y2 );


void WINAPI DrawIsoTriangle(
    HDC hdc, int xOrg, int yOrg, int Radius, double Orientation
    );


void WINAPI GetIsoTriangleVertices(
    POINT* Vtx, int xOrg, int yOrg, int Radius, double Orientation
    );

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


COLORREF WINAPI ScaleColorRef( COLORREF color, BYTE mul, BYTE div );


COLORREF WINAPI GradientColor( COLORREF c1, COLORREF c2, WORD Ix, WORD Length );


COLORREF WINAPI GrayScaleColor( COLORREF rgb );

//++ RGB byte order swappers

#ifdef _MSC_VER
//--! @ingroup bswap

DWORD __cdecl _swapRGB( DWORD rgba ); // _bswap.asm

//--! @ingroup bswap

DWORD __cdecl _swapRGB2( DWORD rgb ); // -"-

#else
  // Sorry; No GCC/GAS/NASM implementation, nor any C fallback yet...
#endif//def _MSC_VER

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


HFONT WINAPI CreateFontEx( 
    CSTR Typeface,          //<! Typeface name, e.g "Arnold Boecklin".
    int Points,             //<! Font size, in typographic points (1/72" ea).
    int Weight,             //<! Font weight, e.g. FW_BOLD. 
    DWORD Charset DEF_(ANSI_CHARSET), //<! Character set, e.g. ANSI_CHARSET.
    DWORD Quality DEF_(ANTIALIASED_QUALITY) //<! Font quality, e.g. ANTIALIASED_QUALITY.
    );


int WINAPI FontHeight( HDC hdc, int Points );
int WINAPI ScreenFontHeight( WORD Points ); 


HFONT WINAPI GetWndFont( HWND hWnd, OPTOUT LOGFONT* pLogFont );

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


POINT WINAPI WhereXY( HDC dc );


HDC WINAPI ReleaseWndDC( HDC hdc );

// Desktop DC

HDC  WINAPI GetDesktopDC(); 
void WINAPI ReleaseDesktopDC( HDC hDeskDC ); 


HDC WINAPI CreateMemoryDC( UINT cx, UINT cy, OPTOUT HBITMAP* pOldBmp DEF_(NULL) );


HBITMAP WINAPI DeleteMemoryDC( HDC hMemDC, OPTIN HBITMAP oldBmp DEF_(NULL) );


void WINAPI GetScreenLPI( PPOINT pLpi );


HGDIOBJ WINAPI GetCurrentObjectEx( HDC hdc, UINT ObjType, PVOID pObjData );

#define OBJ_DIBSECTION  (GDI_OBJ_LAST+1) 
#define GetCurrentFontEx( dc, plfont )   (HFONT) GetCurrentObjectEx( dc, OBJ_FONT, PLOGFONT(plfont) )
#define GetCurrentPenEx( dc, plpen )     (HPEN) GetCurrentObjectEx( dc, OBJ_PEN, PLOGPEN(plpen) )
#define GetCurrentExtPenEx( dc, pelpen ) (HPEN) GetCurrentObjectEx( dc, OBJ_EXTPEN, PEXTLOGPEN(pelpen) )
#define GetCurrentBrushEx( dc, plbrsh )  (HBRUSH) GetCurrentObjectEx( dc, OBJ_BRUSH, PLOGBRUSH(plbrsh) )
#define GetCurrentBitmapEx( dc, pbmap )  (HBITMAP) GetCurrentObjectEx( dc, OBJ_BITMAP, PBITMAP(pbmap) )
#define GetCurrentDibSectEx( dc, pdibs ) (HBITMAP) GetCurrentObjectEx( dc, OBJ_DIBSECTION, PDIBSECTION(pdibs) )
#define GetCurrentPaletteEx( dc, pwrd )  (HPALETTE) GetCurrentObjectEx( dc, OBJ_PAL, PWORD(pwrd) )
#define GetCurrentColorspaceEx( dc, pcs ) (HCOLORSPACE) GetCurrentObjectEx( dc, OBJ_COLORSPACE, PLOGCOLORSPACE(pcs) )

#if 0 // Sundown: DataSize used to be an argument, as in GetObject().
// As of x64, unfortunately, the LOGBRUSH.lbHatch x64 HANDLE
// makes sizeof(LOGBRUSH) == sizeof(LOGPEN), thus defeating the
// original switch statement in the function, forcing an API change.

HGDIOBJ WINAPI GetCurrentObjectEx( HDC hdc, int DataSize, PVOID pObjData );
#define GetCurrentFontEx( dc, plfont )   (HFONT)GetCurrentObjectEx( dc, sizeof(LOGFONT), plfont )
#define GetCurrentPenEx( dc, plpen )     (HPEN)GetCurrentObjectEx( dc, sizeof(LOGPEN), plpen )
#define GetCurrentExtPenEx( dc, pelpen ) (HPEN)GetCurrentObjectEx( dc, sizeof(EXTLOGPEN), pelpen )
#define GetCurrentBrushEx( dc, plbrsh )  (HBRUSH)GetCurrentObjectEx( dc, sizeof(LOGBRUSH), plbrsh )
#define GetCurrentBitmapEx( dc, pbmap )  (HBITMAP)GetCurrentObjectEx( dc, sizeof(BITMAP), pbmap )
#define GetCurrentDibSectEx( dc, pdibs ) (HBITMAP)GetCurrentObjectEx( dc, sizeof(DIBSECTION), pdibs )
#define GetCurrentPaletteEx( dc, pwrd )  (HPALETTE)GetCurrentObjectEx( dc, sizeof(WORD), pwrd )
#define GetCurrentColorspaceEx( dc, pcs ) (HCOLORSPACE)GetCurrentObjectEx( dc, sizeof(LOGCOLORSPACE), pcs )
#endif

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

HBITMAP WINAPI CreateIconBitmap(
    HICON hIcon, HBRUSH hbrBkg, UINT cx DEF_(0), UINT cy DEF_(0)
    );


HBITMAP WINAPI CreateMaskBitmap( HBITMAP img, COLORREF transp );

// CreateAntialiasedBitmap() ...


struct PAINTBMPSTRUCT
{
    HDC     hDC;        
    RECT    rcPaint;    
    UINT    mu;         
    PVOID   ctx;        
};


typedef bool (__stdcall *PFnPaintBitmap)( PAINTBMPSTRUCT* p );


HBITMAP WINAPI CreateAntialiasedBitmap( 
    UINT cx, UINT cy,   
    UINT mu,            
    PFnPaintBitmap PaintBitmap, 
    PVOID Ctx           
    );


bool WINAPI DrawMaskedBitmap( HDC hdc, int x, int y, HBITMAP hBmp, HBITMAP hMask );


bool WINAPI DrawTransparentBitmap( // preliminary
    HDC hdc, int x, int y, int w, int h, HBITMAP hBmp, COLORREF cTrans
    );


void WINAPI DrawBitmap( HDC hdc, int x, int y, HBITMAP hBmp );


void WINAPI DrawBitmapEx(
    HDC hdc, int x, int y, int cx, int cy,
    HBITMAP hBmp, int imx DEF_(0), int imy DEF_(0), int imw DEF_(0), int imh DEF_(0),
    DWORD rasterOp DEF_(SRCCOPY)
    );

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

#define VTX_OPAQUE      0x00 
#define VTX_TRANSPARENT 0xFF 


void WINAPI SetTriVertex(
    PTRIVERTEX pVtx, int x, int y, COLORREF cr, BYTE Alpha DEF_(VTX_OPAQUE)
    );

void WINAPI SetTriMesh( PGRADIENT_TRIANGLE pTri, UINT Vtx1, UINT Vtx2, UINT Vtx3 );

void WINAPI SetRectMesh( PGRADIENT_RECT pRect, UINT TopLeft, UINT BotRight );


void WINAPI DrawGradientRect( HDC hdc, PRECT pr, COLORREF c1, COLORREF c2, UINT type );

#define GRADIENT_H  GRADIENT_FILL_RECT_H 
#define GRADIENT_V  GRADIENT_FILL_RECT_V 
#define GRADIENT_D  (GRADIENT_FILL_TRIANGLE+1) 

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


int WINAPI MapRegionToWindow( HRGN hRgn, HWND hWnd );


RGNDATA* WINAPI AllocAndGetRegionData( IN HRGN hRgn, OPTOUT PRECT* ppRc );
RGNDATA* WINAPI FreeRegionData( RGNDATA* pRgn ); 

#if _DEBUG 
void WINAPI DumpRegionData( CSTR Title, HRGN hRgn );
#else
#define DumpRegionData(Title,hRgn)
#endif

// Path/Region supplements.


typedef struct _gdiPathData
{
    LPPOINT pPoint;  
    LPBYTE  pType;   
    RECT    Bounds;  
    int     nPoints; 
}
*PGdiPathData, GdiPathData;


bool WINAPI GetGdiPathData( HDC hdc, OUT PGdiPathData pData );


void WINAPI FreeGdiPathData( PGdiPathData pData );


bool WINAPI GetGdiPathBounds( HDC hdc, PRECT pBounds );


HRGN WINAPI GetGdiPathRgn( HDC hdc, OUT RGNDATA** ppRgnData, OPTOUT RECT** ppRgnRects );

#if 0 // Superfluous, use PathToRegion() and GetRgnBox() if this is all you need.
HRGN WINAPI GetGdiPathRgnBounds( HDC hdc, OUT PRECT pBounds ); // see src for edification.
#endif


void OffsetPoints( POINT* Pts, UINT nPts, int dx, int dy );


void OffsetRgnData( PRGNDATA prd, int dx, int dy );


void SetIdentityMat2( MAT2* pm );

//++++++++++++++++++++++++++++++++

#define RR_CLIPRGN  1 
#define RR_METARGN  2 
#define RR_APIRGN   3 
#define RR_SYSRGN   SYSRGN 

//++++++++++++++++++++++++++++++++


#define ClearXform( pxfm ) SetXformScale( pxfm, 1.0f, 1.0f )


#define AppendXform( Dst, append ) \
    CombineTransform( (XFORM*)(Dst), (XFORM*)(Dst), (XFORM*)(append) )


#define PrependXform( Dst, prepend ) \
    CombineTransform( (XFORM*)(Dst), (XFORM*)(prepend), (XFORM*)(Dst) )


XFORM* SetXformTranslate( XFORM* pxfm, float dx, float dy );


XFORM* SetXformScale( XFORM* pxfm, float dx, float dy );


XFORM* SetXformRotate( XFORM* pxfm, double angle );


XFORM* SetXformShear( XFORM* pxfm, float sx, float sy );


XFORM* SetXformReflect( XFORM* pxfm, bool rx, bool ry );

//+============================================================================
//|
//|
//+============================================================================


#define OPEN_FILE( name,access ) \
    CreateFile( name, access, FILE_SHARE_READ, &DefSec, OPEN_EXISTING, 0,0 )


HANDLE OpenDirectory( CSTR DirPath, DWORD Flags );

// Known File/Device namespace prefixes, all (except UNC case) are 4 chars long...

#define LONG_PATH_PREFIX_A      "\\\\?\\"   
#define LONG_UNC_PREFIX_A       LONG_PATH_PREFIX_A "UNC\\" 
#define DEVICE_NAME_PREFIX_A    "\\\\.\\"   
#define UNPARSED_NAME_PREFIX_A  "\\??\\"    

#define LONG_PATH_PREFIX_W      L"\\\\?\\"  
#define LONG_UNC_PREFIX_W       LONG_PATH_PREFIX_W L"UNC\\" 
#define DEVICE_NAME_PREFIX_W    L"\\\\.\\"  
#define UNPARSED_NAME_PREFIX_W  L"\\??\\"   

#ifdef _UNICODE
    #define LONG_PATH_PREFIX     LONG_PATH_PREFIX_W
    #define LONG_UNC_PREFIX      LONG_UNC_PREFIX_W
    #define DEVICE_NAME_PREFIX   DEVICE_NAME_PREFIX_W
    #define UNPARSED_NAME_PREFIX UNPARSED_NAME_PREFIX_W
#else
    #define LONG_PATH_PREFIX     LONG_PATH_PREFIX_A
    #define LONG_UNC_PREFIX      LONG_UNC_PREFIX_A
    #define DEVICE_NAME_PREFIX   DEVICE_NAME_PREFIX_A
    #define UNPARSED_NAME_PREFIX UNPARSED_NAME_PREFIX_A
#endif


ACSTR SkipPathPrefixA( ACSTR PathName );
WCSTR SkipPathPrefixW( WCSTR PathName ); 

#ifdef _UNICODE
  #define SkipPathPrefix SkipPathPrefixW
#else
  #define SkipPathPrefix SkipPathPrefixA
#endif

//-----------------------------------------------------------------------------

bool FileExist( CSTR PathName );  
bool DirExist( CSTR PathName );   

bool IsDir( LPWIN32_FIND_DATA pFd ); 
bool IsSubdirName( CSTR Dir );       
bool IsSubdir( LPWIN32_FIND_DATA pFd ); 

bool IsJunctionDir( CSTR PathName ); 
bool IsSymLink( CSTR PathName );     
bool IsSymLinkDir( CSTR PathName );  


bool IsVolumeMountPoint( CSTR PathName, TSTR VolNameBuf DEF_(NULL), UINT ccBuf DEF_(0) );


bool GetWin32FileData( CSTR PathName, LPWIN32_FIND_DATA pFd );


UINT64 SetFilePos( HANDLE hFile, INT64 Offset, UINT How );
UINT64 GetFilePos( HANDLE hFile ); 

#define GetFilePointer( hFile,pHiPart ) SetFilePointer( hFile, 0, (PLONG)pHiPart, FILE_CURRENT )

bool   Seek( HANDLE hFile, LONG Offs, DWORD How ); 
UINT   Tell( HANDLE hFile ); 

bool   IsEndOfFile( HANDLE hFile ); 

UINT64 GetFileSize64( HANDLE hFile ); 
UINT64 GetFileSize64Ex( CSTR FName ); 
UINT64 GetFileSizeByName( CSTR FName ); 

UINT PeekFile( HANDLE hFile, PVOID Buf, UINT nBytes ); 

UINT BlockRead( HANDLE hFile, PVOID Buf, UINT nBytes ); 
UINT BlockWrite( HANDLE hFile, PVOID Buf, UINT nBytes ); 


BOOL WriteLine( HANDLE hFile, CSTR Buf, UINT ccBuf DEF_(0) );


UINT __cdecl WriteStrA( HANDLE hFile, const char* Fmt, ... );
UINT __cdecl WriteStrW( HANDLE hFile, const wchar_t* Fmt, ... );


UINT ReadLineA( HANDLE hFile, char* Buffer, UINT BufLength, bool TrimCrLf );
UINT ReadLineW( HANDLE hFile, wchar_t* Buffer, UINT BufLength, bool TrimCrLf ); 

#ifdef _UNICODE
#define WriteStr    WriteStrW
#define ReadLine    ReadLineW
#else
#define WriteStr    WriteStrA
#define ReadLine    ReadLineA
#endif


TSTR GetPathFileName( TSTR PathName );


UINT GetFileNameFromHandle( HANDLE hFile, OUT TSTR Buffer, UINT BufLen );

UINT GetNtDeviceName( HANDLE hObj, OUT TSTR DevNameBuf, UINT BufLen );     // WIP: Traits TBD.
DWORD GetDosNameFromNtDeviceName( IN CSTR NtName, OUT TSTR DosName, UINT ccDosName ); // dito.


UINT DevicePathToDosPath( IN CSTR DevPath, OUT TSTR PathBuf, UINT ccPathBuf );


CSTR ChangeDirectory( CSTR Dir );


CSTR DoneDirectory( CSTR prevDir );


bool FindMoreFiles(
    HANDLE hFind, WIN32_FIND_DATA* Found,
    OPTIN BYTE nTries DEF_(1), OPTIN BYTE msWait DEF_(50)
    );


HANDLE FindCloseEx( HANDLE hFind );


CSTR GetTempPathName( CSTR Prefix, CSTR dotExt );


ULARGE_INTEGER GetAttributeAndReparseTag( CSTR PathName );


bool  GetFileInformationByName( CSTR FileName, LPBY_HANDLE_FILE_INFORMATION pInfo );


bool GetVolumeGuidOfShare(
    IN CSTR ShareName, OUT TSTR VolGuid, WORD ccGuid, OPTOUT TSTR DosDrv, WORD ccDrv
    );


bool GetVolumeGuidOfDevice(
    IN CSTR DevName, OUT TSTR VolGuid, WORD ccGuid, OPTOUT TSTR DosDrv, WORD ccDrv
    );


bool CreateJunctionDir( CSTR LinkName, CSTR TargetPath, CSTR PrintName );
// PONDER: bool CreateJunctionDir( CSTR LinkName, CSTR TargetPath, CSTR PrintName, bool AllowUpdate DEF_(false) );
// > AllowUpdate allows update of the link target of an existing junction dir if true.
// > If false, the function will fail with ERROR_FILE_EXISTS if LinkName exist.


bool DeleteJunctionDir( CSTR LinkName );


bool CreateSymLink( CSTR LinkName, CSTR TargetPath, CSTR PrintName );


bool RemoveReparseData( CSTR PathName );


INT GetReparseTarget(
    IN CSTR LinkName,
    OUT TSTR SubstPath, UINT cchSubst, OPTOUT TSTR PrintName, UINT cchPrint,
    OPTOUT PULARGE_INTEGER AttrTag 
    );


UINT GetHardLinkCount( CSTR FileName );


bool _CreateHardLink( CSTR LinkName, CSTR TargetName ); // From my 1999 sources.

#if (WINVER >= 0x0600) // FindFirstFileNameW & FindFirstStreamW requires Vista.


typedef bool (__stdcall *PFnEnumHardLinks)( CSTR PathName, PVOID usrData );


UINT EnumerateHardLinks(
    CSTR FileName,           
    PFnEnumHardLinks Action, 
    PVOID UserData           
    );


typedef bool (__stdcall *PFnEnumStreams)( CSTR PathName, UINT64 Size, PVOID usrData );


UINT EnumerateFileStreams( CSTR FileName, PFnEnumStreams Action, PVOID usrData );

// TODO: UINT GetStreamCount( CSTR FileName ); // (If possible..)

#endif//(WINVER >= 0x0600)
//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

DECLARE_HANDLE( HMAPFILE ); 

// Executable mappings are supported by Windows since XP2.
// Define ALLOW_EXECUTABLE_FILEMAPPING as 0 to disallow it.
#define ALLOW_EXECUTABLE_FILEMAPPING  0


HMAPFILE LoadAndMapFile( CSTR FName, DWORD PageAccess, PBYTE* ppData );


BOOL     UnloadMappedFile( HMAPFILE hMap );

PVOID    GetMappedFilePointer( HMAPFILE hMap ); 
UINT64   GetMappedFileSize( HMAPFILE hMap );    

#if 1 // Holdover for the old names..
  #define GetMappedPointer  GetMappedFilePointer
  #define GetMappedSize     GetMappedFileSize
#endif

#if 0 // Under consideration, expandable mapping
HMAPFILE LoadAndMapFileEx(
    CSTR FileName, DWORD PageAccess, PBYTE* ppData,
    UINT64 MaxSize DEF_(0), CSTR MapName DEF_(NULL)
    );
#endif


size_t PeekMappedFile( HMAPFILE hMapFile, PVOID Buffer, size_t cbRead );
size_t ReadMappedFile( HMAPFILE hMapFile, PVOID Buffer, size_t cbRead );
size_t WriteMappedFile( HMAPFILE hMapFile, PVOID Buffer, size_t cbWrite );
PBYTE  GetMappedFilePtr( HMAPFILE hMapFile );
PBYTE  SetMappedFilePtr( HMAPFILE hMapFile, INT64 Offset, UINT How );
UINT64 GetMappedFilePos( HMAPFILE hMapFile );
UINT64 SetMappedFilePos( HMAPFILE hMapFile, INT64 Offset, UINT How );

END_EXTERN_C
#endif//ndef __UtilFunc_h_incl__
// EOF