HBWIN - Petewg/harbour-core GitHub Wiki

πŸ”™Home

HBWIN library documentation

For a complete catalog of available functions (names only), see hbwin.hbx. Currently, not all of these functions are documented here (nor in any other site, as far as I know). However, most of hbwin library functions are actually wrappers for WinAPI[1] functions (conventionally prefixed by wapi_ or win_), so, taking a look at relevant MS Docs sites (f.e.: here or here) can provide helpful documentation about their usage.

[1]Since Windows10 release, the WinAPI has significantly evolved. Here is an interesting article about "Upgrade your code to the Universal CRT" that might be worth reading.


  • wapi_AddFontResourceEx(<cFontFile>, <nLoadFlag>) ➜ nResult

    adds (loads) the font resource(s) from the specified <cFontFile> file to the system. Fonts added with this function can be marked as private and not enumerable by utilizing <nLoadFlag>.
    Supported font files are: .fon, .fnt, .ttf, .ttc, .fot, .otf, .mmm, .pfb, .pfm
    Value of <nLoadFlag> can be either: FR_PRIVATE (0x10) or FR_NOT_ENUM (0x20) or the sum of them. (Detailed documentation by MS here).
    Function returns the number of fonts added or zero on failure.
    IMPORTANT NOTE: When the added font resource(s) are no more needed, must be removed by calling the wapi_RemoveFontResourceEx() function (see below).

  • wapi_CopyFile(<cSourceFileName>, <cDestinationFileName>, [<lNoOverwrite>]) ➜ lResult

    This function attempts to copy an existing file to a new one.
    - <cSourceFileName> is the name of an existing file to be copied. If it doesn't exist the function fails and wapi_GetLastError() returns ERROR_FILE_NOT_FOUND.
    - <cDestinationFileName> is the name of the new file.
    - If <lNoOverwrite> is FALSE (or not passed at all) and the new file specified by <cDestinationFileName> already exists, the function overwrites the existing file. If it's TRUE and the new file already exists, the function fails. In any case (and regardless of <lNoOverwrite>), if the destination file already exists and has the FILE_ATTRIBUTE_HIDDEN or FILE_ATTRIBUTE_READONLY attribute set, the function will fail with ERROR_ACCESS_DENIED.
    - Returns .T. on success or .F. on failure. Use wapi_GetLastError() to retrieve a specific error description.
    ❗NOTE: this function is available in Harbour 3.4 fork only! I'm citing it here because a) it's a nice function --I do use it already in my personal hb 3.2 build πŸ™‚ and b) it should be adapted and merged into official Harbour 3.2

  • wapi_CreateDC([<cDriver>], [<cDeviceName>], [<cOUtput>], <pDeviceMode>) ➜ hDC`

    creates a device context (DC) for a device using the specified name.
    <cDriver>, is a string that specifies either "DISPLAY" or the name of a specific display device. According to MS documentation for printing, it is recommended this argument to be NIL because GDI ignores <cDriver> for printer devices.
    <cDeviceName>, is string that specifies the name of the specific output device being used, as shown by the Print Manager, f.e., Epson FX-80 (it is not the printer model name). If <cDriver> is "DISPLAY", then <cDeviceName> must be NIL, so that a DC is created for the primary display device.
    <cOUtput>, this is a compatibility parameter, it is ignored and should be NIL.
    <pDeviceMode>, pointer to a DEVMODE structure containing device-specific initialization data for the device driver. Use __wapi_DEVMODE_New() to initialize (create) the structure, __wapi_DEVMODE_Set() to populate it with the proper values and __wapi_DEVMODE_Get() to retrieve set values. Must be NIL, if <cDriver> is "DISPLAY".
    If the function succeeds, the return value is the handle to a DC (device context) for the specified device, otherwise, the return value is NIL.
    Hint: study this sample, found into /hbwin/tests/ folder, to see how to use these functions.

  • wapi_CreateFont([nHeight, nWidth, nEscapement, nOrientation, nWeight, lItalic, lUnderline, lStrikeOut, nCharSet, nOutputPrecision, nClipPrecision, nQuality, nPitchAndFamily, cFontFaceName]) ➜ hFont
    This function "creates a logical font with the specified characteristics. The logical font can subsequently be selected as the font for any device." Worth noting that all the above (fourteen!) parameters are optional; even if <cFontFaceName> is NIL or empty string, the first font that matches the other specified attributes is used. (and what if no other attributes specified? ;-))
    The function returns a handle to a logical font on success, or NIL on failure.
    See detailed documentation by MS here, also (non-MS) here.

  • wapi_CreateFontIndirect([<hHash>|<aArray>]) ➜ hFont
    Similar to the above function. Difference is that, instead of individual parameters, the font attributes must be passed either as a hash table or array with structure identical to LOGFONT structure, as it has been defined by the MS.

  • __wapi_DEVMODE_New(<cDeviceName>) ➜ pDEVMODE
    Returns pointer to a DEVMODE structure for the device (printer or screen) <cDeviceName> specified.
    Note that not all members (fields) of this quite big DEVMODE structure are supported. Currently the supported fields include: "dmOrientation", "dmPaperSize", "dmPaperLength", "dmPaperWidth", "dmScale", "dmCopies", "dmDefaultSource", "dmPrintQuality", "dmDuplex".

  • __wapi_DEVMODE_Set(<pDEVMODE>, <hashToWriteFrom>) ➜ NIL
    sets values for specific members (see above) of <pDEVMODE> structure.

  • __wapi_DEVMODE_Get(<pDEVMODE>, <hashToReadInto>) ➜ NIL
    retrieves values of specific members of <pDEVMODE> structure.

  • wapi_ResetDC(<hDC>, <pDeviceMode>) ➜ lResult
    This function updates the specified (printer or plotter) device context <hDC> using the specified <pDeviceMode> information. Returns TRUE on success, FALSE otherwise.

  • wapi_DrawText(<hDC>, <cText>, <ahRECT>, [<nFormatMethod>]) ➜ nHeight
    Draws formatted text in the specified rectangle. It formats the text according to the specified format (i.e. expanding tabs, justifying characters, breaking lines, et.c.). See hbwin.ch and DrawText documentation at MS, for available formats (they can be used in any valid combination).
    <ahRECT> is an array or hash table with structure ['left', 'top', 'right', 'bottom'] that specifies the rectangle in logical coordinates, in which the text is to be formatted. Note that upon successful termination of function, this array / hash shall contain the rectangle coordinates used (or going to be used (in case empty array/hash passed)) for text drawing (also note that on function failure, these values shall be zero!). If the function succeeds, the return value is the height of the text in logical units. If WIN_DT_VCENTER or WIN_DT_BOTTOM is specified with <nFormatMethod>, the return value is the offset from 'top' to the 'bottom' of the drawn text. If the function fails, the return value is zero.

  • wapi_ExtTextOut(<hDC>, [nPosX, nPosY, fuOptions, aRect, cString, aFontWidths]) ➜ lSuccess
    (to do!) This function draws text on specified <hDC> device, using the currently selected font, background color and text color. (See also, MS documentation)

  • wapi_FindWindow([cClassName], [cWindowName]) ➜ hWnd
    returns a handle to the top-level window whose window name (i.e. title) match the cWindowName.
    ❗IMPORTANT REMARK: The hWnd returned by this function is a pointer (valtype == P).
    Use win_P2N() , if it's needed, (as it is the case in MiniGUI library, for example) to convert it to a usable numeric handler (and win_N2P() to convert back a numeric handler to a pointer).
    This remark may apply for all functions of the HBWIN library that use and/or return handles. (particularly, if hb-3.4 fork is used).

  • wapi_FreeLibrary([<hLib>]) ➜ lSucces
    Frees (unloads) a previously loaded dynamic-link library (DLL) module.
    <hLib> is the handle that had been returned by a previously invoked wapi_LoadLibrary(Ex) function.
    Returns TRUE on success, otherwise FALSE.

  • wapi_GetACP() ➜ nCodePage
    Returns the current Windows ANSI Code Page Identifier for the operating system. (Returned value can be used, f.e., to translate text to or from Unicode).

  • wapi_GetActiveWindow() ➜ hWnd

  • wapi_GetCurrentProcess() ➜ hProcess
    Returns a pseudo handle to the current process. See more here...

  • wapi_GetCurrentProcessId() ➜ nProcID
    Returns the process identifier (integer) of the calling process, which uniquely identifies it throughout the system, until it's termination.

  • wapi_GetLastError() ➜ nErrorCode
    returns the calling thread's last-error code value. As stated by MS "The last-error code is maintained on a per-thread basis. Multiple threads do not overwrite each other's last-error code."

  • wapi_GetLongPathName(<cShortPath>, [@cLongPath] [, nLengthLimit]) ➜ nLongLength
    Converts the specified <cShortPath> path to its long form.

  • wapi_GetModuleHandle([<cModuleName>]) ➜ hModuleHandle
    Returns a module handle for the specified <cModuleName> module. If no module specified, returns a handle to the executable file itself. If the function fails, the return value is NULL. To get extended error information, use wapi_GetLastError().

  • wapi_GetProcAddress(<hModuleHandle>, <cFuncName>|nPos>) ➜ pAddress
    Returns the address of an exported function or variable from a DLL specified by its handle.
    <hModuleHandle> is the handle to the DLL module that contains the function or variable, (this handle can be obtained, f.e., by wapi_LoadLibrary() or wapi_GetModuleHandle() functions that return such a suitable handles).
    <cFuncName>|nPos> is the function or variable name, or the function's ordinal value.
    If the function fails, the return value is NULL. Use wapi_GetLastError() to get error information.\

  • wapi_GetOEMCP() ➜ nOEMCodePageID
    Returns the current OEM code page identifier for the operating system.
    See Code Page Identifiers at MS.

  • wapi_GetShortPathName(<cLongPath>, [@cShortPath] [, nLengthLimit]) ➜ nShortLenght
    Retrieves the short path form of the specified <cLongPath> path.

  • wapi_GetSystemDirectory() ➜ cSystemDirectoryFullPath
    retrieves the path of the system directory (f.e. C:\Windows\system32)

  • wapi_GetSystemMetrics(<nParam>) ➜ xSystemMetricsValue
    Returns the value of the the requested <nParam> system metric or 0 (zero) on failure.
    See hbwin.ch for available wapi_GetSystemMetrics() parameters (#defined constants). See also GetSystemMetrics() function doc by MS.

  • wapi_GetVolumeInformation(<cRootPath>, @<cVolumeName>, @<nVolSerialNumber>, @<nMaxComponentLength>, @<nFileSystemFlags>, @<cFileSystemName>) ➜ lSuccess
    Retrieves various info about the file system and volume associated with the root directory specified by <cRootPath> If <cRootPath> is not specified the root of the current directory is used. Normally, should be given as X:\, where X is the letter assigned to logical disk drive which is examined.
    Relevant information is stored to each corresponding parameter that must be passed by reference.
    See also: Windows API function GetVolumeInformation().

  • wapi_GetWindowsDirectory() ➜ cWindowsDirectoryFullPath
    retrieves the path of the windows directory (f.e. C:\Windows)

  • wapi_IsIconic(<hWnd>) ➜ .T.|.F.

  • wapi_IsUserAnAdmin() ➜ .T.|.F.

  • wapi_IsWindow(<hWnd>) ➜ .T.|.F.

  • wapi_IsZoomed(<hWnd>) ➜ .T.|.F.

  • wapi_LoadImage([<hInstance>],<cName>,[<nType>],[<nWidth>],[<nHeight>],[<nFlags>]) ➜ hImage
    Loads an icon, cursor, animated cursor, or bitmap. For more about specific parameters, please refer MS documentation.

  • wapi_LoadLibraryEx([<cDllName>], NIL, [<nFlags>]) ➜ hLib
    Returns a handle (pointer) to the loaded <cDllName> module. If the function fails, the return value is NIL.
    For <nFlags> possible values and meaning, see this MS page.

  • wapi_LoadLibrary([<cDllName>]) ➜ hLib
    Returns a handle (pointer) to the loaded <cDllName> module. If the function fails, the return value is NIL.
    For more details see this MS page.

  • wapi_MessageBeep(<nType>) ➜ lOk
    Plays a waveform sound of a certain type. refer to hbwin.ch for nTypes.

  • wapi_MessageBox([<hWnd>], [<cMessageText>], [<cCaption>], [<nType>]) ➜ nButtonClicked
    returns the constant integer value, assigned to button clicked. NOTE: this value is not the positional (ordinal) number of the button (as is f.e. in Alert() function).

    • refer to MSDN for more. Also, refer to hbwin.ch for supported nTypes.
  • wapi_MessageBoxTimeout(<phWnd>,<cText>,<cCaption>,<nType>,<nLangId>,<nTimeout>) ➜ nButtonClicked | WIN_MB_TIMEDOUT
    similar to above function, but with timeout option. <nTimeout> is the time to wait, expressed in milliseconds, after which the messagebox closes. Returns either a WIN_MB_TIMEDOUT value (#include "hbwin.ch"), indicating the wait-time was run out, or a constant integer value, assigned to button clicked, (exactly like to above wapi_MessageBox() function). Note: when the message box has only the [OK] button, the return value is always 1.

  • wapi_MulDiv(<nNumber>, <nNumerator>, <nDenominator>) ➜ nResult
    Multiplies two 32-bit values (<nNumber>, <nNumerator>) and then divides the 64-bit result by a third 32-bit value (<nDenominator>).
    If the function succeeds, the return value is the result of the multiplication and division, rounded to the nearest integer. If either an overflow occurred or nDenominator was 0 (zero), the return value is -1.
    Remark: Chances are this function is buggy?! Try this:

    ? 1234567890 * 3 / 1              // --> 3703703670.00
    ? wapi_MulDiv( 1234567890, 3, 1 ) // --> -1

    Given that the function is an one-line-wrapper for MulDiv(), seems that the "bug" isn't actually originating from HBWIN library.

  • wapi_PlaySound(<cSound>, <hModule>, <nFlags>) ➜ .T.|.F.
    This function plays a sound specified by the given <cSound> which can be either a system event sound (e.g.: "SoundExclamation") or a file name (e.g.: "mysound.wav") or a sound resource contained in executable file pointed by <hModule>.
    Returns TRUE if successful or FALSE otherwise. See MSDN for detailed documentation, as well as, hbwin.ch for supported <nFlags>.
    example usage:

     #include "hbwin.ch"
     // play the system event `Exclamation` sound
     wapi_PlaySound( "SystemExclamation", 0, WIN_SND_ALIAS + WIN_SND_ASYNC ) 
     // play a wave sound file
     wapi_PlaySound("mySound.wav", 0, WIN_SND_FILENAME + WIN_SND_ASYNC )
  • wapi_QueryDosDevice( <cDeviceName> ) ➜ aResults
    Retrieves information about MS-DOS device names.

  • wapi_QueryPerformanceCounter( <@nCounter> ) ➜ lSuccess
    Β«Retrieves the current value of the performance counter, which is a high resolution time stamp (with an accuracy of less than 1 ΞΌs) that can be used for time-interval measurementsΒ».(reference: MS)

  • wapi_QueryPerformanceFrequency( <@nFrequency> ) ➜ lSuccess
    Β«Retrieves the frequency of the performance counter. The frequency of the performance counter is fixed at system boot and is consistent across all processors. Therefore, the frequency need only be queried upon application initialization, and the result can be cachedΒ». (reference: MS)

  • wapi_RemoveFontResourceEx(<cFontFile>, <nLoadFlag>) ➜ nResult
    removes, from the system font table, font resources (previously added by wapi_AddFontResourceEx()).
    parameter arguments (<cFontFile>, <nLoadFlag>) must be the same as those that have been used when the font resources added with wapi_AddFontResourceEx() (see above).
    If the function succeeds, the return value is nonzero, otherwise (on failure) it's zero.

  • wapi_SetErrorMode(<nErrorMode>) ➜ nPrevSetting
    Controls whether the system will handle the specified types of serious errors or whether the process will handle them. Returns the previous setting of the error-mode. See more at this MSDN article.

  • wapi_SetFocus(<hWnd>) ➜ prevhWnd
    Sets the keyboard focus to the specified window. Returns the handle to the window that previously had the keyboard focus. If the hWnd parameter is invalid or the window is not attached to the calling thread's message queue, the return value is NULL.

  • wapi_SetLastError(<nErrorCode>) ➜ NIL
    Sets the last-error code for the calling thread.

  • wapi_ShellExecute([<hWnd>],[<cOperation>],[<cFile>],[<cParameters>],[<cDirectory>],[<nShowCmd>]) ➜ nResult
    Performs an operation on a specified file.
    PARAMETERS:

    • hWnd, handle to parent window (can be 0 or NIL).
    • cOperation, string, also known as verb, that specifies the action to be performed.
      Valid verbs: edit, explore, find, open, print, runas, properties(?), NULL. (The set of available verbs depends on the particular file or folder).
    • cFile, filename or folder name on which operation is performed.
    • cParameters, string that specifies executable-file parameters.
    • cDirectory, string that specifies default (working) directory.
    • nShowCmd flags determining how the window is shown when opened.

    (Read complete documentation of ShellExecute at MSDN)
    (Also see the possible values for <nShowCmd> flag(s) that specify how an application is to be displayed when it is opened.
    Returns a value greater than 32 on success, or an errorcode (less/equal 32) on failure; (see below table of possible errors)

    #DEFINE VALUE DESCRIPTION
    0 The operating system is out of memory or resources.
    SE_ERR_FNF 2 The specified file was not found.
    SE_ERR_PNF 3 The specified path was not found.
    SE_ERR_ACCESSDENIED 5 The operating system denied access to the specified file.
    SE_ERR_OOM 8 There was not enough memory to complete the operation.
    ERROR_BAD_FORMAT 11 The .exe file is invalid (non-Win32 .exe or error in .exe image).
    SE_ERR_SHARE 26 A sharing violation occurred.
    SE_ERR_ASSOCINCOMPLETE 27 The file name association is incomplete or invalid.
    SE_ERR_DDETIMEOUT 28 The DDE transaction could not be completed because the request timed out.
    SE_ERR_DDEFAIL 29 The DDE transaction failed.
    SE_ERR_DDEBUSY 30 The DDE transaction could not be completed because other DDE transactions were being processed.
    SE_ERR_NOASSOC 31 There is no application associated with the given file name extension. This error will also be returned if you attempt to print a file that is not printable.
    SE_ERR_DLLNOTFOUND 32 The specified DLL was not found.
  • wapi_ShellExecute_Wait([<hWnd>],[<cOperation>],[<cFile>],[<cParameters>],[<cWorkDirectory>],[<nShowCmd>]) ➜ lSuccess
    The function is similar to wapi_ShellExecute() (see above), but it waits for the completion of <cOperation> before returning to caller. The program flow is suspended until the asked operation, that been initiated by this function, is signaled, which practically happens upon its termination (this does not necessarily means and the completion/termination of any other process triggered by the operation, f.e., the termination of an editor opened to edit the cFile).

  • wapi_ShowWindow(<hWnd>, [<nShowCmd>]) ➜ lPrevShowState
    Sets the show state of the the window pointed out by <hWnd>, according to <nShowCmd> parameter. Possible values for <nShowCmd> are SW_HIDE, SW_NORMAL, SW_MINIMIZE, SW_MAXIMIZE, SW_RESTORE etc.
    The function returns TRUE if the window was previously visible, otherwise FALSE(if window was hidden). Use wapi_GetLastError() to determine whether the function succeeded or not to set the new show state.
    ❗NOTE: this function is new, provided with this Dec 29, 2018 commit, therefore is not available in earlier versions.
    See also: ShowWindow function at MSDN.

  • wapi_Sleep(<nMilliseconds>) ➜ NIL
    suspends the execution of the current thread until the <nMilliseconds> (expressed in milliseconds) time-out interval elapsing.

  • wapi_StartDoc(<hDC>, [<hDocInfo>]) ➜ nPrintJobID
    documentation in Harbour Enchiridion ... (if 404, then you need access, in which case, follow Luke 11:9 suggestion).

  • wapi_TextOut(<hDC>, [<nPosX>], [<nPosY], [<cString>]) ➜ lSuccess
    This function draws a string on specified <hDC> device at a given [x,y] position, using the currently selected font, background and text color.
    (For more, see MS documentation)

  • win_bitmapIsSupported(<hDC>, <cBMPbuffer>) ➜ nRetval
    returns 0 if supported, < 0 otherwise.

  • win_bitmapType(<cBMPbuffer>) ➜ nType
    returned values: 1=BMP, 2=JPEG, 3=PNG, 0=UNKNOWN.

  • win_DrawBitmap(<hDC>, <cBMPbuffer>, nLeft, nTop, nRight, nBottom, nWidth, nHeight) ➜ lSuccess
    (TODO!)

  • win_EnumFonts( [<hDC>] ) ➜ aFonts
    enumerates the fonts available on a specified <hDC> device.
    returns array of sub-arrays of all available fonts for the device given, where each sub-array corresponds to each enumerated font instance. Structure of sub-array is: {cFacename, lFixedPitch, lTrueType, nCharset}
    If <hDC> omitted, default is screen.

  • win_EnumFontFamilies([<hDC>], [<cFaceName>]) ➜ aFonts
    It's similar to above win_EnumFonts() but accepts an optional <cFaceName> argument that limits enumaration on the given face (font) name only.
    Returns array of sub-arrays of the given font instances, if available, (or all available fonts, when <cFaceName> omitted) for the specified device, where each sub-array corresponds to each enumerated font instance. Structure of sub-array is: {cFacename, lFixedPitch, lTrueType, nCharset}
    If no <hDC> specified, default is screen.
    Worth to note that MS is suggesting the usage of this function, instead of win_EnumFonts(), which "is provided only for compatibility with 16-bit versions of Windows".

  • win_GetCommandLineParam() ➜ cParams
    returns a string with command line parameters that have been passed upon program startup or empty string if no params passed.

  • win_GetOpenFileName([[@]<nFlags>], [<cTitle>], [<cInitDir>], [<cDefExt>], [<acFilter>], [[@]<nFilterIndex>], [<nBufferSize>], [<cDefName>]) ➜ cFilePath | cPath + e"\0" + cFile1 [ + e"\0" + cFileN ] | ""
    Opens a file selection dialog and lets user to select a file or files. It returns either:
    ➜ cFullPathFilename if only one file selected, or
    ➜ a cList of items delimited by a null char Chr(0) containing the FilePath (first item) and the filenames (following items without path), if more than one file selected, or
    ➜ empty string if no file selected (e.g. when dialog canceled by user).

  • win_GetPrinterFontName(<hPrinterDC>) ➜ cFontName
    Get the font name that Windows actually used.

  • win_GetSaveFileName([[@]<nFlags>], [<cTitle>], [<cInitDir>], [<cDefExt>], [<acFilter>], [[@]<nFilterIndex>], [<nBufferSize>], [<cDefName>]) ➜ cFilePath | cPath + e"\0" + [ + e"\0" + cFileN ] | ""
    Opens a Save file dialog box and lets the user specify the drive, directory, and name of a file to save.
    Returns same value(s) as the above win_GetOpenFileName() function.

  • win_GetCharSize(<hDC>, [<lHeight>]) ➜ nWidth|nHeight
    Returns either the width or height (when <lHeight> is not NIL and defined as .T.) of font characters in used. If, for whatever reason, the function fail, zero is returned. ( see also: wapi_CreateDC() )

  • win_GetDeviceCaps() ➜ (TODO!)

  • win_GetDocumentProperties() ➜ (TODO!)

  • win_GetTextSize(<hDC>, <cString>, [<nLength>], [<lWidth>]) ➜ nWidth|nHeight
    Calculates, in device units, the width or height that will be needed to show up on device <hDC>, either the entire string <cString> or a portion of it, as defined by <nLength> which, if it's bigger than Len() of <String>, is reasonably reduced to equal that. If <lWidth> specified as .T. or ommited (in which case defaults to .T.) the value returned represents width otherwise the height of text. If, for whatever reason, the function fail, zero is returned.

  • win_LoadBitmapFile(<cBMPFile>) ➜ cBMPbuffer

  • win_LoadResource( [<cResourceName>]|[, <cResourceType>]) ➜ hResourceHanle

  • win_N2P(<nNum>) ➜ pPointer
    converts an unsigned numeric value to a value of type pointer.
    ❕REMARK: After this commit, this function, as well as win_P2N(), have been both removed from hb 3.4, therefore, users of hb 3.4 fork might need to take a look at this and this note, for a potential workaround.

  • win_P2N(<pPointer>) ➜ nNum
    converts a value of type pointer to unsigned numeric value.
    ❕REMARK: removed from hb 3.4 (see above remark).

  • Windows version checking functions
    The functions referenced in the table below, are used to check whether the Windows version running, conforms to the inquired specific version or not. They return .T. or .F. respectively.

    Function name Returns .T. when Windows version is
    win_osIs95() Windows '95
    win_osIs98() Windows '98
    win_osIs9x() Windows '95 or '98
    win_osIsME() Windows Millenium
    win_osIs2000() Windows 2000
    win_osIs2000OrUpper() Windows 2000 or later
    win_osIs2003() Windows Server 2003
    win_osIsXP() Windows XP
    win_osIsWinXPOrUpper() Windows XP or later
    win_osIsVista() Windows Vista
    win_osIsVistaOrUpper() Windows Vista or later
    win_osIs7() Windows 7
    win_osIs8() Windows 8
    win_osIs81() Windows 8.1
    win_osIs10() Windows 10
    win_osIsNT() Windows NT or later
    win_osIsNT351() Windows NT 3.51
    win_osIsNT4() Windows NT 4.0
    win_osIsTSClient() Terminal Services client session

    For detailed version info, see win_osVersionInfo() below

  • win_osNetRegOk([<lSetIt>], [<lDoVista>]) ➜ .T. | .F.
    This function checks and optionally sets Windows Registry settings, for safe LAN networking.
    If <lSetIt> defined .T. (when omitted, it defaults to .F.) then this function attempts to create/set the appropriate registry key-values, needed to resolve opportunistic locking issues encounterd on all versions of Windows! The <lDoVista> flag (default is .T.) determines whether the function will operate on VISTA (or later) windows versions.
    ❗IMPORTANT: To change the relevant registry settings 'Administrator rights' are required!
    See also this thread on habour-users group.

  • win_osNetVRedirOk( @nResult ) ➜ .T. | .F.
    Checks legacy Win9x systems if they are vredir.vxd ready.

  • win_osVersionInfo() ➜ aInfo
    returns array with version info elements: { nMajorVersion, nMinorVersion, nBuildNumber, nPlatformId, cServicePack}. for more see OSVERSIONINFO @ msdn

  • win_PrintDataRaw(<cPrinter>, <cData> [,<cDocName>]) ➜ nBytesPrinted
    It's similar to 'win_PrintFileRaw()' (see below) but sends to the given <cPrinter> printer the data specified by the 2nd parameter <cData>, instead of the file body. It returns the number of printed bytes, or negative value on error.

  • win_PrintDlgDC([@<cDevice>],[<nFromPage>],[<nToPage>],[<nCopies>])➜ hDC
    Opens a Print Dialog Box, allowing user to select printer and/or change print settings. If device selection succeeded, the function returns a hDC, which is handle (pointer) to a Device Context, for the selected device (printer). The <cDevice> parameter, when passed by reference, will receive the name of selected printer.
    If the Dialog Box canceled by user or, for whatever reason, the function failed, then the returned value is NULL pointer (zero) and if <cDevice> had been passed by reference, it is not affected (i.e. it retains its initial value).

  • win_printerExists(<cPrinterName>) ➜ lExists
    checks if cPrinterName printer is present. Won't check (i.e. returns .F.) legacy device names like "LPTn[:]", "COMn[:]".

  • win_printerGetDefault() ➜ cDefaultPrinterName
    returns the name of the default printer for the current user on the local computer.

  • win_printerList([lPrinterNamesOnly] [, lLocalPrintersOnly]) ➜ aPrinterList
    returns 1-dim array with PrinterNames if 1st par==.F., or array of array(s) for each printer with struct: { "PrinterName", "Port", "Type"(LOCAL/NETWORK), "DriverName", "ShareName", "ServerName" } NOTE: "Type" value is not always accurate. f.e.: network printer connected to ip-port is referred as LOCAL.

  • win_printerPortToName(<cPort>) ➜ cPrinterName
    returns the name of printer connected to cPort. empty string will be returned if no printer is connected or on error. cPort can be a plain port name such as "LPT1:", "USB001" or ip address like "192.168.1.50" et.c.

  • win_printerSetDefault(<cPrinterName>) ➜ lSuccess
    sets cPrinterName as default printer.

  • win_printerStatus([<cPrinterName>]) ➜ nStatus
    returns status of cPrinterName printer, or status of default printer if no cPrinterName specified. nStatus==0 means no error (?), any other value denotes some kind of error; evidently, wrong/invalid printer names will return error (-1).

  • win_PrintFileRaw(<cPrinterName>, <cFileName>) ➜ nBytesWritten
    sends contents of file cFileName to printer cPrinterName. Returns number of bytes printed or negative value on error.

  • win_QPCounter2Sec(<nCounter>) -> nSeconds
    It converts to seconds the difference between two calls to wapi_QueryPerformanceCounter(),
    that can be used to measure time of code execution (time-interval measurements).
    for example:

   // grab/store starting point into `nCounterStart`
   wapi_QueryPerformanceCounter( @nCounterStart )
   [...] // lines of code, for which
   [...] // we want to measure execution time-interval.
   // grab/store ending point into `nCounterEnd`
   wapi_QueryPerformanceCounter( @nCounterEnd )
   ? "total execution time in secs: " 
   // convert the difference into seconds
   ?? win_QPCounter2Sec( nCounterEnd - nCounterStart ), " sec."

Windows registry functions (incomplete...)
NOTE: Useful sample code, that demonstrates the usage of various registry functions, can be found into /contrib/hbwin/tests/ folder, here.

  • win_regCloseKey() ➜ x??? (TODO!)

  • win_regCreateKeyEx() ➜ x??? (TODO!)

  • win_regDelete( cRegPath, nRegSam ) ➜ lResult

  • win_regDeleteKey( nHKEY, cKey ) ➜ lResult

  • win_regDeleteValue( pKeyHandle, cEntry ) ➜ lResult

  • win_regGet( nHKEY, cKeyName, cEntryName, xDefault, nRegSam ) ➜ xValue

  • win_regOpenKeyEx( nHKEY, cKey, 0, nSamDesired, @pKeyHandle ) ➜ lResult

  • win_regPathSplit( cRegPath, @nHKEY, @cKey, @cEntry ) ➜ (Nothing)

  • win_regQuery( nHKEY, cKeyName, cEntryName, xValue, lSetIt, nRegSam ) ➜ lResult

  • win_regQueryValueEx( pKeyHandle, cEntryName, 0, @nValueType, @xRetVal ) ➜ NIL

  • win_regRead( cRegPath, xDefault, nRegSam ) ➜ xValue

  • win_regSet( nHKEY, cKeyName, cEntryName, xValue, nValueType, nRegSam ) ➜ lResult

  • win_regSetValueEx() ➜ x??? (TODO!)

  • win_regWrite( cRegPath, xValue, nType, nRegSam ) ➜ lResult

  • win_ReportEvent([cUNCServerName],<cSourceName>,<nType>,<nCategory>,<nEventID>,<cMessage|acMessages>,[cRawData]) ➜ lResult
    "Writes an entry at the end of the specified event log."
    cUNCServerName: The Universal Naming Convention (UNC) name of the remote server on which this operation is to be performed. If this parameter is NULL, the local computer is used.
    cSourceName: The name of the event source whose handle is to be retrieved. The source name must be a subkey of a log under the Eventlog registry key. Note that the Security log is for system use only.
    nType: The type of event to be logged. This parameter can be one of the following values.

    #Macro Value Meaning
    WIN_EVENTLOG_SUCCESS 0x0000 Information event
    WIN_EVENTLOG_AUDIT_FAILURE 0x0010 Failure Audit event
    WIN_EVENTLOG_AUDIT_SUCCESS 0x0008 Success Audit event
    WIN_EVENTLOG_ERROR_TYPE 0x0001 Error event
    WIN_EVENTLOG_INFORMATION_TYPE 0x0004 Information event
    WIN_EVENTLOG_WARNING_TYPE 0x0002 Warning event

    nCategory: The event category. This is source-specific information; the category can have any value. For more information, see Event Categories.
    nEventID : The event identifier. The event identifier specifies the entry in the message file associated with the event source. For more information, see Event Identifiers.
    cMessage|acMessages: String or array of strings that will be displayed to the user by Windows Event Viewer.
    cRawData: buffer containing the binary data. (optional)
    example usage: lSuccess := win_ReportEvent( NIL, "MyApplication", WIN_EVENTLOG_SUCCESS, 0, 0, { "Stop running", "Start diving" } )

  • win_serviceControl(<cServiceName>, <nControlCode>) ➜ lResult
    Sends a control code to a service.
    cServiceName: The name of the service to send the control-code. This is the ServiceName used to install the service by win_serviceInstall().
    nControlCode: The control-code to be send. See here possible values of control codes.

  • win_serviceDelete(cServiceName, lStop) ➜ lResult

  • win_serviceGetStatus ➜ nStatus
    returns current status of service. See below possible return values as defined in hbwin.ch

    MACRO VALUE (nStatus)
    WIN_SERVICE_NO_CHANGE 0xFFFFFFFF
    WIN_SERVICE_STOPPED 1
    WIN_SERVICE_START_PENDING 2
    WIN_SERVICE_STOP_PENDING 3
    WIN_SERVICE_RUNNING 4
    WIN_SERVICE_CONTINUE_PENDING 5
    WIN_SERVICE_PAUSE_PENDING 6
    WIN_SERVICE_PAUSED 7
  • win_serviceInstall(cServiceName, cDisplayName, cPath, nStartType, cAccountName, cPassword) ➜ lSuccess

  • win_serviceRun

  • win_serviceSetExitCode

  • win_serviceSetStatus

  • win_serviceStart

  • win_serviceStop

  • win_ShellNotifyIcon([<hWnd>], [<nUID>], [<nMessage>], [<hIcon>], [<cTooltip>], [<lAddDel>], [<cInfo>], [<nInfoTimeOut>], [<cInfoTitle>], [<nInfoFlags>]) ➜ lOK
    Sends a message to the taskbar's status area.

  • win_SHFileOperation([<hWnd>], [<nFunction>], [<cFrom>|<aFrom>], [<cTo>|<aTo>], [<nFlags>], [<@lAnyOperationAborted>], [<aNameMappings>], [<cProgressTitle>]) ➜ nResult
    Performs ordinary O/S level file manipulation operations like copy, move, rename, delete.

  • win_SysRefresh(<nMilisecs>) ➜ 0
    Forces system events processing which may means that it "dispatches incoming sent messages, checks the thread message queue for a posted message, and retrieves the message (if any exist)" (MS). Can (must?) be used/invoked inside heavy processing loops to avoid the application stops responding. (That's my best I figured out, after investigating function's core-source code :-) --any better documentation is welcome).

  • win_Unicode() ➜ .T.|.F.
    checks if UNICODE encoding is in use or not.

  • win_UuidCreateString(<@nRPCStatus>) ➜ cUUID
    If succeed, returns a stringified UUID (Universally Unique Identifier) or empty string on failure.
    Possible values acquired via passed by reference <nRPCStatus> include:

    Value Meaning
    RPC_S_OK (0) The call to function succeeded. A valid UUID created.
    RPC_S_UUID_LOCAL_ONLY (1824) The UUID is guaranteed to be unique to this computer only.
    RPC_S_UUID_NO_ADDRESS (1739) Cannot get Ethernet or token-ring hardware address for this computer.

πŸ”

πŸ”™ Home

⚠️ **GitHub.com Fallback** ⚠️