====== GetWindowsDirectory() ======

The [[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/sysinfo/base/getwindowsdirectory.asp|GetWindowsDirectory()]] function, implemented in KERNEL32.DLL,  returns the full path name of the directory in which Windows is installed.  Its declaration in OpenInsight is found in the DLL_KERNEL32 record in the SYSPROCS table, shown below:

UINT   STDCALL GetWindowsDirectoryA(LPCHAR, UINT) AS GETWINDOWSDIRECTORY

The ANSI version of the GetWindowsDirectory() function is aliased.  Two arguments are required:

  * LPCHAR (a pointer to a character buffer), which will contain the default windows directory after a successful call.  The character buffer must be large enough to contain the //largest// string that could be returned from GetWindowsDirectory(), including a trailing byte containing CHAR(0).
  * UINT (an unsigned integer), the size of the buffer, in bytes.  The buffer should be initialized to spaces, using the [[str|Str()]] function or the [[space|Space()]] function.

GetWindowsDirectory() returns a UINT which contains the actual size of the returned string.  This can be used by a function, such as [[msg|Msg()]], to manipulate the result.

==== Example ====
 
Below is sample code, from the click event of a button, that calls [[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/sysinfo/base/getwindowsdirectory.asp|GetWindowsDirectory()]] and displays the result.

<code> 
declare function GetWindowsDirectory
 
winDirectory = str(' ',255)
 
retval = GetWindowsDirectory( winDirectory, 255)
 
call msg(@window, 'Default Windows Directory is ' : winDirectory[1,retval])
</code>

On Line 1, GetWindowsDirectory is declared as a function, like a standard OpenInsight function.

On Line 2, the variable winDirectory is initialized, using the [[str|str()]] function, to a string containing 255 spaces.

On Line 3, GetWindowsDirectory is called.  After a successful call, winDirectory contains the string (including the terminating Char(0), and retval contains the number of characters (without the terminating Char(0)) in the string.

Finally, on Line 4, the [[msg|msg()]] function is called, displaying the path.  Note how only the characters actually returned are displayed.