SHPathPrepareForWriteW function (shlobj_core.h)
Checks to see if the path exists. This includes remounting mapped network drives, prompting for ejectable media to be reinserted, creating the paths, prompting for the media to be formatted, and providing the appropriate user interfaces, if necessary. Read/write permissions for the medium are not checked.
Syntax
SHSTDAPI SHPathPrepareForWriteW(
[in, optional] HWND hwnd,
[in, optional] IUnknown *punkEnableModless,
[in] LPCWSTR pszPath,
DWORD dwFlags
);
Parameters
[in, optional] hwnd
Type: HWND
A handle to a window that specifies the parent window to be used for any user interface windows that must be created. If set to NULL, user interface windows are not created.
[in, optional] punkEnableModless
Type: IUnknown*
A pointer to an IUnknown interface that specifies the IOleInPlaceActiveObject object that implements the EnableModeless method.
[in] pszPath
Type: LPCTSTR
A pointer to a null-terminated string of maximum length MAX_PATH that specifies the path to be verified as valid for writing. This can be a UNC or file drive path.
dwFlags
Type: DWORD
Flags that determine behavior options. This parameter can be a combination of the following values.
SHPPFW_NONE
Do not create new directories.
SHPPFW_DEFAULT
Default. Do not prompt the user if a directory needs to be created. This is identical to SHPPFW_DIRCREATE. Do not pass with SHPPFW_ASKDIRCREATE.
SHPPFW_DIRCREATE
Create directories without prompting the user. Do not pass with SHPPFW_ASKDIRCREATE.
SHPPFW_ASKDIRCREATE
Prompt the user before creating directories. Do not pass with SHPPFW_DIRCREATE.
SHPPFW_IGNOREFILENAME
Last item in pszPath is a file name, so ignore. For example, if pszPath="C:\MyDir\MyFile.doc", only use "C:\MyDir". If pszPath="C:\MyFirDir\MySecDir", only use "C:\MyFirDir".
SHPPFW_NOWRITECHECK
Not currently implemented.
SHPPFW_MEDIACHECKONLY
Windows XP or later. Suppresses the "not accessible" error message box, which displays when a failure other than a user cancellation occurs, and hwnd is not NULL.
Return value
Type: HRESULT
Returns S_OK if the path is available, or an error code otherwise. Note that a return value of S_OK does not mean that the medium is writable; it simply means that the path is available.
Remarks
The primary use of this function is for a program to check a path before using it and display the necessary user interface to prompt the user. For example, if the disk in drive A: were missing, a window that prompts the user to insert the disk would appear.
Note
The shlobj_core.h header defines SHPathPrepareForWrite as an alias that automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that is not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
Requirements
Requirement | Value |
---|---|
Minimum supported client | Windows 2000 Professional [desktop apps only] |
Minimum supported server | Windows 2000 Server [desktop apps only] |
Target Platform | Windows |
Header | shlobj_core.h (include Shlobj.h, Shlobj_core.h) |
Library | Shell32.lib |
DLL | Shell32.dll (version 5.0 or later) |