CBShellBoost Component

Properties   Methods   Events   Config Settings   Errors  

The CBShellBoost component is a "gateway" to using the core functionality of CBFS Shell. With CBShellBoost, you can install and uninstall the native proxy DLL to or from the system as well as initialize it before using the core classes.

Syntax

callback.CBFSShell.Cbshellboost

Remarks

To serve Shell requests, the components are integrated with the Shell with the help of the proxy DLL, a native dynamic library that is provided for each processor architecture, supported by Windows.

Before the DLL can be used, it should be "installed" - properly registered with the Shell. Installation and uninstallation is done using the corresponding methods of this CBShellBoost component.

When an application uses the CBFS Shell components, it should initialize the native DLL before use. This is done using the Initialize method. Call it once per application session, during the initialization of the application. Do not call Initialize when you install or uninstall the native DLL.

Each distinct kind of a virtual folder (shell namespace extension) requires an own license key and a dedicated copy of the native DLL.

Property List


The following is the full list of the properties of the component with short descriptions. Click on the links for further details.

AttributesThis contains various options of virtual folder behavior.
DisplayNameThis is the name that Windows Shell uses when it displays the Namespace Extension.
IconLocationThis contains the full path to the file with the icon.
NamespaceLocationThis property specifies where the extension is located in the Shell Namespace.
PathToDLLThis property specifies the path to the native proxy DLL.
PerUserInstallationThis property specifies whether the component is registered for the current user or for all users.

Method List


The following is the full list of the methods of the component with short descriptions. Click on the links for further details.

ConfigSets or retrieves a configuration setting.
InitializeThis method initializes the core shell library.
InstallThis method installs the native proxy DLL to the system and registers Shell folder information.
UninstallThis method unregisters Shell folder information and uninstalls the native DLL from the system.

Event List


The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.

ErrorFires if an unhandled error occurs during an event.

Config Settings


The following is a list of config settings for the component with short descriptions. Click on the links for further details.

EnumerationBatchSizeThe RPC protocol enumeration batch size.
IPCErrorTextThe error text that will be displayed alongside the Refresh button when the native proxy DLL in the Shell cannot communicate with the server (and your process).
IPCFormatThe fixed name of the RPC endpoint.
IsInstalledSpecifies whether the installation was performed.
ProductGUIDID of the proxy DLL.
RefreshButtonTextThe text that will be displayed on the Refresh button in the shell folder.
ServerStartArgumentsThe arguments to pass with the command.
ServerStartCommandLineThe command line to run when the server is not available.
ServerStartOperationThe operation verb.
ServerStartShowOptionDefines how the application windows should be shown.
ServerStartTimeToWaitOptional time to wait before retrying RPC connection.
ServerStartWorkingDirectoryThe working directory.

Attributes Property (CBShellBoost Component)

This contains various options of virtual folder behavior.

Syntax

public long Attributes { get; set; }
Public Property Attributes As Long

Default Value

0xa0c00108

Remarks

This property specifies various options, related to the behavior of the virtual folder, created by the Shell Namespace Extension.

Set this property before calling the Install method.

The property should contain zero or more of the following flags, OR'd together:

SFGAO_CANCOPY0x00000001The specified items can be copied.

ShellItem property: CanCopy. Default for items: false. Default for folders: false.

SFGAO_CANMOVE0x00000002The specified items can be moved.

ShellItem property: CanMove. Default for items: false. Default for folders: false.

SFGAO_CANLINK0x00000004Shortcuts can be created for the specified items.

ShellItem property: CanLink. Default for items: true. Default for folders: true.

If a namespace extension returns this attribute, a Create Shortcut entry with a default handler is added to the shortcut menu that is displayed during drag-and-drop operations. The extension can also implement its own handler for the link verb in place of the default. If the extension does so, it is responsible for creating the shortcut. A Create Shortcut item is also added to the Windows Explorer File menu and to normal shortcut menus.

SFGAO_STORAGE0x00000008The specified items can be bound to an IStorage object.

Should not be changed if item content is used. Default for items: true. Default for folders: true.

SFGAO_CANRENAME0x00000010The specified items can be renamed.

ShellItem property: CanRename. Default for items: false. Default for folders: false.

SFGAO_CANDELETE0x00000020The specified items can be deleted.

ShellItem property: CanDelete. Default for items: false. Default for folders: false.

SFGAO_HASPROPSHEET0x00000040The specified items have property sheets.

ShellItem property: HasPropertySheet. Default for items: true. Default for folders: true.

SFGAO_ISDROPTARGET0x00000100The specified items are drop targets.

ShellItem property: IsDropTarget. Default for items: false. Default for folders: false.

SFGAO_PLACEHOLDER0x00000800The specified items are not fully present and recalled on open or access.

SFGAO_SYSTEM0x00001000The specified items are system items.

Default for items: false. Default for folders: false.

SFGAO_ENCRYPTED0x00002000The specified items are encrypted and might require special presentation.

Default for items: false. Default for folders: false.

SFGAO_ISSLOW0x00004000Accessing the item (through IStream or other storage interfaces) is expected to be a slow operation.

Default for items: false. Default for folders: false.

Applications should avoid accessing items flagged with SFGAO_ISSLOW.

SFGAO_GHOSTED0x00008000The specified items are shown as dimmed and unavailable to the user.

Default for items: false. Default for folders: false.

SFGAO_LINK0x00010000The specified items are shortcuts.

Default for items: false. Default for folders: false.

SFGAO_SHARE0x00020000The specified objects are shared.

Default for items: false. Default for folders: false.

SFGAO_READONLY0x00040000The specified items are read-only.

In the case of folders, this means that new items cannot be created in those folders. This should not be confused with the behavior specified by the file Read-Only attribute. Default for items: false. Default for folders: false.

SFGAO_HIDDEN0x00080000The item is hidden and should not be displayed unless the Show hidden files and folders option is enabled in Folder Settings.

ShellItem property: IsHidden. Default for items: false. Default for folders: false.

SFGAO_NONENUMERATED0x00100000The items are non-enumerated items and should be hidden.

Should not be changed. Default for items: false. Default for folders: false.

SFGAO_NEWCONTENT0x00200000The items contain new content, as defined by the particular application.

Default for items: false. Default for folders: false.

SFGAO_STREAM0x00400000Indicates that the item has a stream associated with it.

Should not be changed if item content is used. Default for items: true. Default for folders: true.

SFGAO_STORAGEANCESTOR0x00800000Children of this item are accessible through IStream or IStorage. Those children are flagged with SFGAO_STORAGE or SFGAO_STREAM.

Should not be changed if item content is used. Default for items: false. Default for folders: true.

SFGAO_VALIDATE0x01000000When specified as input, SFGAO_VALIDATE instructs the folder to validate that the items contained in a folder or Shell item array exist.

Should not be changed. Default for items: false. Default for folders: false.

SFGAO_REMOVABLE0x02000000The specified items are on removable media or are themselves removable devices.

Default for items: false. Default for folders: false.

SFGAO_COMPRESSED0x04000000The specified items are compressed.

Default for items: false. Default for folders: false.

SFGAO_BROWSABLE0x08000000The specified items can be hosted inside a web browser or Explorer frame.

Default for items: false. Default for folders: true.

To be used with non-folder items.

SFGAO_FILESYSANCESTOR0x10000000The specified folders are either file system folders or contain at least one descendant (child, grandchild, or later) that is a file system (SFGAO_FILESYSTEM) folder.

Already handled for physical ShellFolders instances. Default for items: false. Default for folders: false.

SFGAO_FOLDER0x20000000The specified items are folders.

Should not be changed. Default for items: false. Default for folders: true.

SFGAO_FILESYSTEM0x40000000The specified folders or files are part of the file system (that is, they are files, directories, or root directories).

The parsed names of the items can be assumed to be valid Win32 file system paths. These paths can be either UNC or drive-letter based.

Already handled for physical ShellFolders and ShellItems instances.

Default for items: true (physical) or false (virtual). Default for folders: true (physical) or false (virtual).

SFGAO_HASSUBFOLDER0x80000000The specified folders have subfolders.

The SFGAO_HASSUBFOLDER attribute is only advisory and might be returned by Shell folder implementations even if they do not contain subfolders. Note, however, that the converse - failing to return SFGAO_HASSUBFOLDER - definitively states that the folder objects do not have subfolders. Returning SFGAO_HASSUBFOLDER is recommended whenever a significant amount of time is required to determine whether any subfolders exist. For example, the Shell always returns SFGAO_HASSUBFOLDER when a folder is located on a network drive.

Already handled, but may be changed if needed (when we are sure that the folder is empty).

Default for items: false. Default for folders: true.

A more detailed description of the attributes can be found in the dedicated MSDN topic.

The most used SFGAO values have an equivalent .NET property in the ShellItem class.

DisplayName Property (CBShellBoost Component)

This is the name that Windows Shell uses when it displays the Namespace Extension.

Syntax

public string DisplayName { get; set; }
Public Property DisplayName As String

Default Value

""

Remarks

This name is displayed by the Shell and should be human-readable, as end users will recognize your Namespace Extension by this name.

IconLocation Property (CBShellBoost Component)

This contains the full path to the file with the icon.

Syntax

public string IconLocation { get; set; }
Public Property IconLocation As String

Default Value

""

Remarks

This property may be set to the full path of the file with the icon that corresponds to the Shell Namespace Extension. If the icon is contained in the EXE or DLL file, the path may be followed by a comma and an integer value, which may be either an ID or index of the icon in the resources within the EXE or DLL file. If the ID is used, it must be prefixed with the "minus" character.

Examples:

<path\to\file.dll>,-<resource ID>

<path\to\file.dll>,<resource index>

Set this property before calling the Install method.

NamespaceLocation Property (CBShellBoost Component)

This property specifies where the extension is located in the Shell Namespace.

Syntax

public string NamespaceLocation { get; set; }
Public Property NamespaceLocation As String

Default Value

""

Remarks

This property describes where the Shell Namespace Extension will be located in the Shell Namespace.

Set this property before calling the Install method.

This location must be one of the following specified values (other values will not be translated properly into folder IDs):

NS_LOCATION_NONENo location.

Used for extensions that implement "file as folder" feature and that may appear anywhere within the Shell namespace.

NS_LOCATION_COMMONPLACESCommonPlacesAdd or Remove Programs Shell folder or Programs and Features (Windows 10 and later).

Corresponds to FOLDERID_ChangeRemovePrograms well-known ID.

NS_LOCATION_CONTROLPANELControlPanelControl Panel folder.

Corresponds to FOLDERID_ControlPanelFolder well-known ID.

NS_LOCATION_DESKTOPDesktopDesktop folder and Desktop itself.

Corresponds to FOLDERID_Desktop well-known ID.

NS_LOCATION_FONTSFontsFolderFonts folder.

Corresponds to FOLDERID_Fonts well-known ID.

NS_LOCATION_MYCOMPUTERMyComputerMy Computer Shell folder.

Corresponds to FOLDERID_ComputerFolder well-known ID.

NS_LOCATION_NETWORK_NEIGHBORHOODNetworkNeighborhoodNetwork Shell folder.

Corresponds to FOLDERID_NetworkFolder well-known ID.

NS_LOCATION_ENTIRE_NETWORKNetworkNeighborhood\EntireNetworkNetwork Shortcuts folder.

Corresponds to FOLDERID_NetHood well-known ID.

NS_LOCATION_PRINTERS_AND_FAXESPrintersAndFaxesPrinters and Faxes folder or Devices and Printers (Windows 10 or later).

Corresponds to FOLDERID_PrintersFolder well-known ID.

NS_LOCATION_USERS_FILESUsersFilesUser's root folder.

Corresponds to FOLDERID_UsersFiles well-known ID.

NS_LOCATION_USERS_LIBRARIESUsersLibrariesLibraries folder.

Corresponds to FOLDERID_UsersLibraries well-known ID.

Additional information about well-known folder IDs can be found in the dedicated MSDN topic.

PathToDLL Property (CBShellBoost Component)

This property specifies the path to the native proxy DLL.

Syntax

public string PathToDLL { get; set; }
Public Property PathToDLL As String

Default Value

""

Remarks

This optional property may be used to specify the full path with the name of the native proxy DLL, which is loaded by the Shell.

If the property left empty, the component automatically will locate the appropriate DLL, searching the directory where the application's executable resides.

PerUserInstallation Property (CBShellBoost Component)

This property specifies whether the component is registered for the current user or for all users.

Syntax

public bool PerUserInstallation { get; set; }
Public Property PerUserInstallation As Boolean

Default Value

True

Remarks

This property specifies specifies whether the information related to the component is written to the registry for the current user or for all users.

In the latter case, administrative rights are required to successfully execute the Install and Uninstall methods. If the user account of the process that calls these methods does not have such rights, the call will fail with an error.

Config Method (CBShellBoost Component)

Sets or retrieves a configuration setting.

Syntax

public string Config(string configurationString);
Public Function Config(ByVal ConfigurationString As String) As String

Remarks

Config is a generic method available in every component. It is used to set and retrieve configuration settings for the component.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

Initialize Method (CBShellBoost Component)

This method initializes the core shell library.

Syntax

public void Initialize();
Public Sub Initialize()

Remarks

This method initializes the core library and must be called each time the application starts before attempting to use ShellBoost Core methods. The two exceptions are Install and Uninstall, which don't require advance initialization.

If the application explicitly specifies the path to the DLL, it should do this through the PathToDLL property before calling this method.

Install Method (CBShellBoost Component)

This method installs the native proxy DLL to the system and registers Shell folder information.

Syntax

public void Install();
Public Sub Install()

Remarks

This method is used to install the native proxy DLL that integrates with Shell to the system.

Before calling this method, you may change the default values of the Attributes, DisplayName, IconLocation, NamespaceLocation, PathToDLL, and PerUserInstallation properties. All of these values are used during installation and are placed in the Windows registry. Configuration settings, if used, also should be set using the Config method before the call to Install.

The PerUserInstallation property specifies whether the information is written to the registry for the current user or for all users.

In the latter case, administrative rights are required to execute this method successfully. If the user account of the process that calls this method does not have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD (0x0522) error.

Uninstall Method (CBShellBoost Component)

This method unregisters Shell folder information and uninstalls the native DLL from the system.

Syntax

public void Uninstall();
Public Sub Uninstall()

Remarks

This method is used to uninstall the native DLL that integrates with Shell from the system.

Before calling this method, you may change the default value of the PerUserInstallation property.

The PerUserInstallation property specifies whether the information is written to the registry for the current user or for all users.

In the latter case, administrative rights are required to execute this method successfully. If the user account of the process that calls this method does not have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD (0x0522) error.

Note: As CBShellBoost and CBMenu share a proxy DLL and a product GUID, they store some common information in a registry key. Calling the Uninstall method of one of the components will delete a shared registry key as well.

Each component should be uninstalled properly by calling the corresponding Uninstall method. At the same time, if your application needs to uninstall just one component and keep the other, it should call the Uninstall method of that component and then call the Install method of the other component to restore the common information in the shared registry key.

Error Event (CBShellBoost Component)

Fires if an unhandled error occurs during an event.

Syntax

public event OnErrorHandler OnError;

public delegate void OnErrorHandler(object sender, CbshellboostErrorEventArgs e);

public class CbshellboostErrorEventArgs : EventArgs {
  public int ErrorCode { get; }
  public string Description { get; }
}
Public Event OnError As OnErrorHandler

Public Delegate Sub OnErrorHandler(sender As Object, e As CbshellboostErrorEventArgs)

Public Class CbshellboostErrorEventArgs Inherits EventArgs
  Public ReadOnly Property ErrorCode As Integer
  Public ReadOnly Property Description As String
End Class

Remarks

This event fires if an unhandled error occurs. Developers can use this information to track down unhandled errors that occur in the component.

Config Settings (CBShellBoost Component)

The component accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

CBShellBoost Config Settings

EnumerationBatchSize:   The RPC protocol enumeration batch size.

This configuration setting specifies the number of items that are transferred in one RPC request during enumeration. If the value is 0 or negative, the automatic default value is used. The default value is 100.

Set this configuration setting before installing the native proxy DLL.

IPCErrorText:   The error text that will be displayed alongside the Refresh button when the native proxy DLL in the Shell cannot communicate with the server (and your process).

IPCFormat:   The fixed name of the RPC endpoint.

If the Shell and the server operate in different desktop sessions, set this configuration before installing the native proxy DLL. See the "RPC endpoint" subchapter of the Interprocess Communications for details.

IsInstalled:   Specifies whether the installation was performed.

This configuration setting returns true if the component finds the required registry entries, put there by a previous call to the Install method; otherwise, false is returned. In the latter case, an application should use the Install method again.

ProductGUID:   ID of the proxy DLL.

A product GUID (also known as project ID) is used to distinguish among various installations performed by different applications. The GUID of the shell virtual folder is derived from this ID.

This setting may also be used to specify the GUID of the product to be uninstalled. To remove previous installations with a different GUID set this setting and then call Uninstall. For instance:

component.Config("ProductGUID={OldGUID}"); component.Uninstall();

RefreshButtonText:   The text that will be displayed on the Refresh button in the shell folder.

This button is displayed when the native proxy DLL in the Shell cannot communicate with the server (and your process).

ServerStartArguments:   The arguments to pass with the command.

Set this configuration setting before installing the native proxy DLL. See the Starting Server topic for details.

ServerStartCommandLine:   The command line to run when the server is not available.

This command is executed using the ShellExecute function of the Shell API.

Set this configuration setting before installing the native proxy DLL. See the Starting Server topic for details.

ServerStartOperation:   The operation verb.

This command is executed using the ShellExecute function of the Shell API. You may pass an optional operation verb to this function.

Set this configuration setting before installing the native proxy DLL. See the Starting Server topic for details.

ServerStartShowOption:   Defines how the application windows should be shown.

This value corresponds to the nShowCmd parameter of the ShellExecute function. The default value is 1 ("show normal").

Set this configuration setting before installing the native proxy DLL. See the Starting Server topic for details.

ServerStartTimeToWait:   Optional time to wait before retrying RPC connection.

Set this configuration setting before installing the native proxy DLL. See the Starting Server topic for details.

ServerStartWorkingDirectory:   The working directory.

This path will create a current directory for the started process.

Set this configuration setting before installing the native proxy DLL. See the Starting Server topic for details.

Trappable Errors (CBShellBoost Component)

The component uses the following error codes. For convenience, all of these codes are also available as constants.

CBShellBoost Errors

20    Cannot load native proxy DLL. (CBFSSHELL_ERR_CANT_LOAD_PROXY)
28    The major version of the proxy DLL doesn't match the major version of the .NET assembly. (CBFSSHELL_ERR_PROXY_VERSION_MISMATCH)
55    Proxy DLL not installed properly. (CBFSSHELL_ERR_NOT_INSTALLED)
56    Installation of the native proxy DLL failed. (CBFSSHELL_ERR_INSTALL_FAILED)
57    Uninstallation of the native proxy DLL failed. (CBFSSHELL_ERR_UNINSTALL_FAILED)
58    Initialization of the native proxy DLL failed. (CBFSSHELL_ERR_INIT_FAILED)
59    The current license and the ID in the native proxy DLL name don't match. (CBFSSHELL_ERR_PROXY_NAME_MISMATCH)
60    Writing to the Windows registry failed. (CBFSSHELL_ERR_CANT_WRITE_TO_REGISTRY)
61    This CBMenu instance has already been started. (CBFSSHELL_ERR_ALREADY_STARTED)
62    A menu item with the same verb is already registered. (CBFSSHELL_ERR_MENU_ITEM_ALREADY_REG)
63    Menu items not registered. (CBFSSHELL_ERR_MENU_ITEM_NOT_REG)