ShellNotify Component

Properties   Methods   Events   Config Settings   Errors  

The ShellNotify component enables monitoring file system change notifications.

Syntax

callback.CBFSShell.ShellNotify

Remarks

The ShellNotify component provides a simple way to monitor changes such as creation, renaming, deletion, or modification of files or folders. The component uses the Windows API to register as an observer of shell notifications.

Activate

First, set the Path property to the desired location to listen for changes. The target may be a local or remote filesystem, and a path may be specified using the drive letter format or a UNC path. For instance, you can set C:\Path\To\Folder if the target is a mapped drive, or \\servername\sharename if the target is a network share.

After that, you may set the Recursive property depending on whether you would like to include changes for subfolders. You may also set the value of Notifications to control the types of changes to monitor.

ShellNotify component = new ShellNotify(); component.Path = "C:\Temp"; component.Recursive = True;

The next step is to call Activate to begin listening for changes. As users interact with files and folders at the specified Path, the corresponding events will be triggered. Activate must be called again if the Explorer process is terminated.

component.Activate();

Deactivate

To unregister as an observer of changes, call the Deactivate method. This action will cease monitoring change notifications and only needs to be called once.

component.Deactivate();

PIDLs

A PIDL (or an IDL) is a fundamental Windows Shell concept. At a high level, it is pretty simple, as it is just a value that represents a Windows Shell item in the Windows Shell Namespace. It is a bit like a full filesystem path for a physical file or folder, except that it is a binary object and not a string. The name "PIDL" and "IDL" can be used interchangeably. The leading P stands for pointer, the IDL stands for item identifier list, and PIDL generally refers to an IDL itself rather than the pointer to it.

The below information is provided as a general knowledge. Your application will deal with PIDLs only when they denote some Windows Shell items that are not necessarily a part of the Windows Shell namespace extension that you create. Such PIDLs can be used with the Windows Shell API if you decide to call it directly. When CBFS Shell exposes these PIDL values they will appear hex-encoded. If an application needs to call a shell function, it has to decode the PIDL before calling that function.

Just like a full filesystem path is a list of strings separated by the directory separator (on Windows, it is the \ (backslash) character), a PIDL is a list (L is for list) of Ids (identifiers). Unlike a filesystem path, though, a PIDL is binary, and Ids are separated by a special PIDL separator (two consecutive zero bytes).

Microsoft provides more details about PIDLs here Identifying Namespace Objects.

Troubleshooting

Following are some helpful resources for troubleshooting issues.

• If events are not triggered for any changes, note that the component relies on Explorer running and not terminating or restarting. If the Explorer process ends then you will need to call Activate again.
• If certain events are not triggered, it may be that the system components behave differently depending on the target you are monitoring. For instance, to monitor changes to a network share one needs to handle ItemChanged.
• If you are seeing strange behavior not contained in this list, please reach out to us with a description of the problem and we are happy to help. Our support team is available over email at support@callback.com

Property List

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

Method List

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

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.

Config Settings

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

Notifications Property (ShellNotify Component)

The property specifies which changes to monitor.

Syntax

• C#
• VB.NET

public int Notifications { get; set; }

Public Property Notifications As Integer

Default Value

0x0002001F

Remarks

The property specifies which changes the component should monitor. The value may be a combination of the following flags:

The default value of 0x0002001F (CHANGE_NOTIFY_DEFAULT) is a combination of the following flags:

• CHANGE_NOTIFY_CREATE
• CHANGE_NOTIFY_CREATE_FOLDER
• CHANGE_NOTIFY_DELETE
• CHANGE_NOTIFY_DELETE_FOLDER
• CHANGE_NOTIFY_RENAME
• CHANGE_NOTIFY_RENAME_FOLDER

Path Property (ShellNotify Component)

The property specifies what path or namespace item to monitor.

Syntax

• C#
• VB.NET

public string Path { get; set; }

Public Property Path As String

Default Value

""

Remarks

This property specifies the target to monitor. If omitted, all of the Windows Shell namespace is monitored. A target may be any namespace item such as a folder or non-folder item.

An application may set this property to a filesystem path in drive-letter format, a path in UNC format, or a hex-encoded PIDL if a Windows Shell folder or item with no filesystem path is to be monitored. For instance:

• C:\Path\To\Folder
• \\<server>\<share>

Recursive Property (ShellNotify Component)

This property specifies whether changes in subfolders should be monitored.

Syntax

• C#
• VB.NET

public bool Recursive { get; set; }

Public Property Recursive As Boolean

Default Value

True

Remarks

This property specifies whether changes in subfolders of the folder specified by Path property should also be monitored. This setting will be ignored if the Path property references a non-folder item.

Activate Method (ShellNotify Component)

This method initiates monitoring for changes.

Syntax

• C#
• VB.NET

public void Activate();

Public Sub Activate()

Remarks

Use this method to begin monitoring for changes in the target location specified by the Path property. The types of changes that will be included in monitoring are set in the Notifications property.

Activate must be called again if the Explorer process is terminated.

Config Method (ShellNotify Component)

This method sets or retrieves a configuration setting.

Syntax

• C#
• VB.NET

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.

Deactivate Method (ShellNotify Component)

This method stops monitoring changes.

Syntax

• C#
• VB.NET

public void Deactivate();

Public Sub Deactivate()

Remarks

Use this method to stop monitoring for changes and unregister as an observer of change notifications.

Error Event (ShellNotify Component)

This event is fired if an unhandled error occurs during an event.

Syntax

• C#
• VB.NET

public event OnErrorHandler OnError;

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

public class ShellNotifyErrorEventArgs : EventArgs {
  public int ErrorCode { get; }
  public string Description { get; }
}

Public Event OnError As OnErrorHandler

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

Public Class ShellNotifyErrorEventArgs 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.

ErrorCode contains an error code and Description contains a textual description of the error.

FileCreated Event (ShellNotify Component)

This event fires when a file is created.

Syntax

• C#
• VB.NET

public event OnFileCreatedHandler OnFileCreated;

public delegate void OnFileCreatedHandler(object sender, ShellNotifyFileCreatedEventArgs e);

public class ShellNotifyFileCreatedEventArgs : EventArgs {
  public byte[] PIDL { get; }
  public string Path { get; }
}

Public Event OnFileCreated As OnFileCreatedHandler

Public Delegate Sub OnFileCreatedHandler(sender As Object, e As ShellNotifyFileCreatedEventArgs)

Public Class ShellNotifyFileCreatedEventArgs Inherits EventArgs
  Public ReadOnly Property PIDL As Byte()
  Public ReadOnly Property Path As String
End Class

Remarks

This event fires upon creation, when the Windows Shell registers file creation within the namespace.

PIDL contains a byte array that represents an item in the Windows Shell namespace. Please see PIDL for more information.

Path contains the full path of the item. This parameter is only applicable when the item is part of a filesystem with a path.

Note: The events are triggered in the same thread that the Windows Shell used for a notification. Performing time-consuming operations within this event will prevent other events firing in a timely manner and may affect overall performance.

FileDeleted Event (ShellNotify Component)

This event fires when a file is deleted.

Syntax

• C#
• VB.NET

public event OnFileDeletedHandler OnFileDeleted;

public delegate void OnFileDeletedHandler(object sender, ShellNotifyFileDeletedEventArgs e);

public class ShellNotifyFileDeletedEventArgs : EventArgs {
  public byte[] PIDL { get; }
  public string Path { get; }
}

Public Event OnFileDeleted As OnFileDeletedHandler

Public Delegate Sub OnFileDeletedHandler(sender As Object, e As ShellNotifyFileDeletedEventArgs)

Public Class ShellNotifyFileDeletedEventArgs Inherits EventArgs
  Public ReadOnly Property PIDL As Byte()
  Public ReadOnly Property Path As String
End Class

Remarks

This event fires upon deletion, when the Windows Shell has registered file deletion.

PIDL contains a byte array that represents an item in the Windows Shell namespace. Please see PIDL for more information.

Path contains the full path of the item. This parameter is only applicable when the item is part of a filesystem with a path.

Note: The events are triggered in the same thread that the Windows Shell used for a notification. Performing time-consuming operations within this event will prevent other events firing in a timely manner and may affect overall performance.

FileRenamed Event (ShellNotify Component)

This event fires when a file is renamed.

Syntax

• C#
• VB.NET

public event OnFileRenamedHandler OnFileRenamed;

public delegate void OnFileRenamedHandler(object sender, ShellNotifyFileRenamedEventArgs e);

public class ShellNotifyFileRenamedEventArgs : EventArgs {
  public byte[] PIDL { get; }
  public string Path { get; }
  public byte[] NewPIDL { get; }
  public string NewPath { get; }
}

Public Event OnFileRenamed As OnFileRenamedHandler

Public Delegate Sub OnFileRenamedHandler(sender As Object, e As ShellNotifyFileRenamedEventArgs)

Public Class ShellNotifyFileRenamedEventArgs Inherits EventArgs
  Public ReadOnly Property PIDL As Byte()
  Public ReadOnly Property Path As String
  Public ReadOnly Property NewPIDL As Byte()
  Public ReadOnly Property NewPath As String
End Class

Remarks

This event fires upon renaming, when the Windows Shell has registered file renaming in one or more Windows Shell items.

PIDL contains a byte array that represents an previous item in the Windows Shell namespace. Please see PIDL for more information.

Path contains the full previous path of the item. This parameter is only applicable when the item is part of a filesystem with a path.

NewPIDL contains the new PIDL.

NewPath contains the new path. This parameter is only applicable when the item is part of a filesystem with a path.

Note: The events are triggered in the same thread that the Windows Shell used for a notification. Performing time-consuming operations within this event will prevent other events firing in a timely manner and may affect overall performance.

FolderCreated Event (ShellNotify Component)

This event fires when a folder is created.

Syntax

• C#
• VB.NET

public event OnFolderCreatedHandler OnFolderCreated;

public delegate void OnFolderCreatedHandler(object sender, ShellNotifyFolderCreatedEventArgs e);

public class ShellNotifyFolderCreatedEventArgs : EventArgs {
  public byte[] PIDL { get; }
  public string Path { get; }
}

Public Event OnFolderCreated As OnFolderCreatedHandler

Public Delegate Sub OnFolderCreatedHandler(sender As Object, e As ShellNotifyFolderCreatedEventArgs)

Public Class ShellNotifyFolderCreatedEventArgs Inherits EventArgs
  Public ReadOnly Property PIDL As Byte()
  Public ReadOnly Property Path As String
End Class

Remarks

This event fires upon folder creation, when the Windows Shell has registered a folder is created.

PIDL contains a byte array that represents an item in the Windows Shell namespace. Please see PIDL for more information.

Path contains the full path of the item. This parameter is only applicable when the item is part of a filesystem with a path.

Note: The events are triggered in the same thread that the Windows Shell used for a notification. Performing time-consuming operations within this event will prevent other events firing in a timely manner and may affect overall performance.

FolderDeleted Event (ShellNotify Component)

This event fires when a folder is deleted.

Syntax

• C#
• VB.NET

public event OnFolderDeletedHandler OnFolderDeleted;

public delegate void OnFolderDeletedHandler(object sender, ShellNotifyFolderDeletedEventArgs e);

public class ShellNotifyFolderDeletedEventArgs : EventArgs {
  public byte[] PIDL { get; }
  public string Path { get; }
}

Public Event OnFolderDeleted As OnFolderDeletedHandler

Public Delegate Sub OnFolderDeletedHandler(sender As Object, e As ShellNotifyFolderDeletedEventArgs)

Public Class ShellNotifyFolderDeletedEventArgs Inherits EventArgs
  Public ReadOnly Property PIDL As Byte()
  Public ReadOnly Property Path As String
End Class

Remarks

This event fires upon folder deletion, when the Windows Shell has registered a folder has been deleted.

PIDL contains a byte array that represents an item in the Windows Shell namespace. Please see PIDL for more information.

Path contains the full path of the item. This parameter is only applicable when the item is part of a filesystem with a path.

Note: The events are triggered in the same thread that the Windows Shell used for a notification. Performing time-consuming operations within this event will prevent other events firing in a timely manner and may affect overall performance.

FolderRenamed Event (ShellNotify Component)

This event fires when a folder is renamed.

Syntax

• C#
• VB.NET

public event OnFolderRenamedHandler OnFolderRenamed;

public delegate void OnFolderRenamedHandler(object sender, ShellNotifyFolderRenamedEventArgs e);

public class ShellNotifyFolderRenamedEventArgs : EventArgs {
  public byte[] PIDL { get; }
  public string Path { get; }
  public byte[] NewPIDL { get; }
  public string NewPath { get; }
}

Public Event OnFolderRenamed As OnFolderRenamedHandler

Public Delegate Sub OnFolderRenamedHandler(sender As Object, e As ShellNotifyFolderRenamedEventArgs)

Public Class ShellNotifyFolderRenamedEventArgs Inherits EventArgs
  Public ReadOnly Property PIDL As Byte()
  Public ReadOnly Property Path As String
  Public ReadOnly Property NewPIDL As Byte()
  Public ReadOnly Property NewPath As String
End Class

Remarks

This event fires upon folder renaming, when the Windows Shell has registered renaming in one or more Windows Shell items.

PIDL contains a byte array that represents an previous item in the Windows Shell namespace. Please see PIDL for more information.

Path contains the full previous path of the item. This parameter is only applicable when the item is part of a filesystem with a path.

NewPIDL contains a new PIDL.

NewPath contains a new path. This parameter is only applicable when the item is part of a filesystem with a path.

Note: The events are triggered in the same thread that the Windows Shell used for a notification. Performing time-consuming operations within this event will prevent other events firing in a timely manner and may affect overall performance.

ItemChanged Event (ShellNotify Component)

This event fires when any item is changed.

Syntax

• C#
• VB.NET

public event OnItemChangedHandler OnItemChanged;

public delegate void OnItemChangedHandler(object sender, ShellNotifyItemChangedEventArgs e);

public class ShellNotifyItemChangedEventArgs : EventArgs {
  public byte[] PIDL { get; }
  public string Path { get; }
  public byte[] NewPIDL { get; }
  public string NewPath { get; }
  public int Changes { get; }
}

Public Event OnItemChanged As OnItemChangedHandler

Public Delegate Sub OnItemChangedHandler(sender As Object, e As ShellNotifyItemChangedEventArgs)

Public Class ShellNotifyItemChangedEventArgs Inherits EventArgs
  Public ReadOnly Property PIDL As Byte()
  Public ReadOnly Property Path As String
  Public ReadOnly Property NewPIDL As Byte()
  Public ReadOnly Property NewPath As String
  Public ReadOnly Property Changes As Integer
End Class

Remarks

This event fires upon any change, when the Windows Shell has registered a creation, deletion, renaming, or updates in one or more Windows Shell items. The types of updates can include changes to size, attributes, security settings, last write, and last access time.

PIDL contains a byte array that represents an item in the Windows Shell namespace. If the set of changes includes renaming, this parameter contains the previous PIDL. Please see PIDL for more information.

Path contains the full path of the item. This parameter is only applicable when the item is part of a filesystem with a path. If the set of changes includes renaming, this parameter contains the previous Path.

NewPIDL contains a new PIDL. This parameter is only used when the set of changes includes renaming.

NewPath contains a new path. This parameter is only used when the set of changes includes renaming.

Changes specifies the type of change. The value can be one of the following:

Note: The events are triggered in the same thread that the Windows Shell used for a notification. Performing time-consuming operations within this event will prevent other events firing in a timely manner and may affect overall performance.

Config Settings (ShellNotify Component)

Base Config Settings

Trappable Errors (ShellNotify Component)

ShellNotify Errors