Edit

ITransferDestination::CreateItem method (shobjidl_core.h)

  • Article

Creates the specified file.

Syntax

HRESULT CreateItem(
  [in]  LPCWSTR               pszName,
  [in]  DWORD                 dwAttributes,
  [in]  ULONGLONG             ullSize,
  [in]  TRANSFER_SOURCE_FLAGS flags,
  [out] REFIID                riidItem,
  [out] void                  **ppvItem,
  [in]  REFIID                riidResources,
  [out] void                  **ppvResources
);

Parameters

[in] pszName

Type: LPCWSTR

A pointer to a null-terminated buffer that contains the name of the file relative to the current directory.

[in] dwAttributes

Type: DWORD

One or more of the FILE_ATTRIBUTE flags defined in the BY_HANDLE_FILE_INFORMATION structure. The most significant value is FILE_ATTRIBUTE_DIRECTORY, which indicates that a folder should be created.

[in] ullSize

Type: ULONGLONG

The size, in bytes, of the file to create. This value can be 0 if the size is unknown.

[in] flags

Type: TRANSFER_SOURCE_FLAGS

Flags that control the file operation. One or more of the TRANSFER_SOURCE_FLAGS flags.

[out] riidItem

Type: REFIID

A reference to the IID of the interface to retrieve through ppvItem, typically IID_IShellItem or another interface that derives from it.

[out] ppvItem

Type: void**

When this method returns, contains the interface pointer requested in riidItem. This is typically IShellItem or a derived interface.

[in] riidResources

Type: REFIID

A reference to the IID of the interface to retrieve through ppvResources, typically IID_IShellItemResources or another interface that derives from it.

[out] ppvResources

Type: void**

When this method returns, contains the interface pointer requested in riidResources. This is typically IShellItemResources or a derived interface.

Return value

Type: HRESULT

Returns a success code if successful, or an error value otherwise. Success codes include:

  • S_OK: The move succeeded and ppvItem and ppvResources both point to valid objects.
  • COPYENGINE_S_USER_IGNORED: The destination item already exists and has not been overwritten. The values pointed to by ppvItem and ppvResources are NULL. If the caller is implementing a move as a copy and delete operation, the caller should complete the move by deleting the source item.

Remarks

This method may be used to create a Shell item object representing the destination folder for a copy or move operation. The ITransferSource interface provides methods to actually move objects of IShellItem to the destination.

Call ITransferDestination::Advise before calling any other ITransferDestination methods so the handler can callback on any errors that might occur. If not set, the handler should consider it an indication that no feedback is available and to do the "default" operation.

It is recommended that you use the IID_PPV_ARGS macro, defined in Objbase.h, to package the riidResources and ppvResources parameters. This macro provides the correct IID based on the interface pointed to by the value in ppvResources, which eliminates the possibility of a coding error.

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)