From 2a784fc6170d7abe88a66f5a6c99c0c5022defcd Mon Sep 17 00:00:00 2001 From: David Hall Date: Thu, 23 Aug 2018 15:00:02 -0600 Subject: [PATCH] Updated documentation --- PInvoke/Ole/PropSys/PropSys.Interfaces.cs | 118 ++ PInvoke/Ole/PropSys/PropSys.cs | 2177 +++++++++++++++++++++++++++-- 2 files changed, 2156 insertions(+), 139 deletions(-) diff --git a/PInvoke/Ole/PropSys/PropSys.Interfaces.cs b/PInvoke/Ole/PropSys/PropSys.Interfaces.cs index 8709278f..2f77c739 100644 --- a/PInvoke/Ole/PropSys/PropSys.Interfaces.cs +++ b/PInvoke/Ole/PropSys/PropSys.Interfaces.cs @@ -641,6 +641,124 @@ namespace Vanara.PInvoke [return: MarshalAs(UnmanagedType.Interface)] IPropertyDescription GetPropertyDescriptionByName([In, MarshalAs(UnmanagedType.LPWStr)] string pszCanonicalName, [In, MarshalAs(UnmanagedType.LPStruct)] Guid riid); + /// + /// + /// Gets an instance of the subsystem object that implements IPropertyDescriptionList, to obtain an ordered collection of + /// property descriptions, based on the provided string. + /// + /// + /// + /// Type: LPCWSTR + /// A pointer to a string that identifies the property list. + /// + /// + /// Type: REFIID + /// A reference to the desired IID. + /// + /// + /// The address of an IPropertyDescriptionList interface pointer. + /// + /// + /// + /// The property description list string ("proplist") syntax consists of a sequence of canonical property names, with flags + /// associated with each property name. The string starts with "prop:". The syntax looks like this: + /// + /// The flags are optional and can be any of those below. Note: These flags translate to the PROPDESC_VIEW_FLAGS enum. + /// + /// + /// Flag + /// Meaning + /// + /// + /// - + /// Sort in reverse order (PDVF_REVERSESORT). + /// + /// + /// 0 + /// Show by default in both the primary and secondary lists (PDVF_SHOWBYDEFAULT | PDVF_SHOWINPRIMARYLIST | PDVF_SHOWINSECONDARYLIST). + /// + /// + /// 1 + /// Show in the primary and secondary lists (PDVF_SHOWINPRIMARYLIST | PDVF_SHOWINSECONDARYLIST). + /// + /// + /// 2 + /// Show in secondary list (PDVF_SHOWINSECONDARYLIST). + /// + /// + /// ^ + /// Begin a new group (PDVF_BEGINNEWGROUP). + /// + /// + /// / + /// Right align (PDVF_RIGHTALIGN). + /// + /// + /// * + /// Hide if the value is not present. + /// + /// + /// | + /// Center align. (PDVF_CENTERALIGN). + /// + /// + /// ~ + /// Hide the label. (PDVF_HIDELABEL). + /// + /// + /// # + /// Fill area. (PDVF_FILLAREA). + /// + /// + /// ? + /// Hide if unsupported by property handler (PDVF_HIDEIFUNSUPPORTED). + /// + /// + /// < + /// Parse as link (PDVF_PARSEASLINK). + /// + /// + /// & + /// Show as whole link (PDVF_SHOWASWHOLELINK). + /// + /// + /// From the dbfolder and file folder perspective: + /// + /// + /// 0 + /// Show as a column in defview, column chooser menu, and column chooser dialog. + /// + /// + /// 1 + /// Show in the column chooser menu and dialog. + /// + /// + /// 2 + /// Show in the column chooser dialog. + /// + /// + /// NULL + /// Include in the search results, but hide in the UI. + /// + /// + /// The endflags are also optional and can be the following: + /// + /// + /// EndFlag + /// Meaning + /// + /// + /// ] + /// End column (used for extended tiles view). + /// + /// + /// + /// It is recommended that you use the IID_PPV_ARGS macro, defined in objbase.h, to package the riid and ppv parameters. This + /// macro provides the correct IID based on the interface pointed to by the value in ppv, eliminating the possibility of a coding error. + /// + /// For more information about property schemas, see Property Schemas. + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-ipropertysystem-getpropertydescriptionlistfromstring [return: MarshalAs(UnmanagedType.Interface)] IPropertyDescriptionList GetPropertyDescriptionListFromString([In, MarshalAs(UnmanagedType.LPWStr)] string pszPropList, [In, MarshalAs(UnmanagedType.LPStruct)] Guid riid); diff --git a/PInvoke/Ole/PropSys/PropSys.cs b/PInvoke/Ole/PropSys/PropSys.cs index b8e7b0e3..3dd8611b 100644 --- a/PInvoke/Ole/PropSys/PropSys.cs +++ b/PInvoke/Ole/PropSys/PropSys.cs @@ -29,10 +29,11 @@ namespace Vanara.PInvoke public enum GETPROPERTYSTOREFLAGS { /// - /// Meaning to a calling process: Succeed at getting the store, even if some properties are not returned. Note: Some values may be different, or - /// missing, compared to a store without this flag. + /// Meaning to a calling process: Succeed at getting the store, even if some properties are not returned. Note: Some values may + /// be different, or missing, compared to a store without this flag. /// - /// Meaning to a file folder: Succeed and return a store, even if the handler or innate store has an error during creation. Only fail if substores fail. + /// Meaning to a file folder: Succeed and return a store, even if the handler or innate store has an error during creation. Only + /// fail if substores fail. /// /// Meaning to other folders: Succeed on getting the store, even if some properties are not returned. /// Combination with other flags: Cannot be combined with GPS_TEMPORARY, GPS_READWRITE, or GPS_HANDLERPROPERTIESONLY. @@ -40,44 +41,50 @@ namespace Vanara.PInvoke GPS_BESTEFFORT = 0x40, /// - /// Meaning to a calling process: Return a read-only property store that contains all properties. Slow items (offline files) are not opened. + /// Meaning to a calling process: Return a read-only property store that contains all properties. Slow items (offline files) are + /// not opened. /// Combination with other flags: Can be overridden by other flags. /// GPS_DEFAULT = 0, /// - /// Meaning to a calling process: Delay memory-intensive operations, such as file access, until a property is requested that requires such access. + /// Meaning to a calling process: Delay memory-intensive operations, such as file access, until a property is requested that + /// requires such access. /// - /// Meaning to a file folder: Do not create the handler until needed; for example, either GetCount/GetAt or GetValue, where the innate store does not - /// satisfy the request. Note: GetValue might fail due to file access problems. + /// Meaning to a file folder: Do not create the handler until needed; for example, either GetCount/GetAt or GetValue, where the + /// innate store does not satisfy the request. Note: GetValue might fail due to file access problems. /// /// - /// Meaning to other folders: If the folder has memory-intensive properties, such as delegating to a file folder or network access, it can optimize - /// performance by supporting IDelayedPropertyStoreFactory and splitting up its properties into a fast and a slow store. It can then use delayed MUX - /// to recombine them. + /// Meaning to other folders: If the folder has memory-intensive properties, such as delegating to a file folder or network + /// access, it can optimize performance by supporting IDelayedPropertyStoreFactory and splitting up its properties into a fast + /// and a slow store. It can then use delayed MUX to recombine them. /// /// Combination with other flags: Cannot be combined with GPS_TEMPORARY or GPS_READWRITE. /// GPS_DELAYCREATION = 0x20, /// - /// Meaning to a calling process: Provides a store that does not involve reading from the disk or network. Note: Some values may be different, or - /// missing, compared to a store without this flag. + /// Meaning to a calling process: Provides a store that does not involve reading from the disk or network. Note: Some values may + /// be different, or missing, compared to a store without this flag. /// Meaning to a file folder: Include the "innate" and "fallback" stores only. Do not load the handler. /// - /// Meaning to other folders: Include only properties that are available in memory or can be computed very quickly (no properties from disk, network, - /// or peripheral IO devices). This is normally only data sources from the IDLIST. When delegating to other folders, pass this flag on to them. + /// Meaning to other folders: Include only properties that are available in memory or can be computed very quickly (no properties + /// from disk, network, or peripheral IO devices). This is normally only data sources from the IDLIST. When delegating to other + /// folders, pass this flag on to them. + /// + /// + /// Combination with other flags: Cannot be combined with GPS_TEMPORARY, GPS_READWRITE, GPS_HANDLERPROPERTIESONLY, or GPS_DELAYCREATION. /// - /// Combination with other flags: Cannot be combined with GPS_TEMPORARY, GPS_READWRITE, GPS_HANDLERPROPERTIESONLY, or GPS_DELAYCREATION. /// GPS_FASTPROPERTIESONLY = 8, /// - /// Meaning to a calling process: Include only properties directly from the property handler, which opens the file on the disk, network, or device. + /// Meaning to a calling process: Include only properties directly from the property handler, which opens the file on the disk, + /// network, or device. /// Meaning to a file folder: Only include properties directly from the handler. /// - /// Meaning to other folders: When delegating to a file folder, pass this flag on to the file folder; do not do any multiplexing (MUX). When not - /// delegating to a file folder, ignore this flag instead of returning a failure code. + /// Meaning to other folders: When delegating to a file folder, pass this flag on to the file folder; do not do any multiplexing + /// (MUX). When not delegating to a file folder, ignore this flag instead of returning a failure code. /// /// Combination with other flags: Cannot be combined with GPS_TEMPORARY, GPS_FASTPROPERTIESONLY, or GPS_BESTEFFORT. /// @@ -87,9 +94,9 @@ namespace Vanara.PInvoke GPS_MASK_VALID = 0x1fff, /// - /// Windows 7 and later. Callers should use this flag only if they are already holding an opportunistic lock (oplock) on the file because without an - /// oplock, the bind operation cannot continue. By default, the Shell requests an oplock on a file before binding to the property handler. This flag - /// disables the default behavior. + /// Windows 7 and later. Callers should use this flag only if they are already holding an opportunistic lock (oplock) on the file + /// because without an oplock, the bind operation cannot continue. By default, the Shell requests an oplock on a file before + /// binding to the property handler. This flag disables the default behavior. /// Windows Server 2008 and Windows Vista: This flag is not available. /// GPS_NO_OPLOCK = 0x80, @@ -97,7 +104,8 @@ namespace Vanara.PInvoke /// /// Meaning to a calling process: Open a slow item (offline file) if necessary. /// - /// Meaning to a file folder: Retrieve a file from offline storage, if necessary. Note: Without this flag, the handler is not created for offline files. + /// Meaning to a file folder: Retrieve a file from offline storage, if necessary. Note: Without this flag, the handler is not + /// created for offline files. /// /// Meaning to other folders: Do not return any properties that are very slow. /// Combination with other flags: Cannot be combined with GPS_TEMPORARY or GPS_FASTPROPERTIESONLY. @@ -108,17 +116,19 @@ namespace Vanara.PInvoke /// Meaning to a calling process: Can write properties to the item. Note: The store may contain fewer properties than a read-only store. /// Meaning to a file folder: ReadWrite. /// - /// Meaning to other folders: ReadWrite. Note: When using default MUX, return a single unmultiplexed store because the default MUX does not support ReadWrite. + /// Meaning to other folders: ReadWrite. Note: When using default MUX, return a single unmultiplexed store because the default + /// MUX does not support ReadWrite. /// /// - /// Combination with other flags: Cannot be combined with GPS_TEMPORARY, GPS_FASTPROPERTIESONLY, GPS_BESTEFFORT, or GPS_DELAYCREATION. Implies GPS_HANDLERPROPERTIESONLY. + /// Combination with other flags: Cannot be combined with GPS_TEMPORARY, GPS_FASTPROPERTIESONLY, GPS_BESTEFFORT, or + /// GPS_DELAYCREATION. Implies GPS_HANDLERPROPERTIESONLY. /// /// GPS_READWRITE = 2, /// - /// Meaning to a calling process: Provides a writable store, with no initial properties, that exists for the lifetime of the Shell item instance; - /// basically, a property bag attached to the item instance. + /// Meaning to a calling process: Provides a writable store, with no initial properties, that exists for the lifetime of the + /// Shell item instance; basically, a property bag attached to the item instance. /// Meaning to a file folder: Not applicable. Handled by the Shell item. /// Meaning to other folders: Not applicable. Handled by the Shell item. /// Combination with other flags: Cannot be combined with any other flag. Implies GPS_READWRITE. @@ -133,7 +143,7 @@ namespace Vanara.PInvoke /// Include only properties from the file's secondary stream. GPS_EXTRINSICPROPERTIESONLY = 0x400, - + /// GPS_VOLATILEPROPERTIES = 0x800, @@ -142,38 +152,102 @@ namespace Vanara.PInvoke } /// - /// Retrieves the property's canonical name given its PROPERTYKEY. + /// Converts the value of a property to the canonical value, according to the property description. /// - /// A pointer to a PROPERTYKEY structure containing the property's identifiers. - /// The address of a pointer to a buffer that receives the property name as a null-terminated Unicode string. - /// The result of the operation. S_OK indicates success. - [DllImport(Lib.PropSys, ExactSpelling = true)] - [PInvokeData("Propsys.h", MSDNShortId = "bb776502")] - public static extern HRESULT PSGetNameFromPropertyKey([In, MarshalAs(UnmanagedType.LPStruct)] PROPERTYKEY propkey, [MarshalAs(UnmanagedType.CustomMarshaler, MarshalTypeRef = typeof(CoTaskMemStringMarshaler))] out string ppszCanonicalName); - - /// Gets an instance of a property description interface for a property specified by a PROPERTYKEY structure. - /// Reference to a PROPERTYKEY. - /// Reference to the interface ID of the requested interface. - /// - /// When this function returns, contains the interface pointer requested in riid. This is typically IPropertyDescription, IPropertyDescriptionAliasInfo, - /// or IPropertyDescriptionSearchInfo. + /// + /// Type: REFPROPERTYKEY + /// Reference to a PROPERTYKEY structure that identifies the property whose value is to be coerced. /// - /// The result of the operation. S_OK indicates success. - [DllImport(Lib.PropSys, ExactSpelling = true)] - [PInvokeData("Propsys.h", MSDNShortId = "bb776503")] - public static extern HRESULT PSGetPropertyDescription([In, MarshalAs(UnmanagedType.LPStruct)] PROPERTYKEY propkey, [MarshalAs(UnmanagedType.LPStruct)] Guid riid, [MarshalAs(UnmanagedType.Interface)] out object ppv); - - /// Gets the property key for a canonical property name. - /// Pointer to a property name as a null-terminated, Unicode string. - /// When this function returns, contains the requested property key. - /// The result of the operation. S_OK indicates success. - [DllImport(Lib.PropSys, ExactSpelling = true)] - [PInvokeData("Propsys.h", MSDNShortId = "bb762081")] - public static extern HRESULT PSGetPropertyKeyFromName([MarshalAs(UnmanagedType.LPWStr)] string pszName, out PROPERTYKEY ppropkey); - - /// Converts the value of a property to the canonical value, according to the property description.Type: REFPROPERTYKEYReference to a PROPERTYKEY structure that identifies the property whose value is to be coerced.Type: PROPVARIANT*On entry, contains a pointer to a PROPVARIANT structure that contains the original value. When this function returns successfully, contains the canonical value.Type: HRESULTPossible return values include the following:Return codeDescription S_OK The function succeeded. The property value specified by ppropvar is now in a canonical form. INPLACE_S_TRUNCATED The property value specified by ppropvar is now in a truncated, canonical form. E_INVALIDARG The ppropvar parameter is invalid. The PROPVARIANT structure has been cleared. TYPE_E_TYPEMISMATCH Coercion from the value's type to the property description's type was not possible. The PROPVARIANT structure has been cleared. Any other failure code Coercion from the value's type to the property description's type was not possible. The PROPVARIANT structure has been cleared. This function is a wrapper around the system's implementation of IPropertyDescription::CoerceToCanonicalValue.Most property descriptions specify the type that their values are expected to use. For example, the property description for System.Title specifies that System.Title values should be of type VT_LPWSTR. This function coerces values to this type, and then coerces the result into a canonical form.It is important to note that if this function fails, it will have already called PropVariantClear on the input PROPVARIANT structure. Only if this function succeeds is the calling application responsible for calling PropVariantClear on ppropvar when the structure is no longer needed.The coercion performed by this function is also performed by the property system during calls to IPropertyStore::GetValue and IPropertyStore::SetValue. Applications can either depend on the property system to perform the coercions or can use this function to perform the coercion at a time of the application's choosing.The coercion is performed in four steps, as follows:The following values are converted to VT_EMPTY. If the value is not of type VT_EMPTY after Step 1, it is converted to the type specified by the property description. The type of a property description can be obtained by calling IPropertyDescription::GetPropertyType. For information on how the property schema influences the type of a property description, see typeInfo. Conversions are performed as follows: After Steps 2 and 3, the value is coerced into a canonical form based on its type. The canonical forms are summarized in the following table. If applicable, the value is checked against the property description type enumeration. The checks in the following table apply. ExamplesThe following example, to be included as part of a larger program, demonstrates how to use PSCoerceToCanonicalValue to coerce a value to the type required for PKEY_Keywords. - // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-pscoercetocanonicalvalue - // PSSTDAPI PSCoerceToCanonicalValue( REFPROPERTYKEY key, PROPVARIANT *ppropvar ); + /// + /// Type: PROPVARIANT* + /// + /// On entry, contains a pointer to a PROPVARIANT structure that contains the original value. When this function returns + /// successfully, contains the canonical value. + /// + /// + /// + /// Type: HRESULT + /// Possible return values include the following: + /// + /// + /// Return code + /// Description + /// + /// + /// S_OK + /// The function succeeded. The property value specified by ppropvar is now in a canonical form. + /// + /// + /// INPLACE_S_TRUNCATED + /// The property value specified by ppropvar is now in a truncated, canonical form. + /// + /// + /// E_INVALIDARG + /// The ppropvar parameter is invalid. The PROPVARIANT structure has been cleared. + /// + /// + /// TYPE_E_TYPEMISMATCH + /// + /// Coercion from the value's type to the property description's type was not possible. The PROPVARIANT structure has been cleared. + /// + /// + /// + /// Any other failure code + /// + /// Coercion from the value's type to the property description's type was not possible. The PROPVARIANT structure has been cleared. + /// + /// + /// + /// + /// + /// This function is a wrapper around the system's implementation of IPropertyDescription::CoerceToCanonicalValue. + /// + /// Most property descriptions specify the type that their values are expected to use. For example, the property description for + /// System.Title specifies that System.Title values should be of type VT_LPWSTR. This function coerces values to this type, and then + /// coerces the result into a canonical form. + /// + /// + /// It is important to note that if this function fails, it will have already called PropVariantClear on the input PROPVARIANT + /// structure. Only if this function succeeds is the calling application responsible for calling PropVariantClear on ppropvar + /// when the structure is no longer needed. + /// + /// + /// The coercion performed by this function is also performed by the property system during calls to IPropertyStore::GetValue and + /// IPropertyStore::SetValue. Applications can either depend on the property system to perform the coercions or can use this function + /// to perform the coercion at a time of the application's choosing. + /// + /// The coercion is performed in four steps, as follows: + /// + /// + /// The following values are converted to VT_EMPTY. + /// + /// + /// + /// If the value is not of type VT_EMPTY after Step 1, it is converted to the type specified by the property description. The type of + /// a property description can be obtained by calling IPropertyDescription::GetPropertyType. For information on how the property + /// schema influences the type of a property description, see typeInfo. Conversions are performed as follows: + /// + /// + /// + /// + /// After Steps 2 and 3, the value is coerced into a canonical form based on its type. The canonical forms are summarized in the + /// following table. + /// + /// + /// + /// + /// If applicable, the value is checked against the property description type enumeration. The checks in the following table apply. + /// + /// + /// + /// Examples + /// + /// The following example, to be included as part of a larger program, demonstrates how to use PSCoerceToCanonicalValue to coerce a + /// value to the type required for PKEY_Keywords. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-pscoercetocanonicalvalue PSSTDAPI + // PSCoerceToCanonicalValue( REFPROPERTYKEY key, PROPVARIANT *ppropvar ); [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] [PInvokeData("propsys.h", MSDNShortId = "8225dd01-47cc-451e-b6a6-c16ddf62ca20")] public static extern HRESULT PSCoerceToCanonicalValue([In, MarshalAs(UnmanagedType.LPStruct)] PROPERTYKEY key, PROPVARIANT ppropvar); @@ -218,61 +292,563 @@ namespace Vanara.PInvoke /// use an adapter property store to convert an IPropertyStore interface into an IPropertySetStorage interface. /// /// - // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-pscreateadapterfrompropertystore - // PSSTDAPI PSCreateAdapterFromPropertyStore( IPropertyStore *pps, REFIID riid, void **ppv ); + // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-pscreateadapterfrompropertystore PSSTDAPI + // PSCreateAdapterFromPropertyStore( IPropertyStore *pps, REFIID riid, void **ppv ); [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] [PInvokeData("propsys.h", MSDNShortId = "a3489f95-e790-481a-af6e-f30527dc476c")] public static extern HRESULT PSCreateAdapterFromPropertyStore(IPropertyStore pps, [In, MarshalAs(UnmanagedType.LPStruct)] Guid riid, [MarshalAs(UnmanagedType.Interface)] out object ppv); - /// Creates a read-only, delayed-binding property store that contains multiple property stores.Type: GETPROPERTYSTOREFLAGSOne or more GETPROPERTYSTOREFLAGS values. These values specify details of the created property store object.Type: IDelayedPropertyStoreFactory*Interface pointer to an instance of IDelayedPropertyStoreFactory.Type: const DWORD*Pointer to an array of property store IDs. This array does not need to be initialized.Type: DWORDThe number of elements in the array pointed to by rgStoreIds.Type: REFIIDReference to the requested IID of the interface that will represent the created property store.Type: void**When this function returns, contains the interface pointer requested in riid. This is typically IPropertyStore.Type: HRESULTIf this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.This function creates a Component Object Model (COM) object that implements IPropertyStore, INamedPropertyStore, IObjectProvider, and IPropertyStoreCapabilities.Applications must call this object from only one thread at a time.You must initialize COM with CoInitialize or OleInitialize before you call PSCreateDelayedMultiplexPropertyStore. COM must remain initialized for the lifetime of this object.PSCreateDelayedMultiplexPropertyStore is designed as an alternative to PSCreateMultiplexPropertyStore, which requires that the array of property stores be initialized before it creates the multiplex property store.The delayed binding mechanism is designed as a performance enhancement for calls to IPropertyStore::GetValue on a multiplex property store. When asked for the value of a property, the delayed multiplex property store checks each of the property stores for the value. After the value is found, there is no need to create and initialize subsequent stores. The delayed multiplex property store stops searching for a value when one of the property stores returns a success code and a non-VT_EMPTY value.When the delayed multiplex property store needs to access a particular property store, it first checks to see if it has already obtained an interface to that property store. If not, it calls IDelayedPropertyStoreFactory::GetDelayedPropertyStore with the appropriate property store ID to obtain the property store. It always uses the property store IDs in the order in which they are provided by the application. It is possible that not all IDs will be used.If the call to IDelayedPropertyStoreFactory fails with E_NOTIMPL or E_ACCESSDENIED for a particular property store ID, or if the application specified GPS_BESTEFFORT, then the failure is ignored and the delayed multiplex property store moves on to the next property store.In some cases, it might be beneficial to use PSCreateDelayedMultiplexPropertyStore in place of PSCreateMultiplexPropertyStore. For example, if an application needs to multiplex two property stores and the first property store is not memory-intensive to initialize and provides PKEY_Size information. Often, calling applications ask for a multiplex property store and then ask for only PKEY_Size before they release the object. In such a case, the application could avoid the cost of initializing the second property store by calling PSCreateDelayedMultiplexPropertyStore and implementing IDelayedPropertyStoreFactory.ExamplesThe following example, to be included as part of a larger program, demonstrates how to use PSCreateDelayedMultiplexPropertyStore in an implementation of IPropertyStoreFactory::GetPropertyStore. - // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-pscreatedelayedmultiplexpropertystore - // PSSTDAPI PSCreateDelayedMultiplexPropertyStore( GETPROPERTYSTOREFLAGS flags, IDelayedPropertyStoreFactory *pdpsf, const DWORD *rgStoreIds, DWORD cStores, REFIID riid, void **ppv ); + /// + /// Creates a read-only, delayed-binding property store that contains multiple property stores. + /// + /// + /// Type: GETPROPERTYSTOREFLAGS + /// One or more GETPROPERTYSTOREFLAGS values. These values specify details of the created property store object. + /// + /// + /// Type: IDelayedPropertyStoreFactory* + /// Interface pointer to an instance of IDelayedPropertyStoreFactory. + /// + /// + /// Type: const DWORD* + /// Pointer to an array of property store IDs. This array does not need to be initialized. + /// + /// + /// Type: DWORD + /// The number of elements in the array pointed to by rgStoreIds. + /// + /// + /// Type: REFIID + /// Reference to the requested IID of the interface that will represent the created property store. + /// + /// + /// Type: void** + /// When this function returns, contains the interface pointer requested in riid. This is typically IPropertyStore. + /// + /// + /// Type: HRESULT + /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. + /// + /// + /// + /// This function creates a Component Object Model (COM) object that implements IPropertyStore, INamedPropertyStore, IObjectProvider, + /// and IPropertyStoreCapabilities. + /// + /// Applications must call this object from only one thread at a time. + /// + /// You must initialize COM with CoInitialize or OleInitialize before you call PSCreateDelayedMultiplexPropertyStore. COM must remain + /// initialized for the lifetime of this object. + /// + /// + /// PSCreateDelayedMultiplexPropertyStore is designed as an alternative to PSCreateMultiplexPropertyStore, which requires that the + /// array of property stores be initialized before it creates the multiplex property store. + /// + /// + /// The delayed binding mechanism is designed as a performance enhancement for calls to IPropertyStore::GetValue on a multiplex + /// property store. When asked for the value of a property, the delayed multiplex property store checks each of the property stores + /// for the value. After the value is found, there is no need to create and initialize subsequent stores. The delayed multiplex + /// property store stops searching for a value when one of the property stores returns a success code and a non-VT_EMPTY value. + /// + /// + /// When the delayed multiplex property store needs to access a particular property store, it first checks to see if it has already + /// obtained an interface to that property store. If not, it calls IDelayedPropertyStoreFactory::GetDelayedPropertyStore with the + /// appropriate property store ID to obtain the property store. It always uses the property store IDs in the order in which they are + /// provided by the application. It is possible that not all IDs will be used. + /// + /// + /// If the call to IDelayedPropertyStoreFactory fails with E_NOTIMPL or E_ACCESSDENIED for a particular property store ID, or if the + /// application specified GPS_BESTEFFORT, then the failure is ignored and the delayed multiplex property store moves on to the next + /// property store. + /// + /// + /// In some cases, it might be beneficial to use PSCreateDelayedMultiplexPropertyStore in place of PSCreateMultiplexPropertyStore. + /// For example, if an application needs to multiplex two property stores and the first property store is not memory-intensive to + /// initialize and provides PKEY_Size information. Often, calling applications ask for a multiplex property store and then ask for + /// only PKEY_Size before they release the object. In such a case, the application could avoid the cost of initializing the second + /// property store by calling PSCreateDelayedMultiplexPropertyStore and implementing IDelayedPropertyStoreFactory. + /// + /// Examples + /// + /// The following example, to be included as part of a larger program, demonstrates how to use PSCreateDelayedMultiplexPropertyStore + /// in an implementation of IPropertyStoreFactory::GetPropertyStore. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-pscreatedelayedmultiplexpropertystore PSSTDAPI + // PSCreateDelayedMultiplexPropertyStore( GETPROPERTYSTOREFLAGS flags, IDelayedPropertyStoreFactory *pdpsf, const DWORD *rgStoreIds, + // DWORD cStores, REFIID riid, void **ppv ); [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] [PInvokeData("propsys.h", MSDNShortId = "8b264d7e-6124-4724-8d23-605101705893")] public static extern HRESULT PSCreateDelayedMultiplexPropertyStore(GETPROPERTYSTOREFLAGS flags, IDelayedPropertyStoreFactory pdpsf, [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 3)] uint[] rgStoreIds, uint cStores, [In, MarshalAs(UnmanagedType.LPStruct)] Guid riid, - [MarshalAs(UnmanagedType.Interface)] out object ppv); + out IPropertyStore ppv); - /// Creates an in-memory property store.Type: REFIIDReference to the requested interface ID.Type: void**When this function returns, contains a pointer to the desired interface, typically IPropertyStore or IPersistSerializedPropStorage.Type: HRESULTIf this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.This function creates an in-memory property store object that implements IPropertyStore, INamedPropertyStore, IPropertyStoreCache, IPersistStream, IPropertyBag, and IPersistSerializedPropStorage.The memory property store does not correspond to a file and is designed for use as a cache. IPropertyStore::Commit is a no-op, and the data stored in the object persists only as long as the object does.The memory property store is thread safe. It aggregates the free-threaded marshaller and uses critical sections to protect its data members.ExamplesThe following example, to be included as part of a larger program, demonstrates how to use PSCreateMemoryPropertyStore. - // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-pscreatememorypropertystore - // PSSTDAPI PSCreateMemoryPropertyStore( REFIID riid, void **ppv ); + /// + /// Creates an in-memory property store. + /// + /// + /// Type: REFIID + /// Reference to the requested interface ID. + /// + /// + /// Type: void** + /// When this function returns, contains a pointer to the desired interface, typically IPropertyStore or IPersistSerializedPropStorage. + /// + /// + /// Type: HRESULT + /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. + /// + /// + /// + /// This function creates an in-memory property store object that implements IPropertyStore, INamedPropertyStore, + /// IPropertyStoreCache, IPersistStream, IPropertyBag, and IPersistSerializedPropStorage. + /// + /// + /// The memory property store does not correspond to a file and is designed for use as a cache. IPropertyStore::Commit is a no-op, + /// and the data stored in the object persists only as long as the object does. + /// + /// + /// The memory property store is thread safe. It aggregates the free-threaded marshaller and uses critical sections to protect its + /// data members. + /// + /// Examples + /// The following example, to be included as part of a larger program, demonstrates how to use PSCreateMemoryPropertyStore. + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-pscreatememorypropertystore PSSTDAPI + // PSCreateMemoryPropertyStore( REFIID riid, void **ppv ); [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] [PInvokeData("propsys.h", MSDNShortId = "6e7a2ac0-2a4a-41ec-a2a8-ddbe8aa45bc9")] public static extern HRESULT PSCreateMemoryPropertyStore([In, MarshalAs(UnmanagedType.LPStruct)] Guid riid, [MarshalAs(UnmanagedType.Interface)] out object ppv); - /// Creates a read-only property store that contains multiple property stores, each of which must support either IPropertyStore or IPropertySetStorage.Type: IUnknown**Address of a pointer to an array of property stores that implement either IPropertyStore or IPropertySetStorage.Type: DWORDThe number of elements in the array referenced in prgpunkStores.Type: REFIIDReference to the requested IID.Type: void**When this function returns, contains the interface pointer requested in riid. This is typically IPropertyStore.Type: HRESULTIf this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.This function creates a Component Object Model (COM) object that implements IPropertyStore, INamedPropertyStore, IObjectProvider, and IPropertyStoreCapabilities. The multiplex property store object aggregates the properties exposed from multiple property stores.This object can be useful for aggregating the properties from multiple existing property store implementations in a Shell namespace extension, or for reusing an existing property store and providing additional read-only properties.Applications must call this object from only one thread at a time.You must initialize COM with CoInitialize or OleInitialize before you call PSCreateDelayedMultiplexPropertyStore. COM must remain initialized for the lifetime of this object.Each of the objects in the array prgpunkStores must implement either IPropertyStore or IPropertySetStorage. If an object implements IPropertySetStorage, it is wrapped using PSCreatePropertyStoreFromPropertySetStorage for use in the multiplex property store.The multiplex property store implementation of IPropertyStore::GetValue asks each of the provided property stores for the value. The multiplex property store stops searching when one of the property stores returns a success code and a non-VT_EMPTY value. Failure codes cause the search to end and are passed back to the calling application.The multiplex property store implementation of IPropertyStoreCapabilities::IsPropertyWritable delegates the call to the first store that implements IPropertyStoreCapabilities. If multiple stores implement IPropertyStoreCapabilities, the subsequent ones are ignored. If no store implements IPropertyStoreCapabilities, this method returns S_OK.ExamplesThe following example, to be included as part of a larger program, demonstrates how to use PSCreateMultiplexPropertyStore in an implementation of IPropertyStoreFactory::GetPropertyStore. - // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-pscreatemultiplexpropertystore - // PSSTDAPI PSCreateMultiplexPropertyStore( IUnknown **prgpunkStores, DWORD cStores, REFIID riid, void **ppv ); + /// + /// + /// Creates a read-only property store that contains multiple property stores, each of which must support either IPropertyStore or IPropertySetStorage. + /// + /// + /// + /// Type: IUnknown** + /// Address of a pointer to an array of property stores that implement either IPropertyStore or IPropertySetStorage. + /// + /// + /// Type: DWORD + /// The number of elements in the array referenced in prgpunkStores. + /// + /// + /// Type: REFIID + /// Reference to the requested IID. + /// + /// + /// Type: void** + /// When this function returns, contains the interface pointer requested in riid. This is typically IPropertyStore. + /// + /// + /// Type: HRESULT + /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. + /// + /// + /// + /// This function creates a Component Object Model (COM) object that implements IPropertyStore, INamedPropertyStore, IObjectProvider, + /// and IPropertyStoreCapabilities. The multiplex property store object aggregates the properties exposed from multiple property stores. + /// + /// + /// This object can be useful for aggregating the properties from multiple existing property store implementations in a Shell + /// namespace extension, or for reusing an existing property store and providing additional read-only properties. + /// + /// Applications must call this object from only one thread at a time. + /// + /// You must initialize COM with CoInitialize or OleInitialize before you call PSCreateDelayedMultiplexPropertyStore. COM must remain + /// initialized for the lifetime of this object. + /// + /// + /// Each of the objects in the array prgpunkStores must implement either IPropertyStore or IPropertySetStorage. If an object + /// implements IPropertySetStorage, it is wrapped using PSCreatePropertyStoreFromPropertySetStorage for use in the multiplex + /// property store. + /// + /// + /// The multiplex property store implementation of IPropertyStore::GetValue asks each of the provided property stores for the value. + /// The multiplex property store stops searching when one of the property stores returns a success code and a non-VT_EMPTY value. + /// Failure codes cause the search to end and are passed back to the calling application. + /// + /// + /// The multiplex property store implementation of IPropertyStoreCapabilities::IsPropertyWritable delegates the call to the first + /// store that implements IPropertyStoreCapabilities. If multiple stores implement IPropertyStoreCapabilities, the subsequent + /// ones are ignored. If no store implements IPropertyStoreCapabilities, this method returns S_OK. + /// + /// Examples + /// + /// The following example, to be included as part of a larger program, demonstrates how to use PSCreateMultiplexPropertyStore in an + /// implementation of IPropertyStoreFactory::GetPropertyStore. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-pscreatemultiplexpropertystore PSSTDAPI + // PSCreateMultiplexPropertyStore( IUnknown **prgpunkStores, DWORD cStores, REFIID riid, void **ppv ); [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] [PInvokeData("propsys.h", MSDNShortId = "4a6b5a10-5ef2-42c7-bf3b-dfa743be252f")] public static extern HRESULT PSCreateMultiplexPropertyStore([MarshalAs(UnmanagedType.LPArray, ArraySubType = UnmanagedType.IUnknown, SizeParamIndex = 1)] object[] prgpunkStores, - uint cStores, [In, MarshalAs(UnmanagedType.LPStruct)] Guid riid, [MarshalAs(UnmanagedType.Interface)] out object ppv); + uint cStores, [In, MarshalAs(UnmanagedType.LPStruct)] Guid riid, out IPropertyStore ppv); - /// Accepts the IUnknown interface of an object that supports IPropertyStore or IPropertySetStorage. If the object supports IPropertySetStorage, it is wrapped so that it supports IPropertyStore.Type: IUnknown*A pointer to an interface that supports either IPropertyStore or IPropertySetStorage.Type: DWORDSpecifies the access mode to use. One of these values:STGM_READOpen for reading.STGM_READWRITEOpen for reading and writing.Type: REFIIDReference to the requested IID.Type: void**When this function returns successfully, contains the address of a pointer to an interface guaranteed to support IPropertyStore.Type: HRESULTIf this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.If the object pointed to by punk already supports IPropertyStore, no wrapper is created and the punk is returned unaltered. - // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-pscreatepropertystorefromobject - // PSSTDAPI PSCreatePropertyStoreFromObject( IUnknown *punk, DWORD grfMode, REFIID riid, void **ppv ); + /// + /// + /// Accepts the IUnknown interface of an object that supports IPropertyStore or IPropertySetStorage. If the object supports + /// IPropertySetStorage, it is wrapped so that it supports IPropertyStore. + /// + /// + /// + /// Type: IUnknown* + /// A pointer to an interface that supports either IPropertyStore or IPropertySetStorage. + /// + /// + /// Type: DWORD + /// Specifies the access mode to use. One of these values: + /// STGM_READ + /// Open for reading. + /// STGM_READWRITE + /// Open for reading and writing. + /// + /// + /// Type: REFIID + /// Reference to the requested IID. + /// + /// + /// Type: void** + /// When this function returns successfully, contains the address of a pointer to an interface guaranteed to support IPropertyStore. + /// + /// + /// Type: HRESULT + /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. + /// + /// + /// If the object pointed to by punk already supports IPropertyStore, no wrapper is created and the punk is returned unaltered. + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-pscreatepropertystorefromobject PSSTDAPI + // PSCreatePropertyStoreFromObject( IUnknown *punk, DWORD grfMode, REFIID riid, void **ppv ); [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] [PInvokeData("propsys.h", MSDNShortId = "010572d5-0357-4101-803e-0a27fc60ca5e")] public static extern HRESULT PSCreatePropertyStoreFromObject([MarshalAs(UnmanagedType.IUnknown)] object punk, STGM grfMode, [In, MarshalAs(UnmanagedType.LPStruct)] Guid riid, [MarshalAs(UnmanagedType.Interface)] out object ppv); - /// Wraps an IPropertySetStorage interface in an IPropertyStore interface.Type: IPropertySetStorage*A pointer to an IPropertySetStorage interface.Type: DWORDSpecifies the access mode to enforce. grfMode should match the access mode used to open the IPropertySetStorage. Valid values are as follows:STGM_READCalls to IPropertyStore::SetValueupdate an internal cache of properties, and calls to IPropertyStore::Commitcall the appropriate IPropertySetStorage methods to write out the changed properties.STGM_WRITENot supported.STGM_READWRITENot supported.Type: REFIIDReference to an IID.Type: void**When this function returns, contains the interface pointer specified in riid.Type: HRESULTIf this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.This function wraps an IPropertySetStorage interface in an IPropertyStore interface. Any value other than STGM_READ for grfMode, causes calls to IPropertyStore::SetValue and IPropertyStore::Commit to fail with STG_E_ACCESSDENIED. - // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-pscreatepropertystorefrompropertysetstorage - // PSSTDAPI PSCreatePropertyStoreFromPropertySetStorage( IPropertySetStorage *ppss, DWORD grfMode, REFIID riid, void **ppv ); + /// + /// Wraps an IPropertySetStorage interface in an IPropertyStore interface. + /// + /// + /// Type: IPropertySetStorage* + /// A pointer to an IPropertySetStorage interface. + /// + /// + /// Type: DWORD + /// + /// Specifies the access mode to enforce. grfMode should match the access mode used to open the IPropertySetStorage. Valid values are + /// as follows: + /// + /// STGM_READ + /// + /// Calls to IPropertyStore::SetValueupdate an internal cache of properties, and calls to IPropertyStore::Commitcall the appropriate + /// IPropertySetStorage methods to write out the changed properties. + /// + /// STGM_WRITE + /// Not supported. + /// STGM_READWRITE + /// Not supported. + /// + /// + /// Type: REFIID + /// Reference to an IID. + /// + /// + /// Type: void** + /// When this function returns, contains the interface pointer specified in riid. + /// + /// + /// Type: HRESULT + /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. + /// + /// + /// + /// This function wraps an IPropertySetStorage interface in an IPropertyStore interface. Any value other than STGM_READ for + /// grfMode, causes calls to IPropertyStore::SetValue and IPropertyStore::Commit to fail with STG_E_ACCESSDENIED. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-pscreatepropertystorefrompropertysetstorage PSSTDAPI + // PSCreatePropertyStoreFromPropertySetStorage( IPropertySetStorage *ppss, DWORD grfMode, REFIID riid, void **ppv ); [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] [PInvokeData("propsys.h", MSDNShortId = "efba5a2a-df26-4f7e-9ddf-ec471e3d547c")] public static extern HRESULT PSCreatePropertyStoreFromPropertySetStorage(IPropertySetStorage ppss, STGM grfMode, [In, MarshalAs(UnmanagedType.LPStruct)] Guid riid, [MarshalAs(UnmanagedType.Interface)] out object ppv); - /// A wrapper API that calls the schema subsystem's IPropertySystem::EnumeratePropertyDescriptions. This function retrieves an instance of the subsystem object that implements IPropertyDescriptionList, to obtain either the entire list or a partial list of property descriptions in the system.Type: PROPDESC_ENUMFILTERThe list to return. PROPDESC_ENUMFILTER shows the valid values for this method.Type: REFIIDReference to the interface ID of the requested interface.Type: void**The address of an IPropertyDescriptionList interface pointer.Type: PSSTDAPIReturns one of the following values.Return codeDescription S_OK Indicates an interface is obtained. E_INVALIDARG Indicates that ppv is NULL. We recommend that you use the IID_PPV_ARGS macro, defined in objbase.h, to package the riid and ppv parameters. This macro provides the correct IID based on the interface pointed to by the value in ppv, eliminating the possibility of a coding error. - // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-psenumeratepropertydescriptions - // PSSTDAPI PSEnumeratePropertyDescriptions( PROPDESC_ENUMFILTER filterOn, REFIID riid, void **ppv ); + /// + /// + /// A wrapper API that calls the schema subsystem's IPropertySystem::EnumeratePropertyDescriptions. This function retrieves an + /// instance of the subsystem object that implements IPropertyDescriptionList, to obtain either the entire list or a partial list of + /// property descriptions in the system. + /// + /// + /// + /// Type: PROPDESC_ENUMFILTER + /// The list to return. PROPDESC_ENUMFILTER shows the valid values for this method. + /// + /// + /// Type: REFIID + /// Reference to the interface ID of the requested interface. + /// + /// + /// Type: void** + /// The address of an IPropertyDescriptionList interface pointer. + /// + /// + /// Type: PSSTDAPI + /// Returns one of the following values. + /// + /// + /// Return code + /// Description + /// + /// + /// S_OK + /// Indicates an interface is obtained. + /// + /// + /// E_INVALIDARG + /// Indicates that ppv is NULL. + /// + /// + /// + /// + /// + /// We recommend that you use the IID_PPV_ARGS macro, defined in objbase.h, to package the riid and ppv parameters. This macro + /// provides the correct IID based on the interface pointed to by the value in ppv, eliminating the possibility of a coding error. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-psenumeratepropertydescriptions PSSTDAPI + // PSEnumeratePropertyDescriptions( PROPDESC_ENUMFILTER filterOn, REFIID riid, void **ppv ); [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] [PInvokeData("propsys.h", MSDNShortId = "687d5a32-3a2e-4b9b-b06c-ca06a6cd1595")] - public static extern HRESULT PSEnumeratePropertyDescriptions(PROPDESC_ENUMFILTER filterOn, [In, MarshalAs(UnmanagedType.LPStruct)] Guid riid, [MarshalAs(UnmanagedType.Interface)] out object ppv); + public static extern HRESULT PSEnumeratePropertyDescriptions(PROPDESC_ENUMFILTER filterOn, [In, MarshalAs(UnmanagedType.LPStruct)] Guid riid, out IPropertyDescriptionList ppv); - /// Gets a formatted, Unicode string representation of a property value stored in a PROPVARIANT structure. The caller is responsible for allocating the output buffer.Type: REFPROPERTYKEYReference to a PROPERTYKEY that names the property whose value is being retrieved.Type: REFPROPVARIANTReference to a PROPVARIANT structure that contains the type and value of the property.Type: PROPDESC_FORMAT_FLAGSA flag that specifies the format to apply to the property string. See PROPDESC_FORMAT_FLAGS for possible values.Type: LPWSTRWhen the function returns, contains a pointer to the formatted value as a null-terminated, Unicode string. The calling application is responsible for allocating memory for the buffer before it calls PSFormatForDisplay.Type: DWORDSpecifies the length of the buffer at pwszText in WCHARs, including the terminating null character.Type: HRESULTReturns one of the following values.Return codeDescription S_OK The formatted string was successfully created. S_FALSE The formatted string was not created. S_FALSE indicates that an empty string resulted from a VT_EMPTY. E_OUTOFMEMORY Indicates allocation failed.This function calls the schema subsystem's implementation of IPropertySystem::FormatForDisplay. That call provides a Unicode string representation of a property value, with additional formatting based on one or more PROPDESC_FORMAT_FLAGS. If the PROPERTYKEY is not recognized by the schema subsystem, IPropertySystem::FormatForDisplay attempts to format the value according to the value's VARTYPE.You must initialize Component Object Model (COM) with CoInitialize or OleInitialize before you call PSFormatPropertyValue.The purpose of this function is to convert data into a string suitable for display to the user. The value is formatted according to the current locale, the language of the user, the PROPDESC_FORMAT_FLAGS, and the property description specified by the property key. For information on how the property description schema influences the formatting of the value, see the following topics:displayInfostringFormatbooleanFormatnumberFormatNMDATETIMEFORMATenumeratedListTypically, the PROPDESC_FORMAT_FLAGS are used to modify the format prescribed by the property description.The output string can contain Unicode directional characters. These nonspacing characters influence the Unicode bidirectional algorithm so that the values appear correctly when a left-to-right (LTR) language is drawn on a right-to-left (RTL) window, or an RTL is drawn on a LTR window. These characters include the following: The following properties use special formats and are unaffected by the PROPDESC_FORMAT_FLAGS. Note that examples cited are for strings with a current locale set to English; typically, output is localized except where noted.PropertyFormatSystem.FileAttributesThe following file attributes are converted to letters and appended to create a string (for example, a value of 0x1801 is converted to "RCO"):FILE_ATTRIBUTE_READONLY- 'R'FILE_ATTRIBUTE_SYSTEM - 'S'FILE_ATTRIBUTE_ARCHIVE -'A'FILE_ATTRIBUTE_COMPRESSED - 'C'FILE_ATTRIBUTE_ENCRYPTED - 'E'FILE_ATTRIBUTE_OFFLINE - 'O'FILE_ATTRIBUTE_NOT_CONTENT_INDEXED - 'I'System.Photo.ISOSpeedFor example, "ISO-400".System.Photo.ShutterSpeed The APEX value is converted to an exposure time using this formula: For example, "2 sec."or "1/125 sec.".System.Photo.ExposureTimeFor example, "2 sec."or "1/125 sec."System.Photo.Aperture The APEX value is converted to an F number using this formula: For example, "f/5.6".System.Photo.FNumberFor example, "f/5.6".System.Photo.SubjectDistanceFor example, "15 m"or "250 mm".System.Photo.FocalLengthFor example, "50 mm".System.Photo.FlashEnergyFor example, "500 bpcs".System.Photo.ExposureBiasFor example, "-2 step", " 0 step", or "+3 step".System.Computer.DecoratedFreeSpaceFor example, "105 MB free of 13.2 GB".System.ItemTypeFor example, "Application" or "JPEG Image".System.ControlPanel.CategoryFor example, "Appearance and Personalization".System.ComputerNameFor example, "LITWARE05 (this computer)" or "testbox07".If the property key does not correspond to a property description in any of the registered property schemas, then this function chooses a format based on the type of the value.Type of the valueFormatVT_BOOLEANNot supported.VT_FILETIMEDate/time string as specified by PROPDESC_FORMAT_FLAGS and the current locale. PDFF_SHORTTIME and PDFF_SHORTDATE are the default. For example, "11/13/2006 3:22 PM".Numeric VARTYPEDecimal string in the current locale. For example, "42".VT_LPWSTR or otherConverted to a string. Sequences of "\r", "\t", or "\n" are replaced with a single space.VT_VECTOR | anythingSemicolon separated values. A semicolon is used regardless of locale.ExamplesThe following example, to be included as part of a larger program, demonstrates how to use PSFormatForDisplay to format a rating value. - // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-psformatfordisplay - // PSSTDAPI PSFormatForDisplay( REFPROPERTYKEY propkey, REFPROPVARIANT propvar, PROPDESC_FORMAT_FLAGS pdfFlags, LPWSTR pwszText, DWORD cchText ); + /// + /// + /// Gets a formatted, Unicode string representation of a property value stored in a PROPVARIANT structure. The caller is responsible + /// for allocating the output buffer. + /// + /// + /// + /// Type: REFPROPERTYKEY + /// Reference to a PROPERTYKEY that names the property whose value is being retrieved. + /// + /// + /// Type: REFPROPVARIANT + /// Reference to a PROPVARIANT structure that contains the type and value of the property. + /// + /// + /// Type: PROPDESC_FORMAT_FLAGS + /// A flag that specifies the format to apply to the property string. See PROPDESC_FORMAT_FLAGS for possible values. + /// + /// + /// Type: LPWSTR + /// + /// When the function returns, contains a pointer to the formatted value as a null-terminated, Unicode string. The calling + /// application is responsible for allocating memory for the buffer before it calls PSFormatForDisplay. + /// + /// + /// + /// Type: DWORD + /// Specifies the length of the buffer at pwszText in WCHARs, including the terminating null character. + /// + /// + /// Type: HRESULT + /// Returns one of the following values. + /// + /// + /// Return code + /// Description + /// + /// + /// S_OK + /// The formatted string was successfully created. + /// + /// + /// S_FALSE + /// The formatted string was not created. S_FALSE indicates that an empty string resulted from a VT_EMPTY. + /// + /// + /// E_OUTOFMEMORY + /// Indicates allocation failed. + /// + /// + /// + /// + /// + /// This function calls the schema subsystem's implementation of IPropertySystem::FormatForDisplay. That call provides a Unicode + /// string representation of a property value, with additional formatting based on one or more PROPDESC_FORMAT_FLAGS. If the + /// PROPERTYKEY is not recognized by the schema subsystem, IPropertySystem::FormatForDisplay attempts to format the value + /// according to the value's VARTYPE. + /// + /// You must initialize Component Object Model (COM) with CoInitialize or OleInitialize before you call PSFormatPropertyValue. + /// + /// The purpose of this function is to convert data into a string suitable for display to the user. The value is formatted according + /// to the current locale, the language of the user, the PROPDESC_FORMAT_FLAGS, and the property description specified by the + /// property key. For information on how the property description schema influences the formatting of the value, see the following topics: + /// + /// + /// + /// displayInfo + /// + /// + /// stringFormat + /// + /// + /// booleanFormat + /// + /// + /// numberFormat + /// + /// + /// NMDATETIMEFORMAT + /// + /// + /// enumeratedList + /// + /// + /// Typically, the PROPDESC_FORMAT_FLAGS are used to modify the format prescribed by the property description. + /// + /// The output string can contain Unicode directional characters. These nonspacing characters influence the Unicode bidirectional + /// algorithm so that the values appear correctly when a left-to-right (LTR) language is drawn on a right-to-left (RTL) window, or an + /// RTL is drawn on a LTR window. These characters include the following: + /// + /// + /// The following properties use special formats and are unaffected by the PROPDESC_FORMAT_FLAGS. Note that examples cited are for + /// strings with a current locale set to English; typically, output is localized except where noted. + /// + /// + /// + /// Property + /// Format + /// + /// + /// System.FileAttributes + /// + /// The following file attributes are converted to letters and appended to create a string (for example, a value of 0x1801 is + /// converted to "RCO"): + /// + /// + /// + /// + /// FILE_ATTRIBUTE_READONLY- 'R' + /// + /// + /// + /// FILE_ATTRIBUTE_SYSTEM - 'S' + /// + /// + /// + /// FILE_ATTRIBUTE_ARCHIVE -'A' + /// + /// + /// + /// FILE_ATTRIBUTE_COMPRESSED - 'C' + /// + /// + /// + /// FILE_ATTRIBUTE_ENCRYPTED - 'E' + /// + /// + /// + /// FILE_ATTRIBUTE_OFFLINE - 'O' + /// + /// + /// + /// FILE_ATTRIBUTE_NOT_CONTENT_INDEXED - 'I' + /// + /// + /// System.Photo.ISOSpeed + /// For example, "ISO-400". + /// + /// + /// System.Photo.ShutterSpeed + /// The APEX value is converted to an exposure time using this formula: For example, "2 sec."or "1/125 sec.". + /// + /// + /// System.Photo.ExposureTime + /// For example, "2 sec."or "1/125 sec." + /// + /// + /// System.Photo.Aperture + /// The APEX value is converted to an F number using this formula: For example, "f/5.6". + /// + /// + /// System.Photo.FNumber + /// For example, "f/5.6". + /// + /// + /// System.Photo.SubjectDistance + /// For example, "15 m"or "250 mm". + /// + /// + /// System.Photo.FocalLength + /// For example, "50 mm". + /// + /// + /// System.Photo.FlashEnergy + /// For example, "500 bpcs". + /// + /// + /// System.Photo.ExposureBias + /// For example, "-2 step", " 0 step", or "+3 step". + /// + /// + /// System.Computer.DecoratedFreeSpace + /// For example, "105 MB free of 13.2 GB". + /// + /// + /// System.ItemType + /// For example, "Application" or "JPEG Image". + /// + /// + /// System.ControlPanel.Category + /// For example, "Appearance and Personalization". + /// + /// + /// System.ComputerName + /// For example, "LITWARE05 (this computer)" or "testbox07". + /// + /// + /// + /// If the property key does not correspond to a property description in any of the registered property schemas, then this function + /// chooses a format based on the type of the value. + /// + /// + /// + /// Type of the value + /// Format + /// + /// + /// VT_BOOLEAN + /// Not supported. + /// + /// + /// VT_FILETIME + /// + /// Date/time string as specified by PROPDESC_FORMAT_FLAGS and the current locale. PDFF_SHORTTIME and PDFF_SHORTDATE are the default. + /// For example, "11/13/2006 3:22 PM". + /// + /// + /// + /// Numeric VARTYPE + /// Decimal string in the current locale. For example, "42". + /// + /// + /// VT_LPWSTR or other + /// Converted to a string. Sequences of "\r", "\t", or "\n" are replaced with a single space. + /// + /// + /// VT_VECTOR | anything + /// Semicolon separated values. A semicolon is used regardless of locale. + /// + /// + /// Examples + /// + /// The following example, to be included as part of a larger program, demonstrates how to use PSFormatForDisplay to format a rating value. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-psformatfordisplay PSSTDAPI PSFormatForDisplay( + // REFPROPERTYKEY propkey, REFPROPVARIANT propvar, PROPDESC_FORMAT_FLAGS pdfFlags, LPWSTR pwszText, DWORD cchText ); [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] [PInvokeData("propsys.h", MSDNShortId = "71442967-ee8a-448c-83cf-949934ddd152")] public static extern HRESULT PSFormatForDisplay([In, MarshalAs(UnmanagedType.LPStruct)] PROPERTYKEY propkey, PROPVARIANT propvar, PROPDESC_FORMAT_FLAGS pdfFlags, @@ -481,132 +1057,1455 @@ namespace Vanara.PInvoke /// rating value. /// /// - // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-psformatfordisplayalloc - // PSSTDAPI PSFormatForDisplayAlloc( REFPROPERTYKEY key, REFPROPVARIANT propvar, PROPDESC_FORMAT_FLAGS pdff, PWSTR *ppszDisplay ); + // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-psformatfordisplayalloc PSSTDAPI PSFormatForDisplayAlloc( + // REFPROPERTYKEY key, REFPROPVARIANT propvar, PROPDESC_FORMAT_FLAGS pdff, PWSTR *ppszDisplay ); [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] [PInvokeData("propsys.h", MSDNShortId = "d411ea72-fb29-47b6-a7f6-0839b3e2caf2")] public static extern HRESULT PSFormatForDisplayAlloc([In, MarshalAs(UnmanagedType.LPStruct)] PROPERTYKEY key, PROPVARIANT propvar, PROPDESC_FORMAT_FLAGS pdff, [MarshalAs(UnmanagedType.CustomMarshaler, MarshalTypeRef = typeof(CoTaskMemStringMarshaler))] out string ppszDisplay); - /// Gets a formatted, Unicode string representation of a property value stored in a property store. This function allocates memory for the output string.Type: IPropertyStore*Pointer to an IPropertyStore, which represents the property store from which the property value is taken.Type: IPropertyDescription*Pointer to an IPropertyDescription, which represents the property whose value is being retrieved.Type: PROPDESC_FORMAT_FLAGSOne or more PROPDESC_FORMAT_FLAGS that specify the format to apply to the property string. See PROPDESC_FORMAT_FLAGS for possible values.Type: LPWSTR*When the function returns, contains a pointer to the formatted value as a null-terminated, Unicode string.Type: HRESULTIf this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.This function uses the ppd parameter to call IPropertyDescription::FormatForDisplay. That call provides a Unicode string representation of a property value, with additional formatting based on one or more PROPDESC_FORMAT_FLAGS.You must initialize Component Object Model (COM) with CoInitialize or OleInitialize before you call PSFormatPropertyValue.The function allocates memory and returns a pointer to that memory in ppszDisplay. The calling application must use CoTaskMemFree to release the string specified by ppszDisplay when it is no longer needed.The purpose of this function is to convert data into a string suitable for display to the user. The value is formatted according to the current locale, the language of the user, the PROPDESC_FORMAT_FLAGS, and the property description specified by the property key. For information on how the property description schema influences the formatting of the value, see the following topics:displayInfostringFormatbooleanFormatnumberFormatNMDATETIMEFORMATenumeratedListTypically, the PROPDESC_FORMAT_FLAGS are used to modify the format prescribed by the property description.The output string can contain Unicode directional characters. These nonspacing characters influence the Unicode bidirectional algorithm so that the values appear correctly when a left-to-right (LTR) language is drawn on a right-to-left (RTL) window, or an RTL is drawn on a LTR window. These characters include the following: The following properties use special formats and are unaffected by the PROPDESC_FORMAT_FLAGS. Note that examples cited are for strings with a current locale set to English; typically, output is localized except where noted.PropertyFormatSystem.FileAttributesThe following file attributes are converted to letters and appended to create a string (for example, a value of 0x1801 (FILE_ATTRIBUTE_READONLY | FILE_ATTRIBUTE_COMPRESSED | FILE_ATTRIBUTE_OFFLINE) is converted to "RCO"): System.Photo.ISOSpeedFor example, "ISO-400".System.Photo.ShutterSpeed The APEX value is converted to an exposure time using this formula: For example, "2 sec."or "1/125 sec.".System.Photo.ExposureTimeFor example, "2 sec."or "1/125 sec."System.Photo.Aperture The APEX value is converted to an F number using this formula: For example, "f/5.6".System.Photo.FNumberFor example, "f/5.6".System.Photo.SubjectDistanceFor example, "15 m"or "250 mm".System.Photo.FocalLengthFor example, "50 mm".System.Photo.FlashEnergyFor example, "500 bpcs".System.Photo.ExposureBiasFor example, "-2 step", " 0 step", or "+3 step".System.Computer.DecoratedFreeSpaceFor example, "105 MB free of 13.2 GB".System.ItemTypeFor example, "Application" or "JPEG Image".System.ControlPanel.CategoryFor example, "Appearance and Personalization".System.ComputerNameFor example, "LITWARE05 (this computer)" or "testbox07".If the property key does not correspond to a property description in any of the registered property schemas, then this function chooses a format based on the type of the value.Type of the valueFormatVT_BOOLEANNot supported.VT_FILETIMEDate/time string as specified by PROPDESC_FORMAT_FLAGS and the current locale. PDFF_SHORTTIME and PDFF_SHORTDATE are the default. For example, "11/13/2006 3:22 PM".Numeric VARTYPEDecimal string in the current locale. For example, "42".VT_LPWSTR or otherConverted to a string. Sequences of "\r", "\t", or "\n" are replaced with a single space.VT_VECTOR | anythingSemicolon separated values. A semicolon is used regardless of locale.ExamplesThe following example, to be included as part of a larger program, demonstrates how to use PSFormatPropertyValue to format a rating value. - // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-psformatpropertyvalue - // PSSTDAPI PSFormatPropertyValue( IPropertyStore *pps, IPropertyDescription *ppd, PROPDESC_FORMAT_FLAGS pdff, LPWSTR *ppszDisplay ); + /// + /// + /// Gets a formatted, Unicode string representation of a property value stored in a property store. This function allocates memory + /// for the output string. + /// + /// + /// + /// Type: IPropertyStore* + /// Pointer to an IPropertyStore, which represents the property store from which the property value is taken. + /// + /// + /// Type: IPropertyDescription* + /// Pointer to an IPropertyDescription, which represents the property whose value is being retrieved. + /// + /// + /// Type: PROPDESC_FORMAT_FLAGS + /// + /// One or more PROPDESC_FORMAT_FLAGS that specify the format to apply to the property string. See PROPDESC_FORMAT_FLAGS for + /// possible values. + /// + /// + /// + /// Type: LPWSTR* + /// When the function returns, contains a pointer to the formatted value as a null-terminated, Unicode string. + /// + /// + /// Type: HRESULT + /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. + /// + /// + /// + /// This function uses the ppd parameter to call IPropertyDescription::FormatForDisplay. That call provides a Unicode string + /// representation of a property value, with additional formatting based on one or more PROPDESC_FORMAT_FLAGS. + /// + /// You must initialize Component Object Model (COM) with CoInitialize or OleInitialize before you call PSFormatPropertyValue. + /// + /// The function allocates memory and returns a pointer to that memory in ppszDisplay. The calling application must use CoTaskMemFree + /// to release the string specified by ppszDisplay when it is no longer needed. + /// + /// + /// The purpose of this function is to convert data into a string suitable for display to the user. The value is formatted according + /// to the current locale, the language of the user, the PROPDESC_FORMAT_FLAGS, and the property description specified by the + /// property key. For information on how the property description schema influences the formatting of the value, see the following topics: + /// + /// + /// + /// displayInfo + /// + /// + /// stringFormat + /// + /// + /// booleanFormat + /// + /// + /// numberFormat + /// + /// + /// NMDATETIMEFORMAT + /// + /// + /// enumeratedList + /// + /// + /// Typically, the PROPDESC_FORMAT_FLAGS are used to modify the format prescribed by the property description. + /// + /// The output string can contain Unicode directional characters. These nonspacing characters influence the Unicode bidirectional + /// algorithm so that the values appear correctly when a left-to-right (LTR) language is drawn on a right-to-left (RTL) window, or an + /// RTL is drawn on a LTR window. These characters include the following: + /// + /// + /// The following properties use special formats and are unaffected by the PROPDESC_FORMAT_FLAGS. Note that examples cited are for + /// strings with a current locale set to English; typically, output is localized except where noted. + /// + /// + /// + /// Property + /// Format + /// + /// + /// System.FileAttributes + /// + /// The following file attributes are converted to letters and appended to create a string (for example, a value of 0x1801 + /// (FILE_ATTRIBUTE_READONLY | FILE_ATTRIBUTE_COMPRESSED | FILE_ATTRIBUTE_OFFLINE) is converted to "RCO"): + /// + /// + /// + /// System.Photo.ISOSpeed + /// For example, "ISO-400". + /// + /// + /// System.Photo.ShutterSpeed + /// The APEX value is converted to an exposure time using this formula: For example, "2 sec."or "1/125 sec.". + /// + /// + /// System.Photo.ExposureTime + /// For example, "2 sec."or "1/125 sec." + /// + /// + /// System.Photo.Aperture + /// The APEX value is converted to an F number using this formula: For example, "f/5.6". + /// + /// + /// System.Photo.FNumber + /// For example, "f/5.6". + /// + /// + /// System.Photo.SubjectDistance + /// For example, "15 m"or "250 mm". + /// + /// + /// System.Photo.FocalLength + /// For example, "50 mm". + /// + /// + /// System.Photo.FlashEnergy + /// For example, "500 bpcs". + /// + /// + /// System.Photo.ExposureBias + /// For example, "-2 step", " 0 step", or "+3 step". + /// + /// + /// System.Computer.DecoratedFreeSpace + /// For example, "105 MB free of 13.2 GB". + /// + /// + /// System.ItemType + /// For example, "Application" or "JPEG Image". + /// + /// + /// System.ControlPanel.Category + /// For example, "Appearance and Personalization". + /// + /// + /// System.ComputerName + /// For example, "LITWARE05 (this computer)" or "testbox07". + /// + /// + /// + /// If the property key does not correspond to a property description in any of the registered property schemas, then this function + /// chooses a format based on the type of the value. + /// + /// + /// + /// Type of the value + /// Format + /// + /// + /// VT_BOOLEAN + /// Not supported. + /// + /// + /// VT_FILETIME + /// + /// Date/time string as specified by PROPDESC_FORMAT_FLAGS and the current locale. PDFF_SHORTTIME and PDFF_SHORTDATE are the default. + /// For example, "11/13/2006 3:22 PM". + /// + /// + /// + /// Numeric VARTYPE + /// Decimal string in the current locale. For example, "42". + /// + /// + /// VT_LPWSTR or other + /// Converted to a string. Sequences of "\r", "\t", or "\n" are replaced with a single space. + /// + /// + /// VT_VECTOR | anything + /// Semicolon separated values. A semicolon is used regardless of locale. + /// + /// + /// Examples + /// + /// The following example, to be included as part of a larger program, demonstrates how to use PSFormatPropertyValue to format a + /// rating value. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-psformatpropertyvalue PSSTDAPI PSFormatPropertyValue( + // IPropertyStore *pps, IPropertyDescription *ppd, PROPDESC_FORMAT_FLAGS pdff, LPWSTR *ppszDisplay ); [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] [PInvokeData("propsys.h", MSDNShortId = "35c2b424-05bd-4d7d-8365-5900e165e2e2")] - public static extern HRESULT PSFormatPropertyValue(IPropertyStore pps, IPropertyDescription ppd, PROPDESC_FORMAT_FLAGS pdff, + public static extern HRESULT PSFormatPropertyValue(IPropertyStore pps, IPropertyDescription ppd, PROPDESC_FORMAT_FLAGS pdff, [MarshalAs(UnmanagedType.CustomMarshaler, MarshalTypeRef = typeof(CoTaskMemStringMarshaler))] out string ppszDisplay); - /// Gets an instance of a property description interface for a specified property.Type: REFPROPERTYKEYA reference to a PROPERTYKEY structure that specifies the property.Type: REFIIDA reference to the IID of the interface to retrieve through ppv.Type: void**When this function returns successfully, contains the interface pointer requested in riid.Type: HRESULTReturns S_OK if successful, or an error value otherwise, including the following:Return codeDescription TYPE_E_ELEMENTNOTFOUND We recommend that you use the IID_PPV_ARGS macro, defined in Objbase.h, to package the riid and ppv parameters. This macro provides the correct IID based on the interface pointed to by the value in ppv, which eliminates the possibility of a coding error in riid that could lead to unexpected results. - // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-psgetimagereferenceforvalue - // PSSTDAPI PSGetImageReferenceForValue( REFPROPERTYKEY propkey, REFPROPVARIANT propvar, PWSTR *ppszImageRes ); + /// + /// Gets an instance of a property description interface for a specified property. + /// + /// + /// Type: REFPROPERTYKEY + /// A reference to a PROPERTYKEY structure that specifies the property. + /// + /// + /// Type: REFIID + /// A reference to the IID of the interface to retrieve through ppv. + /// + /// + /// Type: void** + /// When this function returns successfully, contains the interface pointer requested in riid. + /// + /// + /// Type: HRESULT + /// Returns S_OK if successful, or an error value otherwise, including the following: + /// + /// + /// Return code + /// Description + /// + /// + /// TYPE_E_ELEMENTNOTFOUND + /// + /// + /// + /// + /// + /// + /// We recommend that you use the IID_PPV_ARGS macro, defined in Objbase.h, to package the riid and ppv parameters. This macro + /// provides the correct IID based on the interface pointed to by the value in ppv, which eliminates the possibility of a coding + /// error in riid that could lead to unexpected results. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-psgetimagereferenceforvalue PSSTDAPI + // PSGetImageReferenceForValue( REFPROPERTYKEY propkey, REFPROPVARIANT propvar, PWSTR *ppszImageRes ); [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] [PInvokeData("propsys.h", MSDNShortId = "E37AF2ED-E3F9-4e50-9317-9DAF03AC543F")] public static extern HRESULT PSGetImageReferenceForValue([In, MarshalAs(UnmanagedType.LPStruct)] PROPERTYKEY propkey, PROPVARIANT propvar, [MarshalAs(UnmanagedType.CustomMarshaler, MarshalTypeRef = typeof(CoTaskMemStringMarshaler))] out string ppszImageRes); - /// Retrieves a property handler for a Shell item.Type: IUnknown*A pointer to the IUnknown interface of a Shell item that supports IShellItem.Windows XP: Use SHCreateShellItem to create the Shell item.Windows Vista: Use SHCreateItemFromIDList, SHCreateItemFromParsingName, SHCreateItemFromRelativeName, SHCreateItemInKnownFolder, or SHCreateItemWithParent to create the Shell item.Type: BOOLTRUE to retrieve a read/write property handler. FALSE to retrieve a read-only property handler.Type: REFIIDReference to the IID of the interface the handler object should return. This should be IPropertyStore or an interface derived from IPropertyStore.Type: void**When this function returns, contains the interface pointer requested in riid.Type: PSSTDAPIReturns S_OK if successful, or an error value otherwise.This function is supported in Windows XP and Windows Vista. For applications supported only on Windows Vista or later, it is recommended that you use IShellItem2::GetPropertyStore instead of PSGetItemPropertyHandler. That method provides a richer set of properties in the property store that is returned.This function is approximately equivalent to passing the GPS_HANDLERPROPERTIESONLY flag to IShellItem2::GetPropertyStore.You must initialize Component Object Model (COM) with CoInitialize or OleInitialize before you call PSGetItemPropertyHandler. COM must remain initialized for the lifetime of this object.ExamplesThe following example, to be included as part of a larger program, demonstrates how to use PSGetItemPropertyHandler to obtain a property handler for an item. - // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-psgetitempropertyhandler - // PSSTDAPI PSGetItemPropertyHandler( IUnknown *punkItem, BOOL fReadWrite, REFIID riid, void **ppv ); + /// + /// Retrieves a property handler for a Shell item. + /// + /// + /// Type: IUnknown* + /// A pointer to the IUnknown interface of a Shell item that supports IShellItem. + /// Windows XP: Use SHCreateShellItem to create the Shell item. + /// + /// Windows Vista: Use SHCreateItemFromIDList, SHCreateItemFromParsingName, SHCreateItemFromRelativeName, + /// SHCreateItemInKnownFolder, or SHCreateItemWithParent to create the Shell item. + /// + /// + /// + /// Type: BOOL + /// TRUE to retrieve a read/write property handler. FALSE to retrieve a read-only property handler. + /// + /// + /// Type: REFIID + /// + /// Reference to the IID of the interface the handler object should return. This should be IPropertyStore or an interface derived + /// from IPropertyStore. + /// + /// + /// + /// Type: void** + /// When this function returns, contains the interface pointer requested in riid. + /// + /// + /// Type: PSSTDAPI + /// Returns S_OK if successful, or an error value otherwise. + /// + /// + /// + /// This function is supported in Windows XP and Windows Vista. For applications supported only on Windows Vista or later, it is + /// recommended that you use IShellItem2::GetPropertyStore instead of PSGetItemPropertyHandler. That method provides a richer set of + /// properties in the property store that is returned. + /// + /// This function is approximately equivalent to passing the GPS_HANDLERPROPERTIESONLY flag to IShellItem2::GetPropertyStore. + /// + /// You must initialize Component Object Model (COM) with CoInitialize or OleInitialize before you call PSGetItemPropertyHandler. COM + /// must remain initialized for the lifetime of this object. + /// + /// Examples + /// + /// The following example, to be included as part of a larger program, demonstrates how to use PSGetItemPropertyHandler to obtain a + /// property handler for an item. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-psgetitempropertyhandler PSSTDAPI + // PSGetItemPropertyHandler( IUnknown *punkItem, BOOL fReadWrite, REFIID riid, void **ppv ); [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] [PInvokeData("propsys.h", MSDNShortId = "7b7fd260-c863-41f7-8594-4ee435090228")] public static extern HRESULT PSGetItemPropertyHandler([MarshalAs(UnmanagedType.IUnknown)] object punkItem, [MarshalAs(UnmanagedType.Bool)] bool fReadWrite, [In, MarshalAs(UnmanagedType.LPStruct)] Guid riid, [MarshalAs(UnmanagedType.Interface)] out object ppv); - /// Retrieves a property handler for a Shell item.Type: IUnknown*A pointer to the IUnknown interface of a Shell item that supports IShellItem.Windows XP: Use SHCreateShellItem to create the Shell item.Windows Vista: Use SHCreateItemFromIDList, SHCreateItemFromParsingName, SHCreateItemFromRelativeName, SHCreateItemInKnownFolder, or SHCreateItemWithParent to create the Shell item.Type: BOOLTRUE to retrieve a read/write property handler. FALSE to retrieve a read-only property handler.Type: IUnknown*Pointer to the IUnknown interface of a class factory object that supports ICreateObject.Type: REFIIDA reference to the IID of the interface to retrieve through ppv.Type: void**When this function returns successfully, contains the interface pointer requested in riid. This is typically IPropertyStore or IPropertyStoreCapabilities.Type: PSSTDAPIReturns S_OK if successful, or an error value otherwise.This function is supported in Windows XP as part of the Microsoft Windows Desktop Search (WDS) redistributable which includes IPropertyStore and supporting interfaces. For applications supported only on Windows Vista or later, we recommend that you use IShellItem2::GetPropertyStoreWithCreateObject instead of PSGetItemPropertyHandlerWithCreateObject because IShellItem2::GetPropertyStoreWithCreateObject provides a richer set of properties in the property store that is returned.This function is approximately equivalent to passing the GPS_HANDLERPROPERTIESONLY flag to IShellItem2::GetPropertyStoreWithCreateObject.The punkCreateObject parameter enables the creation of a property store in a different context than that of the caller. For instance, the ICreateObject implementation can cause the property store to be created in another process. This parameter is used only for property handlers that support it and that are registered underYou must initialize Component Object Model (COM) with CoInitialize or OleInitialize before you call PSGetItemPropertyHandlerWithCreateObject. COM must remain initialized for the lifetime of this object.ExamplesThe following example, to be included as part of a larger program, demonstrates how to use PSGetItemPropertyHandlerWithCreateObject to obtain a property handler for an item. - // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-psgetitempropertyhandlerwithcreateobject - // PSSTDAPI PSGetItemPropertyHandlerWithCreateObject( IUnknown *punkItem, BOOL fReadWrite, IUnknown *punkCreateObject, REFIID riid, void **ppv ); + /// + /// Retrieves a property handler for a Shell item. + /// + /// + /// Type: IUnknown* + /// A pointer to the IUnknown interface of a Shell item that supports IShellItem. + /// Windows XP: Use SHCreateShellItem to create the Shell item. + /// + /// Windows Vista: Use SHCreateItemFromIDList, SHCreateItemFromParsingName, SHCreateItemFromRelativeName, + /// SHCreateItemInKnownFolder, or SHCreateItemWithParent to create the Shell item. + /// + /// + /// + /// Type: BOOL + /// TRUE to retrieve a read/write property handler. FALSE to retrieve a read-only property handler. + /// + /// + /// Type: IUnknown* + /// Pointer to the IUnknown interface of a class factory object that supports ICreateObject. + /// + /// + /// Type: REFIID + /// A reference to the IID of the interface to retrieve through ppv. + /// + /// + /// Type: void** + /// + /// When this function returns successfully, contains the interface pointer requested in riid. This is typically IPropertyStore or IPropertyStoreCapabilities. + /// + /// + /// + /// Type: PSSTDAPI + /// Returns S_OK if successful, or an error value otherwise. + /// + /// + /// + /// This function is supported in Windows XP as part of the Microsoft Windows Desktop Search (WDS) redistributable which includes + /// IPropertyStore and supporting interfaces. For applications supported only on Windows Vista or later, we recommend that you use + /// IShellItem2::GetPropertyStoreWithCreateObject instead of PSGetItemPropertyHandlerWithCreateObject because + /// IShellItem2::GetPropertyStoreWithCreateObject provides a richer set of properties in the property store that is returned. + /// + /// This function is approximately equivalent to passing the GPS_HANDLERPROPERTIESONLY flag to IShellItem2::GetPropertyStoreWithCreateObject. + /// + /// The punkCreateObject parameter enables the creation of a property store in a different context than that of the caller. For + /// instance, the ICreateObject implementation can cause the property store to be created in another process. This parameter is used + /// only for property handlers that support it and that are registered under + /// + /// + /// You must initialize Component Object Model (COM) with CoInitialize or OleInitialize before you call + /// PSGetItemPropertyHandlerWithCreateObject. COM must remain initialized for the lifetime of this object. + /// + /// Examples + /// + /// The following example, to be included as part of a larger program, demonstrates how to use + /// PSGetItemPropertyHandlerWithCreateObject to obtain a property handler for an item. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-psgetitempropertyhandlerwithcreateobject PSSTDAPI + // PSGetItemPropertyHandlerWithCreateObject( IUnknown *punkItem, BOOL fReadWrite, IUnknown *punkCreateObject, REFIID riid, void **ppv ); [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] [PInvokeData("propsys.h", MSDNShortId = "82e0aa15-b67c-4c0a-bafb-f1dc5f822aec")] public static extern HRESULT PSGetItemPropertyHandlerWithCreateObject([MarshalAs(UnmanagedType.IUnknown)] object punkItem, [MarshalAs(UnmanagedType.Bool)] bool fReadWrite, [MarshalAs(UnmanagedType.IUnknown)] object punkCreateObject, [In, MarshalAs(UnmanagedType.LPStruct)] Guid riid, [MarshalAs(UnmanagedType.Interface)] out object ppv); - /// Gets a value from serialized property storage by property name.Type: PCUSERIALIZEDPROPSTORAGEA pointer to an allocated buffer that contains the serialized properties. Call IPersistSerializedPropStorage::GetPropertyStorage to obtain the buffer.Type: DWORDThe size, in bytes, of the USERIALIZESPROPSTORAGE buffer pointed to by psps.Type: LPCWSTRA pointer to a null-terminated, Unicode string that contains the name of the property.Type: PROPVARIANT*When this function returns, contains the requested value.Type: PSSTDAPIReturns S_OK if successful, or an error value otherwise.This function is intended to be called if the calling application already has a serialized property storage and needs no more than a few properties from storage. If many properties need to be retrieved, performance can be enhanced by creating a memory property store by calling PSCreateMemoryPropertyStore, initializing the property store by calling IPersistSerializedPropStorage::SetPropertyStorage, and using INamedPropertyStore or IPropertyStore to retrieve the properties.Note that PSGetNamedPropertyFromPropertyStorage works only on serialized buffers created by the system implementation of IPersistSerializedPropStorage. You must first obtain a memory property store by calling PSCreateMemoryPropertyStore; that store can then create a serialized buffer using the IPersistSerializedPropStorage interface.Although SERIALIZEDPROPSTORAGE is an opaque serialized data structure whose format may change in the future, earlier formats will be supported on subsequent versions of Windows. Because the format is opaque, applications should use supported property storage APIs to access and manipulate the serialized buffer (see IPersistSerializedPropStorage and PSGetPropertyFromPropertyStorage).ExamplesThe following example, to be included as part of a larger program, demonstrates how to use PSGetNamedPropertyFromPropertyStorage to read a value from serialized property storage. - // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-psgetnamedpropertyfrompropertystorage - // PSSTDAPI PSGetNamedPropertyFromPropertyStorage( PCUSERIALIZEDPROPSTORAGE psps, DWORD cb, LPCWSTR pszName, PROPVARIANT *ppropvar ); + /// + /// Gets a value from serialized property storage by property name. + /// + /// + /// Type: PCUSERIALIZEDPROPSTORAGE + /// + /// A pointer to an allocated buffer that contains the serialized properties. Call IPersistSerializedPropStorage::GetPropertyStorage + /// to obtain the buffer. + /// + /// + /// + /// Type: DWORD + /// The size, in bytes, of the USERIALIZESPROPSTORAGE buffer pointed to by psps. + /// + /// + /// Type: LPCWSTR + /// A pointer to a null-terminated, Unicode string that contains the name of the property. + /// + /// + /// Type: PROPVARIANT* + /// When this function returns, contains the requested value. + /// + /// + /// Type: PSSTDAPI + /// Returns S_OK if successful, or an error value otherwise. + /// + /// + /// + /// This function is intended to be called if the calling application already has a serialized property storage and needs no more + /// than a few properties from storage. If many properties need to be retrieved, performance can be enhanced by creating a memory + /// property store by calling PSCreateMemoryPropertyStore, initializing the property store by calling + /// IPersistSerializedPropStorage::SetPropertyStorage, and using INamedPropertyStore or IPropertyStore to retrieve the properties. + /// + /// + /// Note that PSGetNamedPropertyFromPropertyStorage works only on serialized buffers created by the system implementation of + /// IPersistSerializedPropStorage. You must first obtain a memory property store by calling PSCreateMemoryPropertyStore; that store + /// can then create a serialized buffer using the IPersistSerializedPropStorage interface. + /// + /// + /// Although SERIALIZEDPROPSTORAGE is an opaque serialized data structure whose format may change in the future, earlier formats will + /// be supported on subsequent versions of Windows. Because the format is opaque, applications should use supported property storage + /// APIs to access and manipulate the serialized buffer (see IPersistSerializedPropStorage and PSGetPropertyFromPropertyStorage). + /// + /// Examples + /// + /// The following example, to be included as part of a larger program, demonstrates how to use PSGetNamedPropertyFromPropertyStorage + /// to read a value from serialized property storage. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-psgetnamedpropertyfrompropertystorage PSSTDAPI + // PSGetNamedPropertyFromPropertyStorage( PCUSERIALIZEDPROPSTORAGE psps, DWORD cb, LPCWSTR pszName, PROPVARIANT *ppropvar ); [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] [PInvokeData("propsys.h", MSDNShortId = "bb4eedc0-9ef5-46f2-83e5-340b77b3d876")] public static extern HRESULT PSGetNamedPropertyFromPropertyStorage(IntPtr psps, uint cb, [MarshalAs(UnmanagedType.LPWStr)] string pszName, PROPVARIANT ppropvar); - /// Gets an instance of a property description interface for a specified property name.Type: LPCWSTRA pointer to a null-terminated, Unicode string that identifies the property.Type: REFIIDReference to the interface ID of the requested property.Type: void**When this function returns, contains the interface pointer requested in riid. This is typically IPropertyDescription, IPropertyDescriptionAliasInfo, or IPropertyDescriptionSearchInfo.Type: PSSTDAPIReturns one of the following values.Return codeDescription S_OK The interface was obtained. E_INVALIDARG The pszCanonicalName parameter is NULL. TYPE_E_ELEMENTNOTFOUND The canonical name does not exist in the schema subsystem cache.It is recommended that you use the IID_PPV_ARGS macro, defined in objbase.h, to package the riid and ppv parameters. This macro provides the correct IID based on the interface pointed to by the value in ppv, eliminating the possibility of a coding error.We recommend that pszCanonicalName point to the canonical name of a property, for example, . The canonical name is case sensitive.In addition to the new canonical names, callers can pass a legacy name for a property. The following table contains the complete list of supported legacy names and the canonical names they correspond to.Property nameMaps to propertyAccessSystem.DateAccessedAlbumSystem.Music.AlbumTitleAllocSizeSystem.FileAllocationSizeApertureSystem.Photo.ApertureArtistSystem.Music.ArtistAttribSystem.FileAttributesAttributesSystem.FileAttributesAttributesDescriptionSystem.FileAttributesDisplayAudio FormatSystem.Audio.FormatAudio Sample SizeSystem.Audio.SampleSizeBitDepthSystem.Image.BitDepthBitrateSystem.Audio.EncodingBitrateCameraModelSystem.Photo.CameraModelCapacitySystem.CapacityChannelsSystem.Audio.ChannelCountColorSpaceSystem.Image.ColorSpaceCompanySystem.CompanyCompressionSystem.Video.CompressionCompressionSystem.Video.CompressionCopyrightSystem.CopyrightCopyrightSystem.CopyrightCopyrightSystem.Image.CopyrightCreateSystem.DateCreatedCSCStatusSystem.OfflineStatusData RateSystem.Video.EncodingBitrateDateDeletedSystem.Recycle.DateDeletedDeletedFromSystem.Recycle.DeletedFromDimensionsSystem.Image.DimensionsDirectorySystem.ItemFolderNameDisplayDistanceSystem.Photo.SubjectDistanceDocAppNameSystem.ApplicationNameDocAuthorSystem.AuthorDocByteCountSystem.Document.ByteCountDocCategorySystem.CategoryDocCharCountSystem.Document.CharacterCountDocCommentsSystem.CommentDocCompanySystem.CompanyDocCreatedTmSystem.Document.DateCreatedDocEditTimeSystem.Document.TotalEditingTimeDocHiddenCountSystem.Document.HiddenSlideCountDocKeywordsSystem.KeywordsDocLastAuthorSystem.Document.LastAuthorDocLastPrintedSystem.Document.DatePrintedDocLastSavedTmSystem.Document.DateSavedDocLineCountSystem.Document.LineCountDocManagerSystem.Document.ManagerDocNoteCountSystem.Document.NoteCountDocPageCountSystem.Document.PageCountDocParaCountSystem.Document.ParagraphCountDocPresentationTargetSystem.Document.PresentationFormatDocRevNumberSystem.Document.RevisionNumberDocSlideCountSystem.Document.SlideCountDocSubjectSystem.SubjectDocTemplateSystem.Document.TemplateDocTitleSystem.TitleDocWordCountSystem.Document.WordCountDRM DescriptionSystem.DRM.DescriptionDurationSystem.Media.DurationEquipMakeSystem.Photo.CameraManufacturerExposureBiasSystem.Photo.ExposureBiasExposureProgSystem.Photo.ExposureProgramExposureTimeSystem.Photo.ExposureTimeFaxCallerIDSystem.Fax.CallerIDFaxCSIDSystem.Fax.CSIDFaxRecipientNameSystem.Fax.RecipientNameFaxRecipientNumberSystem.Fax.RecipientNumberFaxRoutingSystem.Fax.RoutingFaxSenderNameSystem.Fax.SenderNameFaxTimeSystem.Fax.TimeFaxTSIDSystem.Fax.TSIDFileDescriptionSystem.FileDescriptionFileSystemSystem.Volume.FileSystemFileTypeSystem.Image.FileTypeFileVersionSystem.FileVersionFlashSystem.Photo.FlashFlashEnergySystem.Photo.FlashEnergyFNumberSystem.Photo.FNumberFocalLengthSystem.Photo.FocalLengthFrame RateSystem.Video.FrameRateFrameCountSystem.Media.FrameCountFreeSpaceSystem.FreeSpaceGenreSystem.Music.GenreImageXSystem.Image.HorizontalSizeImageYSystem.Image.VerticalSizeISOSpeedSystem.Photo.ISOSpeedLightSourceSystem.Photo.LightSourceLinksUpToDateSystem.Document.LinksDirtyLinkTargetSystem.Link.TargetParsingPathLyricsSystem.Music.LyricsManagerSystem.Document.ManagerMeteringModeSystem.Photo.MeteringModeMMClipCountSystem.Document.MultimediaClipCountNameSystem.ItemNameDisplayOwnerSystem.FileOwnerPlay CountSystem.DRM.PlayCountPlay ExpiresSystem.DRM.DatePlayExpiresPlay StartsSystem.DRM.DatePlayStartsPresentationTargetSystem.Document.PresentationFormatProductNameSystem.Software.ProductNameProductVersionSystem.Software.ProductVersionProjectSystem.Media.ProjectProtectedSystem.DRM.IsProtectedRankSystem.Search.RankRatingSystem.RatingResolutionXSystem.Image.HorizontalResolutionResolutionYSystem.Image.VerticalResolutionSample RateSystem.Audio.SampleRateScaleSystem.Document.ScaleShutterSpeedSystem.Photo.ShutterSpeedSizeSystem.SizeSoftwareSystem.SoftwareUsedStatusSystem.Media.StatusStatusSystem.StatusStream NameSystem.Video.StreamNameSyncCopyInSystem.Sync.CopyInTrackSystem.Music.TrackNumberTypeSystem.ItemTypeTextVideo Sample SizeSystem.Video.SampleSizeWhenTakenSystem.Photo.DateTakenWriteSystem.DateModifiedYearSystem.Media.YearExamplesThe following example, to be included as part of a larger program, demonstrates how to use PSGetPropertyDescriptionByName to retrieve the description for the ratings property. - // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-psgetpropertydescriptionbyname - // PSSTDAPI PSGetPropertyDescriptionByName( LPCWSTR pszCanonicalName, REFIID riid, void **ppv ); + /// Retrieves the property's canonical name given its PROPERTYKEY. + /// A pointer to a PROPERTYKEY structure containing the property's identifiers. + /// + /// The address of a pointer to a buffer that receives the property name as a null-terminated Unicode string. + /// + /// The result of the operation. S_OK indicates success. + [DllImport(Lib.PropSys, ExactSpelling = true)] + [PInvokeData("Propsys.h", MSDNShortId = "bb776502")] + public static extern HRESULT PSGetNameFromPropertyKey([In, MarshalAs(UnmanagedType.LPStruct)] PROPERTYKEY propkey, [MarshalAs(UnmanagedType.CustomMarshaler, MarshalTypeRef = typeof(CoTaskMemStringMarshaler))] out string ppszCanonicalName); + + /// Gets an instance of a property description interface for a property specified by a PROPERTYKEY structure. + /// Reference to a PROPERTYKEY. + /// Reference to the interface ID of the requested interface. + /// + /// When this function returns, contains the interface pointer requested in riid. This is typically IPropertyDescription, + /// IPropertyDescriptionAliasInfo, or IPropertyDescriptionSearchInfo. + /// + /// The result of the operation. S_OK indicates success. + [DllImport(Lib.PropSys, ExactSpelling = true)] + [PInvokeData("Propsys.h", MSDNShortId = "bb776503")] + public static extern HRESULT PSGetPropertyDescription([In, MarshalAs(UnmanagedType.LPStruct)] PROPERTYKEY propkey, [MarshalAs(UnmanagedType.LPStruct)] Guid riid, [MarshalAs(UnmanagedType.Interface)] out object ppv); + + /// + /// Gets an instance of a property description interface for a specified property name. + /// + /// + /// Type: LPCWSTR + /// A pointer to a null-terminated, Unicode string that identifies the property. + /// + /// + /// Type: REFIID + /// Reference to the interface ID of the requested property. + /// + /// + /// Type: void** + /// + /// When this function returns, contains the interface pointer requested in riid. This is typically IPropertyDescription, + /// IPropertyDescriptionAliasInfo, or IPropertyDescriptionSearchInfo. + /// + /// + /// + /// Type: PSSTDAPI + /// Returns one of the following values. + /// + /// + /// Return code + /// Description + /// + /// + /// S_OK + /// The interface was obtained. + /// + /// + /// E_INVALIDARG + /// The pszCanonicalName parameter is NULL. + /// + /// + /// TYPE_E_ELEMENTNOTFOUND + /// The canonical name does not exist in the schema subsystem cache. + /// + /// + /// + /// + /// + /// It is recommended that you use the IID_PPV_ARGS macro, defined in objbase.h, to package the riid and ppv parameters. This macro + /// provides the correct IID based on the interface pointed to by the value in ppv, eliminating the possibility of a coding error. + /// + /// + /// We recommend that pszCanonicalName point to the canonical name of a property, for example, . The canonical name is case sensitive. + /// + /// + /// In addition to the new canonical names, callers can pass a legacy name for a property. The following table contains the complete + /// list of supported legacy names and the canonical names they correspond to. + /// + /// + /// + /// Property name + /// Maps to property + /// + /// + /// Access + /// System.DateAccessed + /// + /// + /// Album + /// System.Music.AlbumTitle + /// + /// + /// AllocSize + /// System.FileAllocationSize + /// + /// + /// Aperture + /// System.Photo.Aperture + /// + /// + /// Artist + /// System.Music.Artist + /// + /// + /// Attrib + /// System.FileAttributes + /// + /// + /// Attributes + /// System.FileAttributes + /// + /// + /// AttributesDescription + /// System.FileAttributesDisplay + /// + /// + /// Audio Format + /// System.Audio.Format + /// + /// + /// Audio Sample Size + /// System.Audio.SampleSize + /// + /// + /// BitDepth + /// System.Image.BitDepth + /// + /// + /// Bitrate + /// System.Audio.EncodingBitrate + /// + /// + /// CameraModel + /// System.Photo.CameraModel + /// + /// + /// Capacity + /// System.Capacity + /// + /// + /// Channels + /// System.Audio.ChannelCount + /// + /// + /// ColorSpace + /// System.Image.ColorSpace + /// + /// + /// Company + /// System.Company + /// + /// + /// Compression + /// System.Video.Compression + /// + /// + /// Compression + /// System.Video.Compression + /// + /// + /// Copyright + /// System.Copyright + /// + /// + /// Copyright + /// System.Copyright + /// + /// + /// Copyright + /// System.Image.Copyright + /// + /// + /// Create + /// System.DateCreated + /// + /// + /// CSCStatus + /// System.OfflineStatus + /// + /// + /// Data Rate + /// System.Video.EncodingBitrate + /// + /// + /// DateDeleted + /// System.Recycle.DateDeleted + /// + /// + /// DeletedFrom + /// System.Recycle.DeletedFrom + /// + /// + /// Dimensions + /// System.Image.Dimensions + /// + /// + /// Directory + /// System.ItemFolderNameDisplay + /// + /// + /// Distance + /// System.Photo.SubjectDistance + /// + /// + /// DocAppName + /// System.ApplicationName + /// + /// + /// DocAuthor + /// System.Author + /// + /// + /// DocByteCount + /// System.Document.ByteCount + /// + /// + /// DocCategory + /// System.Category + /// + /// + /// DocCharCount + /// System.Document.CharacterCount + /// + /// + /// DocComments + /// System.Comment + /// + /// + /// DocCompany + /// System.Company + /// + /// + /// DocCreatedTm + /// System.Document.DateCreated + /// + /// + /// DocEditTime + /// System.Document.TotalEditingTime + /// + /// + /// DocHiddenCount + /// System.Document.HiddenSlideCount + /// + /// + /// DocKeywords + /// System.Keywords + /// + /// + /// DocLastAuthor + /// System.Document.LastAuthor + /// + /// + /// DocLastPrinted + /// System.Document.DatePrinted + /// + /// + /// DocLastSavedTm + /// System.Document.DateSaved + /// + /// + /// DocLineCount + /// System.Document.LineCount + /// + /// + /// DocManager + /// System.Document.Manager + /// + /// + /// DocNoteCount + /// System.Document.NoteCount + /// + /// + /// DocPageCount + /// System.Document.PageCount + /// + /// + /// DocParaCount + /// System.Document.ParagraphCount + /// + /// + /// DocPresentationTarget + /// System.Document.PresentationFormat + /// + /// + /// DocRevNumber + /// System.Document.RevisionNumber + /// + /// + /// DocSlideCount + /// System.Document.SlideCount + /// + /// + /// DocSubject + /// System.Subject + /// + /// + /// DocTemplate + /// System.Document.Template + /// + /// + /// DocTitle + /// System.Title + /// + /// + /// DocWordCount + /// System.Document.WordCount + /// + /// + /// DRM Description + /// System.DRM.Description + /// + /// + /// Duration + /// System.Media.Duration + /// + /// + /// EquipMake + /// System.Photo.CameraManufacturer + /// + /// + /// ExposureBias + /// System.Photo.ExposureBias + /// + /// + /// ExposureProg + /// System.Photo.ExposureProgram + /// + /// + /// ExposureTime + /// System.Photo.ExposureTime + /// + /// + /// FaxCallerID + /// System.Fax.CallerID + /// + /// + /// FaxCSID + /// System.Fax.CSID + /// + /// + /// FaxRecipientName + /// System.Fax.RecipientName + /// + /// + /// FaxRecipientNumber + /// System.Fax.RecipientNumber + /// + /// + /// FaxRouting + /// System.Fax.Routing + /// + /// + /// FaxSenderName + /// System.Fax.SenderName + /// + /// + /// FaxTime + /// System.Fax.Time + /// + /// + /// FaxTSID + /// System.Fax.TSID + /// + /// + /// FileDescription + /// System.FileDescription + /// + /// + /// FileSystem + /// System.Volume.FileSystem + /// + /// + /// FileType + /// System.Image.FileType + /// + /// + /// FileVersion + /// System.FileVersion + /// + /// + /// Flash + /// System.Photo.Flash + /// + /// + /// FlashEnergy + /// System.Photo.FlashEnergy + /// + /// + /// FNumber + /// System.Photo.FNumber + /// + /// + /// FocalLength + /// System.Photo.FocalLength + /// + /// + /// Frame Rate + /// System.Video.FrameRate + /// + /// + /// FrameCount + /// System.Media.FrameCount + /// + /// + /// FreeSpace + /// System.FreeSpace + /// + /// + /// Genre + /// System.Music.Genre + /// + /// + /// ImageX + /// System.Image.HorizontalSize + /// + /// + /// ImageY + /// System.Image.VerticalSize + /// + /// + /// ISOSpeed + /// System.Photo.ISOSpeed + /// + /// + /// LightSource + /// System.Photo.LightSource + /// + /// + /// LinksUpToDate + /// System.Document.LinksDirty + /// + /// + /// LinkTarget + /// System.Link.TargetParsingPath + /// + /// + /// Lyrics + /// System.Music.Lyrics + /// + /// + /// Manager + /// System.Document.Manager + /// + /// + /// MeteringMode + /// System.Photo.MeteringMode + /// + /// + /// MMClipCount + /// System.Document.MultimediaClipCount + /// + /// + /// Name + /// System.ItemNameDisplay + /// + /// + /// Owner + /// System.FileOwner + /// + /// + /// Play Count + /// System.DRM.PlayCount + /// + /// + /// Play Expires + /// System.DRM.DatePlayExpires + /// + /// + /// Play Starts + /// System.DRM.DatePlayStarts + /// + /// + /// PresentationTarget + /// System.Document.PresentationFormat + /// + /// + /// ProductName + /// System.Software.ProductName + /// + /// + /// ProductVersion + /// System.Software.ProductVersion + /// + /// + /// Project + /// System.Media.Project + /// + /// + /// Protected + /// System.DRM.IsProtected + /// + /// + /// Rank + /// System.Search.Rank + /// + /// + /// Rating + /// System.Rating + /// + /// + /// ResolutionX + /// System.Image.HorizontalResolution + /// + /// + /// ResolutionY + /// System.Image.VerticalResolution + /// + /// + /// Sample Rate + /// System.Audio.SampleRate + /// + /// + /// Scale + /// System.Document.Scale + /// + /// + /// ShutterSpeed + /// System.Photo.ShutterSpeed + /// + /// + /// Size + /// System.Size + /// + /// + /// Software + /// System.SoftwareUsed + /// + /// + /// Status + /// System.Media.Status + /// + /// + /// Status + /// System.Status + /// + /// + /// Stream Name + /// System.Video.StreamName + /// + /// + /// SyncCopyIn + /// System.Sync.CopyIn + /// + /// + /// Track + /// System.Music.TrackNumber + /// + /// + /// Type + /// System.ItemTypeText + /// + /// + /// Video Sample Size + /// System.Video.SampleSize + /// + /// + /// WhenTaken + /// System.Photo.DateTaken + /// + /// + /// Write + /// System.DateModified + /// + /// + /// Year + /// System.Media.Year + /// + /// + /// Examples + /// + /// The following example, to be included as part of a larger program, demonstrates how to use PSGetPropertyDescriptionByName to + /// retrieve the description for the ratings property. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-psgetpropertydescriptionbyname PSSTDAPI + // PSGetPropertyDescriptionByName( LPCWSTR pszCanonicalName, REFIID riid, void **ppv ); [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] [PInvokeData("propsys.h", MSDNShortId = "181ebbfb-66ed-4763-ad2d-acf3c800f9d2")] public static extern HRESULT PSGetPropertyDescriptionByName([MarshalAs(UnmanagedType.LPWStr)] string pszCanonicalName, [In, MarshalAs(UnmanagedType.LPStruct)] Guid riid, [MarshalAs(UnmanagedType.Interface)] out object ppv); - /// Gets an instance of a property description list interface for a specified property list.Type: LPCWSTRPointer to a null-terminated, Unicode string that identifies the property list. See IPropertySystem::GetPropertyDescriptionListFromString for more information about the format of this parameter.Type: REFIIDReference to the interface ID of the requested interface.Type: void**When this function returns, contains the interface pointer requested in riid. This is typically IPropertyDescriptionList.Type: PSSTDAPIReturns one of the following values.Return codeDescription S_OK The interface was obtained. E_INVALIDARG The ppv parameter is NULL. This function calls the property subsystem implementation of IPropertySystem::GetPropertyDescriptionListFromString to obtain a collection of properties provided as a semicolon-delimited property list string.We recommend that you use the IID_PPV_ARGS macro, defined in Objbase.h, to package the riid and ppv parameters. This macro provides the correct IID based on the interface pointed to by the value in ppv, which eliminates the possibility of a coding error.For more information about property schemas, see Property Schemas.ExamplesThe following example, to be included as part of a larger program, demonstrates how to use PSGetPropertyDescriptionListFromString. - // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-psgetpropertydescriptionlistfromstring - // PSSTDAPI PSGetPropertyDescriptionListFromString( LPCWSTR pszPropList, REFIID riid, void **ppv ); + /// + /// Gets an instance of a property description list interface for a specified property list. + /// + /// + /// Type: LPCWSTR + /// + /// Pointer to a null-terminated, Unicode string that identifies the property list. See + /// IPropertySystem::GetPropertyDescriptionListFromString for more information about the format of this parameter. + /// + /// + /// + /// Type: REFIID + /// Reference to the interface ID of the requested interface. + /// + /// + /// Type: void** + /// When this function returns, contains the interface pointer requested in riid. This is typically IPropertyDescriptionList. + /// + /// + /// Type: PSSTDAPI + /// Returns one of the following values. + /// + /// + /// Return code + /// Description + /// + /// + /// S_OK + /// The interface was obtained. + /// + /// + /// E_INVALIDARG + /// The ppv parameter is NULL. + /// + /// + /// + /// + /// + /// This function calls the property subsystem implementation of IPropertySystem::GetPropertyDescriptionListFromString to obtain a + /// collection of properties provided as a semicolon-delimited property list string. + /// + /// + /// We recommend that you use the IID_PPV_ARGS macro, defined in Objbase.h, to package the riid and ppv parameters. This macro + /// provides the correct IID based on the interface pointed to by the value in ppv, which eliminates the possibility of a coding error. + /// + /// For more information about property schemas, see Property Schemas. + /// Examples + /// The following example, to be included as part of a larger program, demonstrates how to use PSGetPropertyDescriptionListFromString. + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-psgetpropertydescriptionlistfromstring PSSTDAPI + // PSGetPropertyDescriptionListFromString( LPCWSTR pszPropList, REFIID riid, void **ppv ); [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] [PInvokeData("propsys.h", MSDNShortId = "348253ed-46ac-4643-bbf8-2d286ae97f07")] - public static extern HRESULT PSGetPropertyDescriptionListFromString([MarshalAs(UnmanagedType.LPWStr)] string pszPropList, [In, MarshalAs(UnmanagedType.LPStruct)] Guid riid, [MarshalAs(UnmanagedType.Interface)] out object ppv); + public static extern HRESULT PSGetPropertyDescriptionListFromString([MarshalAs(UnmanagedType.LPWStr)] string pszPropList, [In, MarshalAs(UnmanagedType.LPStruct)] Guid riid, out IPropertyDescriptionList ppv); - /// Gets the value of a property as stored in serialized property storage.Type: PCUSERIALIZEDPROPSTORAGEPointer to an allocated buffer that contains the serialized properties. This buffer is obtained by a call to IPersistSerializedPropStorage::GetPropertyStorage.Type: DWORDThe size, in bytes, of the USERIALIZESPROPSTORAGE buffer pointed to by psps.Type: REFPROPERTYKEYReference to the PROPERTYKEY that identifies the property for which to get the value.Type: PROPVARIANT**When this function returns, contains the requested value.Type: PSSTDAPIReturns S_OK if successful, or an error value otherwise.This function is intended to be called if the calling application already has a serialized property storage and needs no more than a few properties from storage. If many properties need to be retrieved, performance can be enhanced by creating a memory property store through PSCreateMemoryPropertyStore, initializing the property store by calling IPersistSerializedPropStorage::SetPropertyStorage, and by using IPropertyStore to retrieve the properties.Note that PSGetPropertyFromPropertyStorage works only on serialized buffers created by the system implementation of IPersistSerializedPropStorage. You must first obtain a memory property store by calling PSCreateMemoryPropertyStore. That store can then create a serialized buffer using the IPersistSerializedPropStorage interface.Although SERIALIZEDPROPSTORAGE is an opaque serialized data structure whose format may change in the future, earlier formats will be supported on subsequent versions of Windows. Because the format is opaque, applications should use supported property storage APIs to access and manipulate the serialized buffer (see IPersistSerializedPropStorage).ExamplesThe following example, to be included as part of a larger program, demonstrates how to use PSGetPropertyFromPropertyStorage to read a value from serialized property storage. - // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-psgetpropertyfrompropertystorage - // PSSTDAPI PSGetPropertyFromPropertyStorage( PCUSERIALIZEDPROPSTORAGE psps, DWORD cb, REFPROPERTYKEY rpkey, PROPVARIANT *ppropvar ); + /// + /// Gets the value of a property as stored in serialized property storage. + /// + /// + /// Type: PCUSERIALIZEDPROPSTORAGE + /// Pointer to an allocated buffer that contains the serialized properties. This buffer is obtained by a call to IPersistSerializedPropStorage::GetPropertyStorage. + /// + /// + /// Type: DWORD + /// The size, in bytes, of the USERIALIZESPROPSTORAGE buffer pointed to by psps. + /// + /// + /// Type: REFPROPERTYKEY + /// Reference to the PROPERTYKEY that identifies the property for which to get the value. + /// + /// + /// Type: PROPVARIANT** + /// When this function returns, contains the requested value. + /// + /// + /// Type: PSSTDAPI + /// Returns S_OK if successful, or an error value otherwise. + /// + /// + /// + /// This function is intended to be called if the calling application already has a serialized property storage and needs no more + /// than a few properties from storage. If many properties need to be retrieved, performance can be enhanced by creating a memory + /// property store through PSCreateMemoryPropertyStore, initializing the property store by calling + /// IPersistSerializedPropStorage::SetPropertyStorage, and by using IPropertyStore to retrieve the properties. + /// + /// + /// Note that PSGetPropertyFromPropertyStorage works only on serialized buffers created by the system implementation of + /// IPersistSerializedPropStorage. You must first obtain a memory property store by calling PSCreateMemoryPropertyStore. That store + /// can then create a serialized buffer using the IPersistSerializedPropStorage interface. + /// + /// + /// Although SERIALIZEDPROPSTORAGE is an opaque serialized data structure whose format may change in the future, earlier formats will + /// be supported on subsequent versions of Windows. Because the format is opaque, applications should use supported property storage + /// APIs to access and manipulate the serialized buffer (see IPersistSerializedPropStorage). + /// + /// Examples + /// + /// The following example, to be included as part of a larger program, demonstrates how to use PSGetPropertyFromPropertyStorage to + /// read a value from serialized property storage. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-psgetpropertyfrompropertystorage PSSTDAPI + // PSGetPropertyFromPropertyStorage( PCUSERIALIZEDPROPSTORAGE psps, DWORD cb, REFPROPERTYKEY rpkey, PROPVARIANT *ppropvar ); [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] [PInvokeData("propsys.h", MSDNShortId = "c649d25d-7971-4804-a5a2-3fd6860659b4")] public static extern HRESULT PSGetPropertyFromPropertyStorage(IntPtr psps, uint cb, [In, MarshalAs(UnmanagedType.LPStruct)] PROPERTYKEY rpkey, PROPVARIANT ppropvar); - /// Gets an instance of the subsystem object that implements IPropertySystem.Type: REFIIDReference to the IID of the requested interface.Type: void**When this function returns, contains the interface pointer requested in riid. This is typically IPropertySystem.Type: PSSTDAPIReturns one of the following values.Return codeDescription S_OK The interface was obtained. E_INVALIDARG The ppv parameter is NULL. You must initialize Component Object Model (COM) with CoInitialize or OleInitialize prior to calling PSGetPropertySystem. COM must remain initialized for the lifetime of this object. The property system object aggregates the free-threaded marshaller and is thread-safe.We recommend that you use the IID_PPV_ARGS macro defined in Objbase.h to package the riid and ppv parameters. This macro provides the correct IID based on the interface pointed to by the value in ppv, which eliminates the possibility of a coding error.ExamplesThe following example, to be included as part of a larger program, demonstrates how to use PSGetPropertySystem. - // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-psgetpropertysystem - // PSSTDAPI PSGetPropertySystem( REFIID riid, void **ppv ); + /// Gets the property key for a canonical property name. + /// Pointer to a property name as a null-terminated, Unicode string. + /// When this function returns, contains the requested property key. + /// The result of the operation. S_OK indicates success. + [DllImport(Lib.PropSys, ExactSpelling = true)] + [PInvokeData("Propsys.h", MSDNShortId = "bb762081")] + public static extern HRESULT PSGetPropertyKeyFromName([MarshalAs(UnmanagedType.LPWStr)] string pszName, out PROPERTYKEY ppropkey); + + /// + /// Gets an instance of the subsystem object that implements IPropertySystem. + /// + /// + /// Type: REFIID + /// Reference to the IID of the requested interface. + /// + /// + /// Type: void** + /// When this function returns, contains the interface pointer requested in riid. This is typically IPropertySystem. + /// + /// + /// Type: PSSTDAPI + /// Returns one of the following values. + /// + /// + /// Return code + /// Description + /// + /// + /// S_OK + /// The interface was obtained. + /// + /// + /// E_INVALIDARG + /// The ppv parameter is NULL. + /// + /// + /// + /// + /// + /// You must initialize Component Object Model (COM) with CoInitialize or OleInitialize prior to calling PSGetPropertySystem. COM + /// must remain initialized for the lifetime of this object. The property system object aggregates the free-threaded marshaller and + /// is thread-safe. + /// + /// + /// We recommend that you use the IID_PPV_ARGS macro defined in Objbase.h to package the riid and ppv parameters. This macro provides + /// the correct IID based on the interface pointed to by the value in ppv, which eliminates the possibility of a coding error. + /// + /// Examples + /// The following example, to be included as part of a larger program, demonstrates how to use PSGetPropertySystem. + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-psgetpropertysystem PSSTDAPI PSGetPropertySystem( REFIID + // riid, void **ppv ); [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] [PInvokeData("propsys.h", MSDNShortId = "ddbf7cea-b22f-4cf9-8b5f-804640086466")] - public static extern HRESULT PSGetPropertySystem([In, MarshalAs(UnmanagedType.LPStruct)] Guid riid, [MarshalAs(UnmanagedType.Interface)] out object ppv); + public static extern HRESULT PSGetPropertySystem([In, MarshalAs(UnmanagedType.LPStruct)] Guid riid, out IPropertySystem ppv); - /// Gets a property value from a property store.Type: IPropertyStore*Pointer to an instance of the IPropertyStore interface, which represents the property store from which to get the value.Type: IPropertyDescription*Pointer to an instance of the IPropertyDescription interface, which represents the property in the property store.Type: PROPVARIANT*Pointer to an uninitialized PROPVARIANT structure. When this function returns, points to the requested property value.Type: HRESULTIf this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.This helper function is used to read a property value from a store. If the calling code already has a PROPERTYKEY structure, it might be simpler to call IPropertyStore::GetValue directly.ExamplesThe following example, to be included as part of a larger program, demonstrates how to use PSGetPropertyValue. - // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-psgetpropertyvalue - // PSSTDAPI PSGetPropertyValue( IPropertyStore *pps, IPropertyDescription *ppd, PROPVARIANT *ppropvar ); + /// + /// Gets a property value from a property store. + /// + /// + /// Type: IPropertyStore* + /// Pointer to an instance of the IPropertyStore interface, which represents the property store from which to get the value. + /// + /// + /// Type: IPropertyDescription* + /// Pointer to an instance of the IPropertyDescription interface, which represents the property in the property store. + /// + /// + /// Type: PROPVARIANT* + /// Pointer to an uninitialized PROPVARIANT structure. When this function returns, points to the requested property value. + /// + /// + /// Type: HRESULT + /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. + /// + /// + /// + /// This helper function is used to read a property value from a store. If the calling code already has a PROPERTYKEY structure, it + /// might be simpler to call IPropertyStore::GetValue directly. + /// + /// Examples + /// The following example, to be included as part of a larger program, demonstrates how to use PSGetPropertyValue. + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-psgetpropertyvalue PSSTDAPI PSGetPropertyValue( + // IPropertyStore *pps, IPropertyDescription *ppd, PROPVARIANT *ppropvar ); [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] [PInvokeData("propsys.h", MSDNShortId = "9369dc85-b006-4b30-a25e-58d53b76f334")] public static extern HRESULT PSGetPropertyValue(IPropertyStore pps, IPropertyDescription ppd, PROPVARIANT ppropvar); - /// Gets the class identifier (CLSID) of a per-computer, registered file property handler.Type: PCWSTRPointer to a null-terminated, Unicode buffer that contains the absolute path of the file whose property handler CLSID is requested.Type: CLSID*When this function returns, contains the requested property handler CLSID.Type: PSSTDAPIReturns S_OK if successful, or an error value otherwise.For information on how to register your handler, see Initializing Property Handlers.This function returns only those handlers registered under HKEY_LOCAL_MACHINE.Most calling applications should not need to call this method or use CoCreateInstance to create a property handler directly. Instead, calling applications should use IShellItem2::GetPropertyStore to create a property store for a Shell item on Windows Vista. IShellItem2::GetPropertyStore provides the largest set of available properties for a Shell item, and the most options for customizing exactly which properties to return.If no property handler is registered for the specified file, this function returns an error code. When this happens, it might still be possible to read certain file system properties from the property store returned from IShellItem2::GetPropertyStore.Applications that need to create a property handler from code and that must run both on Windows Vista and on Windows XP can call PSGetItemPropertyHandler to create a property store for a Shell item through the Microsoft Windows Desktop Search (WDS) redistributable.ExamplesThe following example, to be included as part of a larger program, demonstrates how to use PSLookupPropertyHandlerCLSID. - // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-pslookuppropertyhandlerclsid - // PSSTDAPI PSLookupPropertyHandlerCLSID( PCWSTR pszFilePath, CLSID *pclsid ); + /// + /// Gets the class identifier (CLSID) of a per-computer, registered file property handler. + /// + /// + /// Type: PCWSTR + /// + /// Pointer to a null-terminated, Unicode buffer that contains the absolute path of the file whose property handler CLSID is requested. + /// + /// + /// + /// Type: CLSID* + /// When this function returns, contains the requested property handler CLSID. + /// + /// + /// Type: PSSTDAPI + /// Returns S_OK if successful, or an error value otherwise. + /// + /// + /// For information on how to register your handler, see Initializing Property Handlers. + /// This function returns only those handlers registered under HKEY_LOCAL_MACHINE. + /// + /// Most calling applications should not need to call this method or use CoCreateInstance to create a property handler directly. + /// Instead, calling applications should use IShellItem2::GetPropertyStore to create a property store for a Shell item on Windows + /// Vista. IShellItem2::GetPropertyStore provides the largest set of available properties for a Shell item, and the most + /// options for customizing exactly which properties to return. + /// + /// + /// If no property handler is registered for the specified file, this function returns an error code. When this happens, it might + /// still be possible to read certain file system properties from the property store returned from IShellItem2::GetPropertyStore. + /// + /// + /// Applications that need to create a property handler from code and that must run both on Windows Vista and on Windows XP can call + /// PSGetItemPropertyHandler to create a property store for a Shell item through the Microsoft Windows Desktop Search (WDS) redistributable. + /// + /// Examples + /// The following example, to be included as part of a larger program, demonstrates how to use PSLookupPropertyHandlerCLSID. + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-pslookuppropertyhandlerclsid PSSTDAPI + // PSLookupPropertyHandlerCLSID( PCWSTR pszFilePath, CLSID *pclsid ); [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] [PInvokeData("propsys.h", MSDNShortId = "43f90a33-9bd6-4e47-ab92-5e0d01ba268a")] public static extern HRESULT PSLookupPropertyHandlerCLSID([MarshalAs(UnmanagedType.LPWStr)] string pszFilePath, out Guid pclsid); - /// Converts a string to a PROPERTYKEY structure.Type: LPCWSTRPointer to a null-terminated, Unicode string to be converted.Type: PROPERTYKEY*When this function returns, contains a pointer to a PROPERTYKEY structure.Type: HRESULTIf this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.The string to be converted must be formatted as . For instance, the string that corresponds to is: . PSStringFromPropertyKey outputs strings in this format.This function succeeds for any valid property key string, even if the property does not exist in the property schema.ExamplesThe following example, to be included as part of a larger program, demonstrates how to use PSPropertyKeyFromString. - // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-pspropertykeyfromstring - // PSSTDAPI PSPropertyKeyFromString( LPCWSTR pszString, PROPERTYKEY *pkey ); + /// + /// Converts a string to a PROPERTYKEY structure. + /// + /// + /// Type: LPCWSTR + /// Pointer to a null-terminated, Unicode string to be converted. + /// + /// + /// Type: PROPERTYKEY* + /// When this function returns, contains a pointer to a PROPERTYKEY structure. + /// + /// + /// Type: HRESULT + /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. + /// + /// + /// + /// The string to be converted must be formatted as . For instance, the string that corresponds to is: . PSStringFromPropertyKey + /// outputs strings in this format. + /// + /// This function succeeds for any valid property key string, even if the property does not exist in the property schema. + /// Examples + /// The following example, to be included as part of a larger program, demonstrates how to use PSPropertyKeyFromString. + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-pspropertykeyfromstring PSSTDAPI PSPropertyKeyFromString( + // LPCWSTR pszString, PROPERTYKEY *pkey ); [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] [PInvokeData("propsys.h", MSDNShortId = "9096912a-14ad-4a45-a564-08f98fce3f96")] public static extern HRESULT PSPropertyKeyFromString([MarshalAs(UnmanagedType.LPWStr)] string pszString, out PROPERTYKEY pkey); - /// Not supported.It is valid to call this function, but it is not implemented to perform any function so there is no reason to do so.Type: HRESULTReturns one of the following values.Return codeDescription S_OK Schema files reloaded. E_ACCESSDENIED The calling context does not have proper privileges. - // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-psrefreshpropertyschema - // PSSTDAPI PSRefreshPropertySchema( ); + /// + /// Not supported. + /// It is valid to call this function, but it is not implemented to perform any function so there is no reason to do so. + /// + /// + /// Type: HRESULT + /// Returns one of the following values. + /// + /// + /// Return code + /// Description + /// + /// + /// S_OK + /// Schema files reloaded. + /// + /// + /// E_ACCESSDENIED + /// The calling context does not have proper privileges. + /// + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-psrefreshpropertyschema PSSTDAPI PSRefreshPropertySchema( ); [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] [PInvokeData("propsys.h", MSDNShortId = "07efbf66-3594-4b9d-b959-278dc9000572")] public static extern HRESULT PSRefreshPropertySchema(); - /// Informs the schema subsystem of the addition of a property description schema file.Type: PCWSTRPointer to the full file path, as a Unicode string, to the property description schema (.propdesc) file on the local machine. This can be either a fully-specified full path, or a full path that includes environment variables such as .Type: HRESULTReturns one of the following values.Return codeDescription S_OK All property descriptions in the schema were registered. E_ACCESSDENIED The calling context does not have proper privileges. INPLACE_S_TRUNCATED One or more property descriptions in the schema failed to register. The specific failures are logged in the application event log.This function is a wrapper API for the schema subsystem's implementation of IPropertySystem::RegisterPropertySchema. Call this function only when the file is first installed on the computer. Typically, a setup application calls this function after it installs the .propdesc file, which should be stored in the install directory of the application under Program Files. Multiple calls can be made to IPropertySystem::RegisterPropertySchema in order to register multiple schema files.When registering property schema files, remember that they can be read by processes running as different users. Therefore, it is important to place a schema file in a location that grants read access to all users on the machine. Similarly, use the absolute path to the file in this function's pszPath parameter.Note Because schemas are specific to the machine and cannot be registered for each individual user, registering a file path under user profiles is not supported on Windows Vista.If a full or partial failure is encountered that prevents a property description from being loaded, the cause is recorded in the application event log. This function fails with E_ACCESSDENIED if the calling context does not have proper privileges, which includes write access to HKEY_LOCAL_MACHINE. It is the responsibility of the calling application to obtain privileges through User Account Control (UAC) mechanisms. - // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-psregisterpropertyschema - // PSSTDAPI PSRegisterPropertySchema( PCWSTR pszPath ); + /// + /// Informs the schema subsystem of the addition of a property description schema file. + /// + /// + /// Type: PCWSTR + /// + /// Pointer to the full file path, as a Unicode string, to the property description schema (.propdesc) file on the local machine. + /// This can be either a fully-specified full path, or a full path that includes environment variables such as . + /// + /// + /// + /// Type: HRESULT + /// Returns one of the following values. + /// + /// + /// Return code + /// Description + /// + /// + /// S_OK + /// All property descriptions in the schema were registered. + /// + /// + /// E_ACCESSDENIED + /// The calling context does not have proper privileges. + /// + /// + /// INPLACE_S_TRUNCATED + /// + /// One or more property descriptions in the schema failed to register. The specific failures are logged in the application event log. + /// + /// + /// + /// + /// + /// + /// This function is a wrapper API for the schema subsystem's implementation of IPropertySystem::RegisterPropertySchema. Call this + /// function only when the file is first installed on the computer. Typically, a setup application calls this function after it + /// installs the .propdesc file, which should be stored in the install directory of the application under Program Files. Multiple + /// calls can be made to IPropertySystem::RegisterPropertySchema in order to register multiple schema files. + /// + /// + /// When registering property schema files, remember that they can be read by processes running as different users. Therefore, it is + /// important to place a schema file in a location that grants read access to all users on the machine. Similarly, use the absolute + /// path to the file in this function's pszPath parameter. + /// + /// + /// Note Because schemas are specific to the machine and cannot be registered for each individual user, registering a file + /// path under user profiles is not supported on Windows Vista. + /// + /// + /// If a full or partial failure is encountered that prevents a property description from being loaded, the cause is recorded in the + /// application event log. This function fails with E_ACCESSDENIED if the calling context does not have proper privileges, which + /// includes write access to HKEY_LOCAL_MACHINE. It is the responsibility of the calling application to obtain privileges through + /// User Account Control (UAC) mechanisms. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-psregisterpropertyschema PSSTDAPI + // PSRegisterPropertySchema( PCWSTR pszPath ); [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] [PInvokeData("propsys.h", MSDNShortId = "ea9c4361-fada-4b07-b450-dd0c6409745a")] public static extern HRESULT PSRegisterPropertySchema([MarshalAs(UnmanagedType.LPWStr)] string pszPath); - /// Sets the value of a property in a property store.Type: IPropertyStore*Pointer to an instance of the IPropertyStore interface, which represents the property store that contains the property.Type: IPropertyDescription*Pointer to an instance of the IPropertyDescription interface, which identifies the individual property.Type: REFPROPVARIANTReference to a PROPVARIANT structure that contains the new value.Type: HRESULTIf this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.This helper function is used to write a property value to a store. If the calling code already has a PROPERTYKEY structure, it might be simpler to call IPropertyStore::SetValue directly.ExamplesThe following example, to be included as part of a larger program, demonstrates how to use PSSetPropertyValue. - // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-pssetpropertyvalue - // PSSTDAPI PSSetPropertyValue( IPropertyStore *pps, IPropertyDescription *ppd, REFPROPVARIANT propvar ); + /// + /// Sets the value of a property in a property store. + /// + /// + /// Type: IPropertyStore* + /// Pointer to an instance of the IPropertyStore interface, which represents the property store that contains the property. + /// + /// + /// Type: IPropertyDescription* + /// Pointer to an instance of the IPropertyDescription interface, which identifies the individual property. + /// + /// + /// Type: REFPROPVARIANT + /// Reference to a PROPVARIANT structure that contains the new value. + /// + /// + /// Type: HRESULT + /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. + /// + /// + /// + /// This helper function is used to write a property value to a store. If the calling code already has a PROPERTYKEY structure, it + /// might be simpler to call IPropertyStore::SetValue directly. + /// + /// Examples + /// The following example, to be included as part of a larger program, demonstrates how to use PSSetPropertyValue. + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-pssetpropertyvalue PSSTDAPI PSSetPropertyValue( + // IPropertyStore *pps, IPropertyDescription *ppd, REFPROPVARIANT propvar ); [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] [PInvokeData("propsys.h", MSDNShortId = "b4f8c50d-93cd-4371-88b0-6ce58f023981")] public static extern HRESULT PSSetPropertyValue(IPropertyStore pps, IPropertyDescription ppd, PROPVARIANT propvar); - /// Creates a string that identifies a property from that property's key.Type: REFPROPERTYKEYReference to a PROPERTYKEY structure that identifies a property.Type: LPWSTRPointer to a buffer that receives the output string. The buffer should be large enough to contain PKEYSTR_MAX WCHARs.Type: UINTThe length of the buffer pointed to by psz, in WCHARs.Type: HRESULTIf this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.The string format retrieved is . For example, the output string for is .ExamplesThe following example, to be included as part of a larger program, demonstrates the use of PSPropertyKeyFromString. - // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-psstringfrompropertykey - // PSSTDAPI PSStringFromPropertyKey( REFPROPERTYKEY pkey, LPWSTR psz, UINT cch ); + /// + /// Creates a string that identifies a property from that property's key. + /// + /// + /// Type: REFPROPERTYKEY + /// Reference to a PROPERTYKEY structure that identifies a property. + /// + /// + /// Type: LPWSTR + /// Pointer to a buffer that receives the output string. The buffer should be large enough to contain PKEYSTR_MAX WCHARs. + /// + /// + /// Type: UINT + /// The length of the buffer pointed to by psz, in WCHARs. + /// + /// + /// Type: HRESULT + /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. + /// + /// + /// The string format retrieved is . For example, the output string for is . + /// Examples + /// The following example, to be included as part of a larger program, demonstrates the use of PSPropertyKeyFromString. + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-psstringfrompropertykey PSSTDAPI PSStringFromPropertyKey( + // REFPROPERTYKEY pkey, LPWSTR psz, UINT cch ); [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] [PInvokeData("propsys.h", MSDNShortId = "081f8e6d-9189-44f9-9b27-e85f4793da48")] public static extern HRESULT PSStringFromPropertyKey([In, MarshalAs(UnmanagedType.LPStruct)] PROPERTYKEY pkey, [MarshalAs(UnmanagedType.LPWStr)] StringBuilder psz, uint cch); - /// Informs the schema subsystem of the removal of a property description schema file.Type: PCWSTRPointer to the full file path, as a Unicode string, to the property description schema (.propdesc) file on the local machine. This can be either a fully-specified full path, or a full path that includes environment variables such as .Type: HRESULTReturns one of the following values.Return codeDescription S_OK The schema was unregistered. E_ACCESSDENIED The calling context does not have proper privileges.This function is a wrapper for the schema subsystem's implementation of IPropertySystem::UnregisterPropertySchema. Call this method when the file is being uninstalled from the computer. Typically, a setup application calls this method before or after uninstalling the .propdesc file. This method can be called after the file no longer exists.This function fails with a code of E_ACCESSDENIED if the calling context does not have proper privileges, which include write access to HKLM (HKEY_LOCAL_MACHINE). It is the responsibility of the calling application to obtain privileges through User Account Control (UAC) mechanisms. - // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-psunregisterpropertyschema - // PSSTDAPI PSUnregisterPropertySchema( PCWSTR pszPath ); + /// + /// Informs the schema subsystem of the removal of a property description schema file. + /// + /// + /// Type: PCWSTR + /// + /// Pointer to the full file path, as a Unicode string, to the property description schema (.propdesc) file on the local machine. + /// This can be either a fully-specified full path, or a full path that includes environment variables such as . + /// + /// + /// + /// Type: HRESULT + /// Returns one of the following values. + /// + /// + /// Return code + /// Description + /// + /// + /// S_OK + /// The schema was unregistered. + /// + /// + /// E_ACCESSDENIED + /// The calling context does not have proper privileges. + /// + /// + /// + /// + /// + /// This function is a wrapper for the schema subsystem's implementation of IPropertySystem::UnregisterPropertySchema. Call this + /// method when the file is being uninstalled from the computer. Typically, a setup application calls this method before or after + /// uninstalling the .propdesc file. This method can be called after the file no longer exists. + /// + /// + /// This function fails with a code of E_ACCESSDENIED if the calling context does not have proper privileges, which include write + /// access to HKLM (HKEY_LOCAL_MACHINE). It is the responsibility of the calling application to obtain privileges through User + /// Account Control (UAC) mechanisms. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propsys/nf-propsys-psunregisterpropertyschema PSSTDAPI + // PSUnregisterPropertySchema( PCWSTR pszPath ); [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] [PInvokeData("propsys.h", MSDNShortId = "57df82a9-8954-4c2b-b794-82ac542149e2")] public static extern HRESULT PSUnregisterPropertySchema([MarshalAs(UnmanagedType.LPWStr)] string pszPath);