-
Notifications
You must be signed in to change notification settings - Fork 1.4k
/
prophand-bestprac-faq.yml
143 lines (107 loc) · 13.2 KB
/
prophand-bestprac-faq.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
### YamlMime:FAQ
metadata:
description: This article includes best practices and frequently asked questions about creating and registering property handlers to work with the Windows property system.
ms.assetid: E583A00B-F615-41c8-AECF-061F1396DB9A
title: Property Handler Best Practices and FAQ
ms.topic: faq
ms.date: 05/31/2018
title: Property Handler Best Practices and FAQ
summary: |
This topic explains how to create and register property handlers to work with the Windows property system.
This topic is organized as follows:
- [Best Practices](#best-practices)
- [Overriding File System Properties](#overriding-file-system-properties)
- [Storing Properties in XML-based File Formats](#storing-properties-in-xml-based-file-formats)
- [Computed Properties](#computed-properties)
- [Frequently Asked Questions](#frequently-asked-questions)
- [Related topics](#related-topics)
sections:
- name: Best Practices
questions:
- question: |
Overriding File System Properties
answer: |
Some properties for files are provided by the file system data source, such as:
- PKEY\_FileName
- PKEY\_Extension
- PKEY\_ModifiedTime
In general, property handlers cannot provide values for these properties. However, in some cases these properties can be overridden based on registration information provided by the property handler. Property handlers populate **HKEY\_CLASSES\_ROOT**\\**CLSID**\\*{handler clsid}*\\**OverrideFileSystemProperties** with the names of properties that they want to override. This is limited to a fixed set of properties shown in the following list of which the system has knowledge.
Overriding is supported for the following property values:
- [System.Kind](./props-system-kind.md)
- [System.FileName](./props-system-filename.md)
- [System.IsPinnedToNameSpaceTree](./props-system-ispinnedtonamespacetree.md)
- [System.ItemNameDisplay](./props-system-itemnamedisplay.md)
- [System.SFGAOFlags](./props-system-sfgaoflags.md)
- [System.ItemPathDisplay](./props-system-itempathdisplay.md)
- [System.ItemPathDisplayNarrow](./props-system-itempathdisplaynarrow.md)
- [System.ItemFolderNameDisplay](./props-system-itemfoldernamedisplay.md)
- [System.ItemFolderPathDisplay](./props-system-itemfolderpathdisplay.md)
- [System.ItemFolderPathDisplayNarrow](./props-system-itemfolderpathdisplaynarrow.md)
For a full list of all Shell properties, see [Shell Properties](./props.md).
> [!IMPORTANT]
> The overridden property values are used only when the files are indexed. Thus, browsing files from the file system data source does not reveal the overridden values.
- question: |
Storing Properties in XML-based File Formats
answer: |
There are two basic options available for storing properties in XML-based file formats:
- Store each property using XML elements and attributes according to the XML schema of the document. This approach is more "XML friendly".
- Serialize the entire property store into a memory Binary large object (BLOB), convert the BLOB into a base64-encoded string, and then store that string in the XML. This is the simpler of the two approaches and can be used to trivially provide support for open metadata.
Some handlers might combine these approaches, storing some important values in standard XML format and storing the rest in a BLOB, for example.
- question: |
Computed Properties
answer: |
Some properties are derived from specific attributes of a file. For example, the [System.Image.Dimensions](./props-system-image-dimensions.md) property is determined by the actual dimensions of the image in an image file. Because such property values cannot be changed by the property handler, they are thus marked `isInnate="true"` in the property description. Other properties are computed from a part of a specific property or by aggregating the values of multiple properties. Because updates to these "computed" properties would create ambiguity as to how the "source" values should be changed, computed properties should be marked `isInnate="true"` in the property description or reported as read-only. The latter option is available by instructing the handler to return S\_FALSE from [**IPropertyStoreCapabilities::IsPropertyWritable**](/windows/win32/api/propsys/nf-propsys-ipropertystorecapabilities-ispropertywritable).
- name: Frequently Asked Questions
questions:
- question: |
Why isn't my property handler being loaded by the Windows Search indexer?
answer: |
The Windows Search indexer runs as a system service and cannot load DLLs that are stored in the user profile directory. If you are building and debugging using Microsoft Visual Studio, it will place the DLL in your user profile (and therefore it won't be loaded by the indexer). To work around this, copy your DLL outside of your profile folder (for example, into **C:\\Program Files\\YourAppName**) and register it there.
For more specific guidance on developing property handlers to work with the Windows Search indexer, see [Developing Property Handlers for Windows Search](../search/-search-3x-wds-extidx-propertyhandlers.md).
- question: |
Which properties should be discoverable through the 'IPropertyStore::GetCount' and 'IPropertyStore::GetAt' enumeration methods?
answer: |
Not all clients of property store objects use these methods. Some clients are aware of the properties they plan to request directly (by PKEY name), or receive property information through a property description list. The property discovery methods suppport several other scenarios. If a property does not need to participate in these scenarios, it does not need to be enumerated. Hence, a property handler can produce a non-VT\_EMPTY value for properties that are not discovered through the [**IPropertyStore::GetCount**](/previous-versions/windows/desktop/legacy/bb761472(v=vs.85)) and [**IPropertyStore::GetAt**](/previous-versions/windows/desktop/legacy/bb761471(v=vs.85)) methods.
However, properties should be visible via these methods if any of the following conditions are met:
- **If the property is indexed so that it is searchable:** This means it is included in the Windows Search property store (denoted by `isColumn = "true"` in the property description schema) or available for full text searches (`inInvertedIndex = "true"`). In the absence of these flags or the absence of a property description, properties of type "string" will be added automatically to the inverted index to enable searching. Because the list of known properties (those with installed property descriptions) in the property system is very large (more than 800 properties), it would be impractical to ask every property handler for every property registered in the property system. Instead, the indexing process enumerates the relevant properties from the property handler for each item it indexes, and it uses the values of the enumerated properties to build the full text index.
- **If the property should be copied when the item's property set is duplicated:** To implement a "copy a property set" function, the source item makes the properties that should be copied visible through the [**IPropertyStore::GetCount**](/previous-versions/windows/desktop/legacy/bb761472(v=vs.85)) and [**IPropertyStore::GetAt**](/previous-versions/windows/desktop/legacy/bb761471(v=vs.85)) methods. Properties that do not need to be copied or do not make sense being copied should not be included.
- **If the property value is not empty (VT\_EMPTY):** Property values that are empty are not useful for clients. When clients attempt to return empty property values, a value of VT\_EMPTY is returned. Thus, properties with empty values should not be enumerated.
- **If the property should be removed when invoking the "remove properties" function:** This feature exists to protect privacy; it discovers all values from the property handler through enumeration and removes each one selected for removal by the user.
> [!Note]
> Enumerating properties does not communicate the set of properties that a particular property handler supports if the handler supports a fixed schema (and not open metadata). Instead, such handlers should document the set of properties that they support.
- question: |
How do I know which file formats support open metadata?
answer: |
For information about support for open metadata, see "File Types that Support Open Metadata" in [File Types](../shell/fa-file-types.md).
- question: |
Can VT_NULL values be stored using a property handler?
answer: |
No. VT\_NULL values will be converted to VT\_EMPTY on calls to [**IPropertyStore::GetValue**](/previous-versions/windows/desktop/legacy/bb761473(v=vs.85)) and [**IPropertyStore::SetValue**](/previous-versions/windows/desktop/legacy/bb761475(v=vs.85)).
- question: |
Which date string formats are supported by the 'PropVariantChangeType' function?
answer: |
Generally, properties that represent date/time values should be represented using VT\_FILETIME. However, many data sources provide this information in string form. The [**PropVariantChangeType**](/windows/win32/api/propvarutil/nf-propvarutil-propvariantchangetype) helper API supports coercing some string date formats into [**FILETIME**](/windows/win32/api/minwinbase/ns-minwinbase-filetime) values, as shown in the following table.
| Format | Windows Vista, Windows XP, and Microsoft Windows Desktop Search (WDS) | Windows 7 | Notes |
|-------------------------|-----------------------------------------------------------------------|-----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| yyyy/mm/dd:hh:mm:ss.uuu | Yes | Yes | UTC; y=year, m=month, d=date, h=hours (24-hour clock), m=minutes, s=seconds, u=microseconds |
| yyyy-mm-ddThh:mm:ssZ | No | Yes | **ISO8601 format specification**UTC (denoted by 'Z' time zone indicator); y=year, m=month, d=date, h=hours (24-hour clock), m=minutes, s=seconds; 'T' is a delimiter for the time portion.<br/> |
- question: |
Is it possible to create a read-only property handler?
answer: |
Yes. Some property handler implementations do not support writing of property values. These property handlers should return STGM\_E\_ACCESSDENIED on calls to **IInitializeXXX::Initialize** that pass STGM\_READWRITE, or on any call to [**IPropertyStore::SetValue**](/previous-versions/windows/desktop/legacy/bb761475(v=vs.85)).
All property handlers opened in STGM\_READ mode should return STGM\_E\_ACCESSDENIED on calls to [**IPropertyStore::SetValue**](/previous-versions/windows/desktop/legacy/bb761475(v=vs.85)).
- question: |
Can a property handler treat a property as read-only, even if the schema indicates that the property is writeable?
answer: |
Yes. In the schema system, properties are annotated as read-only (including those with `isInnate = "true"`) or read/write. Property handlers that do not support writing a particular property that the schema says should be writeable should implement [**IPropertyStoreCapabilities**](/windows/win32/api/propsys/nn-propsys-ipropertystorecapabilities) and return S\_FALSE on calls to [**IPropertyStoreCapabilities::IsPropertyWritable**](/windows/win32/api/propsys/nf-propsys-ipropertystorecapabilities-ispropertywritable) for that property. This indicates that in the context of this handler and this file, the property is not writeable.
> [!Note]
> The reverse action is not possible. You cannot enable a property handler to write a property that is marked as read-only in the schema
additionalContent: |
## Related topics
[Understanding Property Handlers](./building-property-handlers-properties.md)
[Using Kind Names](./building-property-handlers-user-friendly-kind-names.md)
[Using Property Lists](./building-property-handlers-property-lists.md)
[Initializing Property Handlers](./building-property-handlers-property-handlers.md)
[Registering and Distributing Property Handlers](./prophand-reg-dist.md)