IFileOperation::NewItem method (shobjidl_core.h)

Article
02/22/2024

Declares a new item that is to be created in a specified location.

Syntax

HRESULT NewItem(
  [in] IShellItem                 *psiDestinationFolder,
  [in] DWORD                      dwFileAttributes,
  [in] LPCWSTR                    pszName,
  [in] LPCWSTR                    pszTemplateName,
  [in] IFileOperationProgressSink *pfopsItem
);

Parameters

[in] psiDestinationFolder

Type: IShellItem*

Pointer to an IShellItem that specifies the destination folder that will contain the new item.

[in] dwFileAttributes

Type: DWORD

A bitwise value that specifies the file system attributes for the file or folder. See GetFileAttributes for possible values.

[in] pszName

Type: LPCWSTR

Pointer to the file name of the new item, for instance Newfile.txt. This is a null-terminated, Unicode string.

[in] pszTemplateName

Type: LPCWSTR

Pointer to the name of the template file (for example Excel9.xls) that the new item is based on, stored in one of the following locations:

CSIDL_COMMON_TEMPLATES. The default path for this folder is %ALLUSERSPROFILE%\Templates.
CSIDL_TEMPLATES. The default path for this folder is %USERPROFILE%\Templates.
%SystemRoot%\shellnew

This is a null-terminated, Unicode string used to specify an existing file of the same type as the new file, containing the minimal content that an application wants to include in any new file.

This parameter is normally NULL to specify a new, blank file.

[in] pfopsItem

Type: IFileOperationProgressSink*

Pointer to an IFileOperationProgressSink object to be used for status and failure notifications. If you call IFileOperation::Advise for the overall operation, progress status and error notifications for the creation operation are included there, so set this parameter to NULL.

Return value

Type: HRESULT

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

This method does not create the new item, it merely declares the item to be created. To create a new item, you must make at least the sequence of calls detailed here:

Call IFileOperation::NewItem to declare the specifics of the new file or folder.
Call IFileOperation::PerformOperations to create the new item.

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2008 [desktop apps only]
Target Platform	Windows
Header	shobjidl_core.h (include Shobjidl.h)