IShellLibrary::LoadLibraryFromItem method (shobjidl_core.h)

Article
02/22/2024

Loads the library from a specified library definition file.

Syntax

HRESULT LoadLibraryFromItem(
  [in] IShellItem *psiLibrary,
  [in] DWORD      grfMode
);

Parameters

[in] psiLibrary

Type: IShellItem*

An IShellItem object for the library definition file to load. An error is returned if this object is not a library.

[in] grfMode

Type: DWORD

One or more STGM storage medium flags that specify access and sharing modes for the library object.

Return value

Type: HRESULT

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

Remarks

If this method is called on an IShellLibrary object that is already loaded, the contents of that object are overwritten in memory with the new information.

If there is no existing library object, SHLoadLibraryFromItem can be called in place of this method.

Examples

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

//
// from shobjidl.h
//
__inline HRESULT SHLoadLibraryFromItem(
    __in IShellItem *psiLibrary,
    __in DWORD grfMode,
    __in REFIID riid,
    __deref_out void **ppv
)
{
    *ppv = NULL;
    IShellLibrary *plib;

    HRESULT hr = CoCreateInstance(
      CLSID_ShellLibrary, 
      NULL, 
      CLSCTX_INPROC_SERVER, 
      IID_PPV_ARGS(&plib));

    if (SUCCEEDED(hr))
    {
        hr = plib->LoadLibraryFromItem (psiLibrary, grfMode);
        if (SUCCEEDED(hr))
        {
            hr = plib->QueryInterface (riid, ppv);
        }
        plib->Release();
    }
    return hr;
}

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

//
// from shobjidl.h
//
__inline HRESULT SHLoadLibraryFromParsingName(
    __in PCWSTR pszParsingName,
    __in DWORD grfMode,
    __in REFIID riid,
    __deref_out void **ppv
)
{
    *ppv = NULL;
    IShellItem *psiLibrary;
    HRESULT hr = SHCreateItemFromParsingName (
      pszParsingName, 
      NULL, 
      IID_PPV_ARGS(&psiLibrary));

    if (SUCCEEDED(hr))
    {
        hr = SHLoadLibraryFromItem (psiLibrary, grfMode, riid, ppv);
        psiLibrary->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)