wraps the IShellItem interface and exposes methods that retrieve information about a Shell item. IShellItem and IShellItem2 are the preferred representations of items in any new code.
| AutoHotkey | AHK v2 alpha |
| OS | Windows XP SP1 / Windows Server 2003 or higher |
| Base classes | Unknown |
| Helper classes | SIGDN, SFGAO, SICHINT |
| ShellItem | wraps the IShellItem interface and exposes methods that retrieve information about a Shell item. |
| IID | This is IID_IShellItem. |
| CLSID | This is CLSID_ShellItem. |
| Constructor methods | |
| FromAbsolutePath | Creates and initializes a Shell item object from an absolute path. |
| FromKnownFolder | Creates a Shell item object for a known folder. |
| FromRelativePath | Creates and initializes a Shell item object from a relative parsing name. |
| IShellItem methods | |
| BindToHandler | Binds to a handler for an item as specified by the handler ID value (BHID). |
| GetParent | Gets the parent of an IShellItem object. |
| GetDisplayName | Gets the display name of the IShellItem object. |
| GetAttributes | Gets a requested set of attributes of the IShellItem object. |
| Compare | Compares two IShellItem objects. |
FromAbsolutePath( path, bc : = 0 )
Creates and initializes a Shell item object from an absolute path.
| STR path | the path to the directory or file to create an item for |
| [opt] IBindCtx bc | a raw interface pointer to an IBindCtx instance used to pass parameters as inputs and outputs to the parsing function. These passed parameters are often specific to the data source and are documented by the data source owners. |
| ShellItem item | the created instance |
FromKnownFolder( folder, user : = 0 )
Creates a Shell item object for a known folder.
| GUID folder | the GUID of the known folder |
| [opt] HTOKEN user | An access token used to represent a particular user. This parameter is usually ommited, in which case the function tries to access the current user’s instance of the folder. However, you may need to assign a value to hToken for those folders that can have multiple users but are treated as belonging to a single user. The most commonly used folder of this type is Documents. |
| ShellItem item | the created item |
To call this function on public known folders, the caller must have Administrator privileges.
FromRelativePath( path, parent : = 0, bc : = 0 )
Creates and initializes a Shell item object from a relative parsing name.
| STR path | the relative path to the item |
| [opt] ShellItem parent | the item the path is relative to (either as ShellItem instance or raw interface pointer). If this is empty, the current working directory is used. |
| [opt] IBindCtx bc | a raw interface pointer to an IBindCtx instance that controls the parsing operation. |
| ShellItem item | the created item |
Currently, this only works if a parent item is supplied.
BindToHandler( mode, interface, bc : = 0 )
Binds to a handler for an item as specified by the handler ID value (BHID).
| GUID mode | a GUID that specifies which handler will be created, either as GUID string or as pointer.. See Remarks. |
| IID interface | the IID of the interface to retrieve, either as GUID string or as pointer. |
| [opt] IBindCtx bc | a raw interface pointer to an IBindCtx instance on a bind context object. Used to pass optional parameters to the handler. The contents of the bind context are handler-specific. For example, when binding to BHID_Stream, the STGM flags in the bind context indicate the mode of access desired (read or read/write). |
| UPTR instance | a raw memory pointer to the created instance |
The GUID for bc must be one of the following values defined in Shlguid.h: BHID_SFObject - Restricts usage to BindToObject. BHID_SFUIObject - Restricts usage to GetUIObjectOf. BHID_SFViewObject - Restricts usage to CreateViewObject. BHID_Storage - Attempts to retrieve the storage RIID, but defaults to Shell implementation on failure. BHID_Stream - Restricts usage to IStream. BHID_LinkTargetItem - CLSID_ShellItem is initialized with the target of this item (can only be SFGAO.LINK). See GetAttributesOf for a description of SFGAO.LINK. BHID_StorageEnum - If the item is a folder, gets an IEnumShellItems object with which to enumerate the storage contents. BHID_Transfer - Windows Vista and later: If the item is a folder, gets an ITransferSource or ITransferDestination object. BHID_PropertyStore - Windows Vista and later: Restricts usage to IPropertyStore or IPropertyStoreFactory. BHID_ThumbnailHandler - Windows Vista and later: Restricts usage to IExtractImage or IThumbnailProvider. BHID_EnumItems - Windows Vista and later: If the item is a folder, gets an IEnumShellItems object that enumerates all items in the folder. This includes folders, nonfolders, and hidden items. BHID_DataObject - Windows Vista and later: Gets an IDataObject object for use with an item or an array of items. BHID_AssociationArray - Windows Vista and later: Gets an IQueryAssociations object for use with an item or an array of items. BHID_Filter - Windows Vista and later: Restricts usage to IFilter. BHID_EnumAssocHandlers - Windows 7 and later: Retrieves an IEnumAssocHandlers that enumerates the association handlers for the given item. Returns an enumeration of recommended handlers, similar to calling SHAssocEnumHandlers with ASSOC_FILTER_RECOMMENDED.
In AHK v2, you can currently not pass pointers for the mode and interface parameters. Pass strings instead.
GetAttributes( requested, byRef attr )
Gets a requested set of attributes of the IShellItem object.
| UINT requested | a combination of flags specifying the attributes requested. You may use the fields of the SFGAO class for convenience. |
| byRef UINT attr | receives a combination of SFGAO flags specifying the attributes actually present. |
| BOOL match | true if all requested attributes are present, false otherwise (or if an error occured). |
Compare( compareTo, hint : = 0 )
Compares two IShellItem objects.
| ShellItem compareTo | the IShellItem to compare this instance to, either as raw interface pointer or ShellItem instance |
| [opt] INT hint | a flag indicating how to perform the comparison. You may use the fields of the SICHINT class for convenience. Defaults to SICHINT.DISPLAY. |
| INT result | the result of the comparison. If the two items are the same, this equals zero; if they are different the parameter is nonzero. |
Creates and initializes a Shell item object from an absolute path.
FromAbsolutePath( path, bc : = 0 )
Creates a Shell item object for a known folder.
FromKnownFolder( folder, user : = 0 )
Creates and initializes a Shell item object from a relative parsing name.
FromRelativePath( path, parent : = 0, bc : = 0 )
Binds to a handler for an item as specified by the handler ID value (BHID).
BindToHandler( mode, interface, bc : = 0 )
Gets the parent of an IShellItem object.
GetParent()
Gets the display name of the IShellItem object.
GetDisplayName( flag : = 0 )
Gets a requested set of attributes of the IShellItem object.
GetAttributes( requested, byRef attr )
Compares two IShellItem objects.
Compare( compareTo, hint : = 0 )