IShellLibrary::Save method (shobjidl_core.h)

Article
10/13/2021

Saves the library to a new Library Description (*.library-ms) file.

Syntax

HRESULT Save(
  [in]  IShellItem       *psiFolderToSaveIn,
  [in]  LPCWSTR          pszLibraryName,
  [in]  LIBRARYSAVEFLAGS lsf,
  [out] IShellItem       **ppsiSavedTo
);

Parameters

[in] psiFolderToSaveIn

Type: IShellItem*

The IShellItem object that specifies the folder in which to save the library, or NULL to save the library with the user's default libraries in the FOLDERID_Libraries known folder.

[in] pszLibraryName

Type: LPCWSTR

The file name under which to save the library. The file name must not include the file name extension; the file name extension is added automatically.

[in] lsf

Type: LIBRARYSAVEFLAGS

The LIBRARYSAVEFLAGS value that specifies how to handle a library name collision.

[out] ppsiSavedTo

Type: IShellItem**

The IShellItem object that represents the library description file into which the library was saved.

Return value

Type: HRESULT

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

Remarks

IShellLibrary::Save and SHSaveLibraryInFolderPath create a new library file, and save the file to disk. To save changes made to a library that has an existing library file, call IShellLibrary::Commit.

If the library is saved in the Libraries known folder (FOLDERID_Libraries), the library's location is automatically added to the system index.

For convenience, SHSaveLibraryInFolderPath can be used in place of this method.

Examples

The following code example shows the helper function SHSaveLibraryInFolderPath, which wraps this method.

//
// from shobjidl.h
//
__inline HRESULT SHSaveLibraryInFolderPath(
    __in IShellLibrary *plib, 
    __in PCWSTR pszFolderPath, 
    __in PCWSTR pszLibraryName, 
    __in LIBRARYSAVEFLAGS lsf, 
    __deref_opt_out PWSTR *ppszSavedToPath
)
{
    if (ppszSavedToPath)
    {
        *ppszSavedToPath = NULL;
    }

    IShellItem *psiFolder;
    HRESULT hr = SHCreateItemFromParsingName(
      pszFolderPath, 
      NULL, 
      IID_PPV_ARGS(&psiFolder));

    if (SUCCEEDED(hr))
    {
        IShellItem *psiSavedTo;
        hr = plib->Save(psiFolder, pszLibraryName, lsf, &psiSavedTo);

        if (SUCCEEDED(hr))
        {
            if (ppszSavedToPath)
            {
                hr = psiSavedTo->GetDisplayName(
                  SIGDN_DESKTOPABSOLUTEPARSING, 
                  ppszSavedToPath);
            }
            psiSavedTo->Release();
        }
        psiFolder->Release();
    }
    return hr;
}

Requirements

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