To access both of the file common dialogs the OPENFILENAME structure is used. Prior to Windows 2000 this UDT was 76 bytes long, with sTemplateName as the last member. With the introduction of Windows XP and the Shell version 5 common dialogs, the OPENFILENAME structure added three new members increasing the size of the UDT to 88 bytes:

Public Type OPENFILENAME
  nStructSize       As Long
  hWndOwner         As Long
  hInstance         As Long
  sFilter           As String
  sCustomFilter     As String
  nMaxCustFilter    As Long
  nFilterIndex      As Long
  sFile             As String
  nMaxFile          As Long
  sFileTitle        As String
  nMaxTitle         As Long
  sInitialDir       As String
  sDialogTitle      As String
  flags             As Long
  nFileOffset       As Integer
  nFileExtension    As Integer
  sDefFileExt       As String
  nCustData         As Long
  fnHook            As Long
  sTemplateName     As String
  pvReserved        As Long  'new in Windows 2000 and later
  dwReserved        As Long  'new in Windows 2000 and later
  flagsEx           As Long  'new in Windows 2000 and later
End Type

Many of the members in the type are recognizable from the similar properties exposed by the VB file common control. To assist in understanding the following code, a lengthy discussion of each member is below. Following that is a discussion on using this UDT in applications running on pre-Windows 2000 machines.

nStructSize is common among many Windows UDTs. As more features are added to Windows controls, the number of members of a structure often change. For example, the definition of the OPENFILENAME structure during Windows 9x through Windows NT4 did not contain the last three members. Windows 2000 and later use the three additional parameters added to the end of the type to provide additional functionality. This type is also required on Windows 2000 and later when utilizing a hook to maintain the places bar in the explorer style. By providing the UDT with a nStructSize member, the receiving API can determine which version of the structure is being used thus whether to ignore any members beyond the size passed. See below for a further discussion.

hWndOwner is also common, and specifies the window owner the dialog, and therefore receives messages from the control or its error messages.

hInstance - If the OFN_ENABLETEMPLATEHANDLE flag is set in the Flags member, hInstance is a handle to a memory object containing a dialog box template. If the OFN_ENABLETEMPLATE flag is set, hInstance is a handle to a module that contains a dialog box template named by the sTemplate member. If neither flag is set, this member is ignored. If the OFN_EXPLORER flag is set, the system uses the specified template to create a dialog box that is a child of the default Explorer-style dialog box. If the OFN_EXPLORER flag is not set, the system uses the template to create an old-style dialog box that replaces the default dialog box.

sFilter - buffer containing pairs of null-terminated filter strings. The last string in the buffer must be terminated by two NULL characters. The first string in each pair is a display string that describes the filter (for example, "Text Files"), and the second string specifies the filter pattern (for example, "*.TXT"). To specify multiple filter patterns for a single display string, use a semicolon to separate the patterns (for example, "*.TXT;*.DOC;*.BAK"). A pattern string can be a combination of valid file name characters and the asterisk (*) wildcard character. Do not include spaces in the pattern string. The system does not change the order of the filters. It displays them in the File Types combo box in the order specified in sFilter.

nFilterIndex specifies an index into the buffer pointed to by sFilter. The system uses the index value to obtain a pair of strings to use as the initial filter description and filter pattern for the dialog box. The first pair of strings has an index value of 1. When the user closes the dialog box, the system copies the index of the selected filter strings into this location.

sFile points to a buffer that contains a filename used to initialize the File Name edit control. The first character of this buffer must be vbNullChar if initialization is not necessary. When the GetOpenFileName or GetSaveFileName function returns, this buffer contains the drive designator, path, filename, and extension of the selected file(s). The demo code below passes "Untitled.bas" as the initial filename, along with a buffer of an additional 1024 chrs for the return selection.

sFileTitle points to a buffer that receives the file name and extension (without path information) of the selected file. If this member is vbNullChar, the function does not copy the file name.

Assuming a buffer is passed for both sFile and sFileTitle, the difference between the these two members can be seen when a multiple file selection dialog is used (flag OFN_ALLOWMULTISELECT). In a single selection, both sFile and sFileTitle return the same data. But when multiple files are selected, sFileTitle returns empty, while sFile contains a null-separated string containing the users selection (up to the max chrs passed in the sFile buffer).

nMaxFile - the size of the buffer pointed to by sFile. The buffer must be large enough to store the path and file name string or strings, including the terminating null character. GetOpenFileName and GetSaveFileName return False if the buffer is too small to contain the file selected information. The buffer should be at least 260 characters long.

nMaxTitle - the size, of the buffer pointed to by sFileTitle. This member is ignored if sFileTitle is vbNullChr.

sInitialDir is a pointer to a null terminated string that can specify the initial directory. The algorithm for selecting the initial directory varies on different platforms (taken from the MSDN).

• Windows 2000/Windows XP:
• If sFile contains a path, that path is the initial directory.
• Otherwise, sInitialDir specifies the initial directory.
• If sInitialDir is NULL and the current directory contains any files of the specified filter types, the initial directory is the current directory.
• Otherwise, if the application has used an Open or Save As dialog box in the past, the path most recently used is selected as the initial directory. However, if an application is not run for a long time, its saved selected path will be discarded.
• Otherwise, the initial directory is the personal files directory of the current user.
• Otherwise, the initial directory is the Desktop folder
  
• Windows 98:
• sInitialDir specifies the initial directory.
• If sInitialDir is NULL and sFile contains a path, that path is the initial directory.
• Otherwise, if the current directory contains any files of the specified filter types, the initial directory is the current directory.
• Otherwise, the initial directory is the personal files directory of the current user.

• Earlier versions of Windows and Windows NT/ 2000:
• sInitialDir specifies the initial directory.
• If sInitialDir is NULL and sFile contains a path, that path is the initial directory.
• Otherwise, the initial directory is the current directory.

flags - bit flags you can use to initialize the dialog box. When the dialog box returns, it sets these flags to indicate the user's input. This member can be a combination of the following flags (within the bounds of the target OS). This is an abbreviated version of the same listing in the MSDN:

nFileOffset specifies the zero-based offset from the beginning of the path to the file name in the string pointed to by sFIle. For example, if sFIle points to the following string, "c:\dir1\dir2\file.ext", this member contains the value 13 to indicate the offset of the "file.ext" string. If the user selects more than one file, nFileOffset is the offset to the first file name.

nFileExtension specifies the zero-based offset in chrs from the beginning of the path to the file name extension in the string pointed to by sFIle. For example, if sFIle points to the following string, "c:\dir1\dir2\file.ext", this member contains the value 18. If the user did not type an extension and sDEfFileExt is NULL, this member specifies an offset to the terminating null character. If the user typed "." as the last character in the file name, this member specifies zero.

sDefFileExt is a pointer to a buffer that contains the default extension. GetOpenFileName and GetSaveFileName append this extension to the file name if the user fails to type an extension. This string can be any length, but only the first three characters are appended. The string should not contain a period. If this member is NULL and the user fails to type an extension, no extension is appended.x

fnHook - address to a hook (callback). This member is ignored unless the Flags member includes the OFN_ENABLEHOOK flag.

sCustomFilter, nMaxCustFilter, nCustData, sTemplateName are not covered in this demo. The MSDN has full information on these members.

API Return Values:

If the user specifies a file name and clicks the OK button, the return value is nonzero. The buffer pointed to by the sFIle member of the OPENFILENAME structure contains the full path and file name specified by the user. If the user cancels or closes the Open dialog box or an error occurs, the return value is zero.

Note too that the GetOpenFileName and GetSaveFileName dialogs only provide the means for the user to chose files. Although the File Save function may ask to overwrite an existing file, no actual overwriting will occur -- coding a file save method is the responsibility of the developer.

For a discussion on OPENFILENAME structure issues specific to Windows 2000/Windows XP, see GetOpenFileName: File Dialog Centering using a Callback.

With the descriptions out of the way, the code to implement the common dialogs is straightforward.

GetOpenFileName: File Open Common Dialog Basics

GetSaveFileName: File Save Common Dialog Basics

For a discussion on modifying the OPENFILENAME structure in order to display the new Windows 2000 or Windows XP-style Open and Save dialogs, please see the comments section in the page GetOpenFileName: File Dialog Centering using a Callback (note: a hook is not required to display this new-style dialog - it just so happens that page is the one I chose to explain this on.)

Windows' New Open and Save Dialog Style

Beginning with Windows 2000, the OPENFILENAME structure was extended to include three additional parameters specific to Windows 2000 and Windows XP. These additions change the size of the structure passed as the .nStructSize member which Windows uses to determine whether it should display the old or new-style dialogs. However, passing the new extended structure on a Win9x or NT4 system will result in the Open File or Save File dialog not being displayed at all.  Thankfully, because of the nStructSize parameter, you can go ahead and define the type with the new members regardless of the system, and then during the call identify the operating system in use and modify the value passed as the nStructSize parameter as appropriately.

To assure that the new dialog appears as expected, you must ensure that Len(OFN) is passed as the nStructSize parameter, and likewise to ensure the dialog appears on lower versions of windows, you can pass Len(OFN - 12) (12 = 3 longs of 4 bytes each). 

Probably the best way to ensure the correct value is passed is through declaration of three variables in your code:

Public OSV_VERSION_LENGTH as Long
Private Const OSV_LENGTH As Long = 76
Private Const OSVEX_LENGTH As Long = 88

Then use a routine to assign one of the two OSV length values to a variable and assign that to nStructSize.