{"id":44853,"date":"2015-01-22T07:00:00","date_gmt":"2015-01-22T22:00:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/oldnewthing\/2015\/01\/22\/the-wonderful-world-of-shell-bind-context-strings\/"},"modified":"2019-03-13T12:12:16","modified_gmt":"2019-03-13T19:12:16","slug":"20150122-00","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20150122-00\/?p=44853","title":{"rendered":"The wonderful world of shell bind context strings"},"content":{"rendered":"

Some time ago<\/a>, we saw how the IBindCtx<\/code> parameter to IShell­Folder::Parse­Display­Name<\/code> can be used to modify how the parse takes place. More generally, the IBindCtx<\/code> parameter to a function is a catch-all miscellaneous options<\/i> parameter. <\/p>\n

The interesting part of the bind context is all the stuff that has been added to it via the IBindCtx::Register­Object­Param<\/code> method<\/a>. You can attach arbitrary objects to the bind context, using a string to identify each one. <\/p>\n

Some bind context parameters are like Boolean parameters that simply change some default behavior of the operation. For these operations, the object that is associated with the bind context string is not important; the important thing is that there is something<\/i> associated with it. Traditionally, you just connect a dummy object that implements just IUnknown<\/code>. <\/p>\n

In the most general case, the object associated with a bind context string implements some operation-specific interface. For example, the STR_BIND_DELEGATE_CREATE_OBJECT<\/code> bind context string<\/a> expects you to associate an object that implements the ICreate­Object<\/code> interface, because the whole point of the STR_BIND_DELEGATE_CREATE_OBJECT<\/code> bind context string is to say, “Hey, I want to create objects in a nonstandard way,” so you need to tell it what that nonstandard way is. <\/p>\n

At the other extreme, you may have a chunk of data that you want to associate with the bind context string. Since bind contexts want to associate objects, you need to wrap the data inside a COM object. We saw this earlier when we had to create an object that implemented the IFile­System­Bind­Data<\/code> interface<\/a> in order to babysit a WIN32_FIND_DATA<\/code> structure. <\/p>\n

Rather than having to create a separate interface for each data type (hello, IObject­With­Folder­Enum­Mode<\/code><\/a>), and rather than going to the opposite extreme and just using IStream<\/code> to pass arbitrary unstructured data, the shell folks decided to take a middle-ground approach: Use a common interface that still has a modicum of type safety, namely, IProperty­Bag<\/code>. Other nice things about this approach is that there are a lot of pre-existing helper functions for property bags and property variants. Also, you need to attach only one object instead of a whole bunch of tiny little ones. <\/p>\n

Under this new regime (which took hold in Windows 8), the bind context has an associated property bag, and you put your data in that property bag. <\/p>\n

In pictures: <\/p>\n\n\n\n\n\n\n\n
<\/td>\n <\/td>\nIBindCtx::Register­Object­Param<\/code><\/td>\n<\/td>\nIProperty­Bag::Write<\/code><\/td>\n<\/tr>\n
IBindCtx<\/code><\/td>\n→<\/td>\nBoolean parameter<\/td>\nIUnknown<\/code><\/td>\n<\/tr>\n
<\/td>\n<\/td>\nInterface parameter<\/td>\nobject with custom interface<\/td>\n<\/tr>\n
<\/td>\n<\/td>\nSTR_PROPERTY­BAG_PARAM<\/code><\/td>\nIPropertyBag<\/code><\/td>\n→<\/td>\nProperty bag DWORD<\/code> parameter<\/td>\nVT_UI4<\/code><\/td>\n<\/tr>\n
<\/td>\n<\/td>\n<\/td>\n<\/td>\n<\/td>\nProperty bag string parameter<\/td>\nVT_BSTR<\/code><\/td>\n<\/tr>\n
<\/td>\n<\/td>\n<\/td>\n<\/td>\n<\/td>\nProperty bag Boolean parameter<\/td>\nVT_BOOL<\/code><\/a><\/td>\n<\/tr>\n<\/table>\n

If you want a Boolean-style parameter to be true<\/code>, then set it in the bind context with a dummy object that implements IUnknown<\/code>. If you want a Boolean-style parameter to false<\/code>, then omit it from the bind context entirely. <\/p>\n

To set an interface-style parameter, set it in the bind context with an object that implements the desired interface. <\/p>\n

To set a property bag-based parameter, set it in the property bag with the appropriate variant type. <\/p>\n

Here are the bind context strings defined up through Windows 8.1 and the way you set them into the bind context. <\/p>\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Bind context string<\/th>\nModel<\/th>\nOperation<\/th>\n<\/tr>\n
STR_AVOID_DRIVE_RESTRICTION_POLICY<\/code><\/td>\nBoolean<\/td>\nBinding<\/td>\n<\/tr>\n
STR_BIND_DELEGATE_CREATE_OBJECT<\/code><\/td>\nInterface ICreateObject<\/code><\/td>\nBinding<\/td>\n<\/tr>\n
STR_BIND_FOLDER_ENUM_MODE<\/code><\/td>\nInterface IObjectWith­FolderEnumMode<\/code><\/code> <\/p>\nParsing<\/td>\n<\/tr>\n
STR_BIND_FOLDERS_READ_ONLY<\/code><\/td>\nBoolean<\/td>\nParsing<\/td>\n<\/tr>\n
STR_BIND_FORCE_FOLDER_SHORTCUT_RESOLVE<\/code><\/td>\nBoolean<\/td>\nBinding<\/td>\n<\/tr>\n
STR_DONT_PARSE_RELATIVE<\/code><\/td>\nBoolean<\/td>\nParsing<\/td>\n<\/tr>\n
STR_DONT_RESOLVE_LINK<\/code><\/td>\nBoolean<\/td>\nBinding<\/td>\n<\/tr>\n
STR_ENUM_ITEMS_FLAGS<\/code><\/td>\nProperty bag: VT_UI4<\/code><\/td>\nBinding for enumeration<\/td>\n<\/tr>\n
STR_FILE_SYS_FIND_DATA<\/code><\/td>\nInterface IFileSys­BindData<\/code> or IFileSys­BindData2<\/code><\/td>\nParsing<\/td>\n<\/tr>\n
STR_FILE_SYS_BIND_DATA_WIN7_FORMAT<\/code><\/td>\nBoolean<\/td>\nParsing<\/td>\n<\/tr>\n
STR_GET_ASYNC_HANDLER<\/code><\/td>\nBoolean<\/td>\nGetUIObjectOf<\/td>\n<\/tr>\n
STR_GPS_BEST­EFFORT<\/code><\/td>\nBoolean<\/td>\nBinding for IProperty­Store<\/code><\/td>\n<\/tr>\n
STR_GPS_DELAY­CREATION<\/code><\/td>\nBoolean<\/td>\nBinding for IProperty­Store<\/code><\/td>\n<\/tr>\n
STR_GPS_FAST­PROPERTIES­ONLY<\/code><\/td>\nBoolean<\/td>\nBinding for IProperty­Store<\/code><\/td>\n<\/tr>\n
STR_GPS_HANDLER­PROPERTIES­ONLY<\/code><\/td>\nBoolean<\/td>\nBinding for IProperty­Store<\/code><\/td>\n<\/tr>\n
STR_GPS_NO_OPLOCK<\/code><\/td>\nBoolean<\/td>\nBinding for IProperty­Store<\/code><\/td>\n<\/tr>\n
STR_GPS_OPEN­SLOW­ITEM<\/code><\/td>\nBoolean<\/td>\nBinding for IProperty­Store<\/code><\/td>\n<\/tr>\n
STR_IFILTER_FORCE_TEXT_FILTER_FALLBACK<\/code><\/td>\nBoolean<\/td>\nBinding for IFilter<\/code><\/td>\n<\/tr>\n
STR_IFILTER_LOAD_DEFINED_FILTER<\/code><\/td>\nBoolean<\/td>\nBinding for IFilter<\/code><\/td>\n<\/tr>\n
STR_INTERNAL_NAVIGATE<\/code><\/td>\nBoolean<\/td>\nLoading history<\/td>\n<\/tr>\n
STR_INTERNET­FOLDER_PARSE_ONLY_URLMON_BINDABLE<\/code><\/td>\nBoolean<\/td>\nParsing<\/td>\n<\/tr>\n
STR_ITEM_CACHE_CONTEXT<\/code><\/td>\nInterface IBindCtx<\/code><\/td>\nParsing and initiailzing<\/td>\n<\/tr>\n
STR_NO_VALIDATE_FILE­NAME_CHARS<\/code><\/td>\nBoolean<\/td>\nParsing<\/td>\n<\/tr>\n
STR_PARSE_ALLOW_INTERNET_SHELL_FOLDERS<\/code><\/td>\nBoolean<\/td>\nParsing<\/td>\n<\/tr>\n
STR_PARSE_AND_CREATE_ITEM<\/code><\/td>\nInterface IParse­And­Create­Item<\/code><\/td>\nParsing<\/td>\n<\/tr>\n
STR_PARSE_DONT_REQUIRE_VALIDATED_URLS<\/code><\/td>\nBoolean<\/td>\nParsing<\/td>\n<\/tr>\n
STR_PARSE_EXPLICIT_ASSOCIATION_SUCCESSFUL<\/code><\/td>\nProperty bag: VT_BOOL<\/code><\/td>\nParsing<\/td>\n<\/tr>\n
STR_PARSE_PARTIAL_IDLIST<\/code><\/td>\nInterface IShell­Item<\/code><\/td>\nParsing<\/td>\n<\/tr>\n
STR_PARSE_PREFER_FOLDER_BROWSING<\/code><\/td>\nBoolean<\/td>\nParsing<\/td>\n<\/tr>\n
STR_PARSE_PREFER_WEB_BROWSING<\/code><\/td>\nBoolean<\/td>\nParsing<\/td>\n<\/tr>\n
STR_PARSE_PROPERTY­STORE<\/code><\/td>\nInterface IProperty­Bag<\/code><\/td>\nParsing<\/td>\n<\/tr>\n
STR_PARSE_SHELL_PROTOCOL_TO_FILE_OBJECTS<\/code><\/td>\nBoolean<\/td>\nParsing<\/td>\n<\/tr>\n
STR_PARSE_SHOW_NET_DIAGNOSTICS_UI<\/code><\/td>\nBoolean<\/td>\nParsing<\/td>\n<\/tr>\n
STR_PARSE_SKIP_NET_CACHE<\/code><\/td>\nBoolean<\/td>\nParsing<\/td>\n<\/tr>\n
STR_PARSE_TRANSLATE_ALIASES<\/code><\/td>\nBoolean<\/td>\nParsing<\/td>\n<\/tr>\n
STR_PARSE_WITH_EXPLICIT_ASSOCAPP<\/code><\/td>\nProperty bag: VT_BSTR<\/code><\/td>\nParsing<\/td>\n<\/tr>\n
STR_PARSE_WITH_EXPLICIT_PROGID<\/code><\/td>\nProperty bag: VT_BSTR<\/code><\/td>\nParsing<\/td>\n<\/tr>\n
STR_PARSE_WITH_PROPERTIES<\/code><\/td>\nInterface IProperty­Store<\/code><\/td>\nParsing<\/td>\n<\/tr>\n
STR_PROPERTYBAG_PARAM<\/code><\/td>\nInterface IProperty­Bag<\/code><\/td>\nholds property bag parameters<\/td>\n<\/tr>\n
STR_SKIP_BINDING_CLSID<\/code><\/td>\nInterface IPersist<\/code><\/td>\nParsing and binding<\/td>\n<\/tr>\n<\/table>\n

There are some oddities in the above table. <\/p>\n

    \n
  • All of the STR_GPS_*<\/code> values would be more conveniently expressed as a single VT_UI4<\/code> property bag-based value. (Exercise: Why isn’t it?) \n
  • The STR_ITEM_CACHE_CONTEXT<\/code> bind context parameter is itself another bind context! The idea here is that you, the caller, are enabling caching during the parse, and the inner bind context acts as the cache. \n
  • The STR_PARSE_EXPLICIT_ASSOCIATION_SUCCESSFUL<\/code> value is unusual in that it is something set by the parser and passed back to the caller. \n
  • As we have been discussing, STR_PROPERTY­BAG_PARAM<\/code> is a bind context string that doesn’t mean anything on its own. Rather, it provides a property bag into which more parameters can be stored. <\/ul>\n

    Next time, I’ll write some helper functions to make all this slightly more manageable. <\/p>\n","protected":false},"excerpt":{"rendered":"

    A generic options parameter.<\/p>\n","protected":false},"author":1069,"featured_media":111744,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[25],"class_list":["post-44853","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-code"],"acf":[],"blog_post_summary":"

    A generic options parameter.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/44853","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/users\/1069"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/comments?post=44853"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/44853\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media\/111744"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media?parent=44853"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=44853"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=44853"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}