From 00ba4639f087491e04035708491ad674ba511758 Mon Sep 17 00:00:00 2001 From: David Hall Date: Fri, 24 Aug 2018 13:14:24 -0600 Subject: [PATCH] Finished adding all PROVARIANT related functions --- PInvoke/Ole/PropSys/PropvarUtil.cs | 2249 +++++++++++++++++++++++++++++++++--- 1 file changed, 2115 insertions(+), 134 deletions(-) diff --git a/PInvoke/Ole/PropSys/PropvarUtil.cs b/PInvoke/Ole/PropSys/PropvarUtil.cs index d112ad2f..11de51df 100644 --- a/PInvoke/Ole/PropSys/PropvarUtil.cs +++ b/PInvoke/Ole/PropSys/PropvarUtil.cs @@ -1,9 +1,10 @@ using System; +using System.Linq; using System.Runtime.InteropServices; +using System.Text; using Vanara.InteropServices; using static Vanara.PInvoke.Ole32; using FILETIME = System.Runtime.InteropServices.ComTypes.FILETIME; -// ReSharper disable InconsistentNaming namespace Vanara.PInvoke { @@ -17,14 +18,19 @@ namespace Vanara.PInvoke { /// The PVCHF default PVCHF_DEFAULT = 0x00000000, + /// Maps to VARIANT_NOVALUEPROP for VariantChangeType PVCHF_NOVALUEPROP = 0x00000001, + /// Maps to VARIANT_ALPHABOOL for VariantChangeType PVCHF_ALPHABOOL = 0x00000002, + /// Maps to VARIANT_NOUSEROVERRIDE for VariantChangeType PVCHF_NOUSEROVERRIDE = 0x00000004, + /// Maps to VARIANT_LOCALBOOL for VariantChangeType PVCHF_LOCALBOOL = 0x00000008, + /// Don't convert a string that looks like hexadecimal (0xABCD) to the numerical equivalent. PVCHF_NOHEXSTRING = 0x00000010 } @@ -36,17 +42,26 @@ namespace Vanara.PInvoke { /// When comparing strings, use StrCmpLogical PVCF_DEFAULT = 0x00000000, + /// Empty/null values are greater-than non-empty values PVCF_TREATEMPTYASGREATERTHAN = 0x00000001, + /// When comparing strings, use StrCmp PVCF_USESTRCMP = 0x00000002, + /// When comparing strings, use StrCmpC PVCF_USESTRCMPC = 0x00000004, + /// When comparing strings, use StrCmpI PVCF_USESTRCMPI = 0x00000008, + /// When comparing strings, use StrCmpIC PVCF_USESTRCMPIC = 0x00000010, - /// When comparing strings, use CompareStringEx with LOCALE_NAME_USER_DEFAULT and SORT_DIGITSASNUMBERS. This corresponds to the linguistically correct order for UI lists. + + /// + /// When comparing strings, use CompareStringEx with LOCALE_NAME_USER_DEFAULT and SORT_DIGITSASNUMBERS. This corresponds to the + /// linguistically correct order for UI lists. + /// PVCF_DIGITSASNUMBERS_CASESENSITIVE = 0x00000020, } @@ -56,16 +71,22 @@ namespace Vanara.PInvoke { /// The default unit. PVCU_DEFAULT = 0, + /// The second comparison unit. PVCU_SECOND = 1, + /// The minute comparison unit. PVCU_MINUTE = 2, + /// The hour comparison unit. PVCU_HOUR = 3, + /// The day comparison unit. PVCU_DAY = 4, + /// The month comparison unit. PVCU_MONTH = 5, + /// The year comparison unit. PVCU_YEAR = 6 } @@ -76,14 +97,44 @@ namespace Vanara.PInvoke { /// Indicates the output will use coordinated universal time. PSTF_UTC = 0x00000000, + /// Indicates the output will use local time. PSTF_LOCAL = 0x00000001 } /// - /// Initializes a structure from a specified Boolean vector. + /// Frees the memory and references used by an array of PROPVARIANT structures stored in an array. /// - /// Pointer to the Boolean vector used to initialize the structure. If this parameter is NULL, the elements pointed to by the cabool.pElems structure member are initialized with VARIANT_FALSE. + /// + /// Type: PROPVARIANT* + /// Array of PROPVARIANT structures to free. + /// + /// + /// Type: UINT + /// The number of elements in the array specified by rgPropVar. + /// + /// + /// No return value. + /// + /// + /// + /// This function releases the memory and references held by each structure in the array before setting the structures to zero. + /// + /// This function performs the same action as FreePropVariantArray, but FreePropVariantArray returns an HRESULT. + /// Examples + /// The following example, to be included as part of a larger program, demonstrates how to use ClearPropVariantArray + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propvarutil/nf-propvarutil-clearpropvariantarray PSSTDAPI_(void) + // ClearPropVariantArray( PROPVARIANT *rgPropVar, UINT cVars ); + [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] + [PInvokeData("propvarutil.h", MSDNShortId = "e8d7f951-8a9e-441b-9fa7-bf21cf08c8ac")] + public static extern HRESULT ClearPropVariantArray([In, Out, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 1)] PROPVARIANT[] rgPropVar, uint cVars); + + /// Initializes a structure from a specified Boolean vector. + /// + /// Pointer to the Boolean vector used to initialize the structure. If this parameter is NULL, the elements pointed to by the + /// cabool.pElems structure member are initialized with VARIANT_FALSE. + /// /// The number of vector elements. /// When this function returns, contains the initialized structure. /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. @@ -91,9 +142,7 @@ namespace Vanara.PInvoke [PInvokeData("Propvarutil.h", MSDNShortId = "bb762288")] public static extern HRESULT InitPropVariantFromBooleanVector([In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 1, ArraySubType = UnmanagedType.Bool)] bool[] prgf, uint cElems, [In, Out] PROPVARIANT ppropvar); - /// - /// Initializes a structure using the contents of a buffer. - /// + /// Initializes a structure using the contents of a buffer. /// Pointer to the buffer. /// The length of the buffer, in bytes. /// When this function returns, contains the initialized structure. @@ -102,9 +151,7 @@ namespace Vanara.PInvoke [PInvokeData("Propvarutil.h", MSDNShortId = "bb762289")] public static extern HRESULT InitPropVariantFromBuffer([In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 1, ArraySubType = UnmanagedType.U1)] byte[] pv, uint cb, [In, Out] PROPVARIANT ppropvar); - /// - /// Initializes a structure based on a class identifier (CLSID). - /// + /// Initializes a structure based on a class identifier (CLSID). /// Reference to the CLSID. /// When this function returns, contains the initialized structure. /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. @@ -112,10 +159,11 @@ namespace Vanara.PInvoke [PInvokeData("Propvarutil.h", MSDNShortId = "bb762290")] public static extern HRESULT InitPropVariantFromCLSID([In, MarshalAs(UnmanagedType.LPStruct)] Guid clsid, [In, Out] PROPVARIANT ppropvar); - /// - /// Initializes a structure based on a specified vector of double values. - /// - /// Pointer to a double vector. If this value is NULL, the elements pointed to by the cadbl.pElems structure member are initialized with 0.0. + /// Initializes a structure based on a specified vector of double values. + /// + /// Pointer to a double vector. If this value is NULL, the elements pointed to by the cadbl.pElems structure member are initialized + /// with 0.0. + /// /// The number of vector elements. /// When this function returns, contains the initialized structure. /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. @@ -123,20 +171,19 @@ namespace Vanara.PInvoke [PInvokeData("Propvarutil.h", MSDNShortId = "bb762292")] public static extern HRESULT InitPropVariantFromDoubleVector([In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 1, ArraySubType = UnmanagedType.R8)] double[] prgn, uint cElems, [In, Out] PROPVARIANT ppropvar); - /// - /// Initializes a structure based on information stored in a structure. - /// - /// Pointer to the date and time as a structure. + /// Initializes a structure based on information stored in a structure. + /// Pointer to the date and time as a structure. /// When this function returns, contains the initialized structure. /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. [DllImport(Lib.PropSys, ExactSpelling = true)] [PInvokeData("Propvarutil.h", MSDNShortId = "bb762293")] public static extern HRESULT InitPropVariantFromFileTime([In] ref FILETIME pftIn, [In, Out] PROPVARIANT ppropvar); - /// - /// Initializes a structure from a specified vector of values. - /// - /// Pointer to the date and time as a vector. If this value is NULL, the elements pointed to by the cafiletime.pElems structure member is initialized with (FILETIME)0. + /// Initializes a structure from a specified vector of values. + /// + /// Pointer to the date and time as a vector. If this value is NULL, the elements pointed to by the + /// cafiletime.pElems structure member is initialized with (FILETIME)0. + /// /// The number of vector elements. /// When this function returns, contains the initialized structure. /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. @@ -145,8 +192,32 @@ namespace Vanara.PInvoke public static extern HRESULT InitPropVariantFromFileTimeVector([In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 1)] FILETIME[] prgft, uint cElems, [In, Out] PROPVARIANT ppropvar); /// - /// Initializes a structure based on a specified vector of 16-bit integer values. + /// Initializes a PROPVARIANT structure based on a GUID. The structure is initialized as VT_LPWSTR. /// + /// + /// Type: REFGUID + /// Reference to the source GUID. + /// + /// + /// Type: PROPVARIANT* + /// When this function returns, contains the initialized PROPVARIANT structure. + /// + /// + /// Type: HRESULT + /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. + /// + /// + /// Creates a VT_LPWSTR PROPVARIANT, which formats the GUID in a form similar to . + /// Examples + /// The following example, to be included as part of a larger program, demonstrates how to use InitPropVariantFromGUIDAsString. + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propvarutil/nf-propvarutil-initpropvariantfromguidasstring PSSTDAPI + // InitPropVariantFromGUIDAsString( REFGUID guid, PROPVARIANT *ppropvar ); + [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] + [PInvokeData("propvarutil.h", MSDNShortId = "bcc343f7-741f-4cdd-bd2f-ae4786faab0e")] + public static extern HRESULT InitPropVariantFromGUIDAsString([In, MarshalAs(UnmanagedType.LPStruct)] Guid guid, [In, Out] PROPVARIANT ppropvar); + + /// Initializes a structure based on a specified vector of 16-bit integer values. /// Pointer to a source vector of SHORT values. If this parameter is NULL, the vector is initialized with zeros. /// The number of elements in the vector. /// When this function returns, contains the initialized structure. @@ -155,9 +226,7 @@ namespace Vanara.PInvoke [PInvokeData("Propvarutil.h", MSDNShortId = "bb762298")] public static extern HRESULT InitPropVariantFromInt16Vector([In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 1, ArraySubType = UnmanagedType.I2)] short[] prgn, uint cElems, [In, Out] PROPVARIANT ppropvar); - /// - /// Initializes a structure based on a specified vector of 32-bit integer values. - /// + /// Initializes a structure based on a specified vector of 32-bit integer values. /// Pointer to a source vector of LONG values. If this parameter is NULL, the vector is initialized with zeros. /// The number of elements in the vector. /// When this function returns, contains the initialized structure. @@ -166,10 +235,10 @@ namespace Vanara.PInvoke [PInvokeData("Propvarutil.h", MSDNShortId = "bb762300")] public static extern HRESULT InitPropVariantFromInt32Vector([In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 1, ArraySubType = UnmanagedType.I4)] int[] prgn, uint cElems, [In, Out] PROPVARIANT ppropvar); - /// - /// Initializes a structure based on a specified vector of 64-bit integer values. - /// - /// Pointer to a source vector of LONGLONG values. If this parameter is NULL, the vector is initialized with zeros. + /// Initializes a structure based on a specified vector of 64-bit integer values. + /// + /// Pointer to a source vector of LONGLONG values. If this parameter is NULL, the vector is initialized with zeros. + /// /// The number of elements in the vector. /// When this function returns, contains the initialized structure. /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. @@ -177,11 +246,14 @@ namespace Vanara.PInvoke [PInvokeData("Propvarutil.h", MSDNShortId = "bb762302")] public static extern HRESULT InitPropVariantFromInt64Vector([In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 1, ArraySubType = UnmanagedType.I8)] long[] prgn, uint cElems, [In, Out] PROPVARIANT ppropvar); - /// - /// Initializes a structure based on a specified vector element. - /// - /// This function extracts a single value from the source structure and uses that value to initialize the output PROPVARIANT structure. The calling application must use to free the PROPVARIANT referred to by ppropvar when it is no longer needed. - /// If the source PROPVARIANT is a vector or array, iElem must be less than the number of elements in the vector or array. + /// Initializes a structure based on a specified vector element. + /// + /// This function extracts a single value from the source structure and uses that value to initialize the + /// output PROPVARIANT structure. The calling application must use to free the + /// PROPVARIANT referred to by ppropvar when it is no longer needed. + /// + /// If the source PROPVARIANT is a vector or array, iElem must be less than the number of elements in the vector or array. + /// /// If the source PROPVARIANT has a single value, iElem must be 0. /// If the source PROPVARIANT is empty, this function always returns an error code. /// You can use to obtain the number of elements in the vector or array. @@ -194,6 +266,71 @@ namespace Vanara.PInvoke [PInvokeData("Propvarutil.h", MSDNShortId = "bb762303")] public static extern HRESULT InitPropVariantFromPropVariantVectorElem([In] PROPVARIANT propvarIn, uint iElem, [In, Out] PROPVARIANT ppropvar); + /// + /// Initializes a PROPVARIANT structure based on a string resource embedded in an executable file. + /// + /// + /// Type: HINSTANCE + /// Handle to an instance of the module whose executable file contains the string resource. + /// + /// + /// Type: UINT + /// Integer identifier of the string to be loaded. + /// + /// + /// Type: PROPVARIANT* + /// When this function returns, contains the initialized PROPVARIANT structure. + /// + /// + /// Type: HRESULT + /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. + /// + /// + /// + /// This function creates a VT_LPWSTR propvariant. If the specified resource does not exist, it initializes the PROPVARIANT with an + /// empty string. Resource strings longer than 1024 characters are truncated and null-terminated. + /// + /// Examples + /// The following example, to be included as part of a larger program, demonstrates how to use InitPropVariantFromResource. + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propvarutil/nf-propvarutil-initpropvariantfromresource PSSTDAPI + // InitPropVariantFromResource( HINSTANCE hinst, UINT id, PROPVARIANT *ppropvar ); + [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] + [PInvokeData("propvarutil.h", MSDNShortId = "c958f823-f820-4b0b-86ed-84ad18befbd1")] + public static extern HRESULT InitPropVariantFromResource(IntPtr hinst, uint id, [In, Out] PROPVARIANT ppropvar); + + /// + /// + /// Initializes a PROPVARIANT structure from a specified string. The string is parsed as a semi-colon delimited list (for example: "A;B;C"). + /// + /// + /// + /// Type: PCWSTR + /// Pointer to a buffer that contains the source Unicode string. + /// + /// + /// Type: PROPVARIANT* + /// When this function returns, contains the initialized PROPVARIANT structure. + /// + /// + /// Type: HRESULT + /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. + /// + /// + /// + /// Creates a VT_VECTOR | VT_LPWSTR propvariant. It parses the source string as a semicolon list of values. The string "a; b; c" + /// creates a vector with three values. Leading and trailing whitespace are removed, and empty values are omitted. + /// + /// If psz is NULL or contains no values, the PROPVARIANT structure is initialized as VT_EMPTY. + /// Examples + /// The following example, to be included as part of a larger program, demonstrates how to use InitPropVariantFromStringAsVector. + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propvarutil/nf-propvarutil-initpropvariantfromstringasvector PSSTDAPI + // InitPropVariantFromStringAsVector( PCWSTR psz, PROPVARIANT *ppropvar ); + [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] + [PInvokeData("propvarutil.h", MSDNShortId = "fc48f2e0-ce4a-4f48-a624-202def4bcff0")] + public static extern HRESULT InitPropVariantFromStringAsVector([MarshalAs(UnmanagedType.LPWStr)] string psz, [In, Out] PROPVARIANT ppropvar); + /// Initializes a structure based on a specified string vector. /// Pointer to a buffer that contains the source string vector. /// The number of vector elements in . @@ -203,6 +340,37 @@ namespace Vanara.PInvoke [PInvokeData("Propvarutil.h", MSDNShortId = "bb762307")] public static extern HRESULT InitPropVariantFromStringVector([In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 1, ArraySubType = UnmanagedType.LPWStr)] string[] prgsz, uint cElems, [In, Out] PROPVARIANT ppropvar); + /// + /// Initializes a PROPVARIANT structure based on a string stored in a STRRET structure. + /// + /// + /// Type: STRRET* + /// Pointer to a STRRET structure that contains the string. + /// + /// + /// Type: PCUITEMID_CHILD + /// PIDL of the item whose details are being retrieved. + /// + /// + /// Type: PROPVARIANT* + /// When this function returns, contains the initialized PROPVARIANT structure. + /// + /// + /// Type: HRESULT + /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. + /// + /// + /// Creates a VT_LPWSTR propvariant. + /// Note This function frees the memory used for the STRRET contents. + /// Examples + /// The following example, to be included as part of a larger program, demonstrates how to use InitPropVariantFromStrRet. + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propvarutil/nf-propvarutil-initpropvariantfromstrret PSSTDAPI + // InitPropVariantFromStrRet( STRRET *pstrret, PCUITEMID_CHILD pidl, PROPVARIANT *ppropvar ); + [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] + [PInvokeData("propvarutil.h", MSDNShortId = "5c02e2ee-14c2-4966-83e7-16dfbf81b879")] + public static extern HRESULT InitPropVariantFromStrRet(IntPtr pstrret, IntPtr pidl, [In, Out] PROPVARIANT ppropvar); + /// Initializes a structure based on a specified string vector. /// The PRGN. /// The number of vector elements in . @@ -213,7 +381,9 @@ namespace Vanara.PInvoke public static extern HRESULT InitPropVariantFromUInt16Vector([In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 1, ArraySubType = UnmanagedType.U2)] ushort[] prgn, uint cElems, [In, Out] PROPVARIANT ppropvar); /// Initializes a structure based on a vector of 32-bit unsigned integer values. - /// Pointer to a source vector of ULONG values. If this parameter is NULL, the is initialized with zeros. + /// + /// Pointer to a source vector of ULONG values. If this parameter is NULL, the is initialized with zeros. + /// /// The number of vector elements in . /// When this function returns, contains the initialized structure. /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. @@ -222,7 +392,9 @@ namespace Vanara.PInvoke public static extern HRESULT InitPropVariantFromUInt32Vector([In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 1, ArraySubType = UnmanagedType.U4)] uint[] prgn, uint cElems, [In, Out] PROPVARIANT ppropvar); /// Initializes a structure based on a vector of 64-bit unsigned integer values. - /// Pointer to a source vector of ULONGLONG values. If this parameter is NULL, the is initialized with zeros. + /// + /// Pointer to a source vector of ULONGLONG values. If this parameter is NULL, the is initialized with zeros. + /// /// The number of vector elements in . /// When this function returns, contains the initialized structure. /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. @@ -233,17 +405,26 @@ namespace Vanara.PInvoke /// Initializes a vector element in a structure with a value stored in another PROPVARIANT. /// Reference to the source structure that contains a single value. /// When this function returns, contains the initialized structure. - /// Returns S_OK if successful, or a standard COM error value otherwise. If the requested coercion is not possible, an error is returned. + /// + /// Returns S_OK if successful, or a standard COM error value otherwise. If the requested coercion is not possible, an error is returned. + /// [DllImport(Lib.PropSys, ExactSpelling = true)] [PInvokeData("Propvarutil.h", MSDNShortId = "bb762315")] public static extern HRESULT InitPropVariantVectorFromPropVariant([In] PROPVARIANT propvarSingle, [Out] PROPVARIANT ppropvarVector); /// Coerces a value stored as a structure to an equivalent value of a different variant type. - /// A pointer to a structure that, when this function returns successfully, receives the coerced value and its new type. - /// A reference to the source structure that contains the value expressed as its original type. + /// + /// A pointer to a structure that, when this function returns successfully, receives the coerced value and + /// its new type. + /// + /// + /// A reference to the source structure that contains the value expressed as its original type. + /// /// Reserved, must be 0. /// Specifies the new type for the value. See the tables below for recognized type names. - /// Returns S_OK if successful, or a standard COM error value otherwise. If the requested coercion is not possible, an error is returned. + /// + /// Returns S_OK if successful, or a standard COM error value otherwise. If the requested coercion is not possible, an error is returned. + /// [DllImport(Lib.PropSys, ExactSpelling = true)] [PInvokeData("Propvarutil.h", MSDNShortId = "bb776514")] public static extern HRESULT PropVariantChangeType([Out] PROPVARIANT ppropvarDest, [In] PROPVARIANT propvarSrc, PROPVAR_CHANGE_FLAGS flags, VARTYPE vt); @@ -253,188 +434,1516 @@ namespace Vanara.PInvoke /// Reference to the second structure. /// /// - /// Returns 1 if propvar1 is greater than propvar2 - /// Returns 0 if propvar1 equals propvar2 - /// Returns -1 if propvar1 is less than propvar2 + /// + /// Returns 1 if propvar1 is greater than propvar2 + /// + /// + /// Returns 0 if propvar1 equals propvar2 + /// + /// + /// Returns -1 if propvar1 is less than propvar2 + /// /// /// [PInvokeData("Propvarutil.h", MSDNShortId = "bb776516")] - public static int PropVariantCompare(PROPVARIANT propvar1, PROPVARIANT propvar2) => - PropVariantCompareEx(propvar1, propvar2, PROPVAR_COMPARE_UNIT.PVCU_DEFAULT, PROPVAR_COMPARE_FLAGS.PVCF_DEFAULT); + public static int PropVariantCompare(PROPVARIANT propvar1, PROPVARIANT propvar2) + { + return PropVariantCompareEx(propvar1, propvar2, PROPVAR_COMPARE_UNIT.PVCU_DEFAULT, PROPVAR_COMPARE_FLAGS.PVCF_DEFAULT); + } - /// - /// Compares two structures, based on specified comparison units and flags. - /// - /// Reference to the first structure. - /// Reference to the second structure. + /// Compares two structures, based on specified comparison units and flags. + /// Reference to the first structure. + /// Reference to the second structure. /// Specifies, where appropriate, one of the comparison units defined in PROPVAR_COMPARE_UNIT. /// Specifies one of the following: /// /// - /// Returns 1 if propvar1 is greater than propvar2 - /// Returns 0 if propvar1 equals propvar2 - /// Returns -1 if propvar1 is less than propvar2 + /// + /// Returns 1 if propvar1 is greater than propvar2 + /// + /// + /// Returns 0 if propvar1 equals propvar2 + /// + /// + /// Returns -1 if propvar1 is less than propvar2 + /// /// /// [DllImport(Lib.PropSys, ExactSpelling = true, PreserveSig = true)] [PInvokeData("Propvarutil.h", MSDNShortId = "bb776517")] public static extern int PropVariantCompareEx(PROPVARIANT propvar1, PROPVARIANT propvar2, PROPVAR_COMPARE_UNIT unit, PROPVAR_COMPARE_FLAGS flags); - /// Retrieves the element count of a structure. - /// Reference to the source structure. - /// Returns the element count of a VT_VECTOR or VT_ARRAY value: for single values, returns 1; for empty structures, returns 0. + /// + /// Extracts a single Boolean element from a PROPVARIANT structure of type , , or . + /// + /// + /// Type: REFPROPVARIANT + /// A reference to the source PROPVARIANT structure. + /// + /// + /// Type: ULONG + /// Specifies the vector or array index; otherwise, iElem must be 0. + /// + /// + /// Type: BOOL* + /// When this function returns, contains the extracted Boolean value. + /// + /// + /// Type: HRESULT + /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. + /// + /// + /// + /// If the source PROPVARIANT structure has type , iElem must be 0. Otherwise iElem must be less than the number of elements in the + /// vector or array. You can use PropVariantGetElementCount to obtain the number of elements in the vector or array. + /// + /// The following example uses this function to loop through the values in a PROPVARIANT structure. + /// Examples + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propvarutil/nf-propvarutil-propvariantgetbooleanelem PSSTDAPI + // PropVariantGetBooleanElem( REFPROPVARIANT propvar, ULONG iElem, BOOL *pfVal ); + [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] + [PInvokeData("propvarutil.h", MSDNShortId = "830dca70-1777-418d-b3ac-78028411700e")] + public static extern HRESULT PropVariantGetBooleanElem([In] PROPVARIANT propvar, uint iElem, [MarshalAs(UnmanagedType.Bool)] out bool pfVal); + + /// + /// Extracts a single double element from a PROPVARIANT structure of type , , or . + /// + /// + /// Type: REFPROPVARIANT + /// Reference to the source PROPVARIANT structure. + /// + /// + /// Type: ULONG + /// Specifies vector or array index; otherwise, iElem must be 0. + /// + /// + /// Type: DOUBLE* + /// When this function returns, contains the extracted double value. + /// + /// + /// Type: HRESULT + /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. + /// + /// + /// + /// If the source PROPVARIANT has type , iElem must be 0. Otherwise iElem must be less than the number of elements in the vector or + /// array. You can use PropVariantGetElementCount to obtain the number of elements in the vector or array. + /// + /// The following example uses this function to loop through the values in a PROPVARIANT structure. + /// Examples + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propvarutil/nf-propvarutil-propvariantgetdoubleelem PSSTDAPI + // PropVariantGetDoubleElem( REFPROPVARIANT propvar, ULONG iElem, DOUBLE *pnVal ); + [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] + [PInvokeData("propvarutil.h", MSDNShortId = "387e23df-bfbd-42c0-adef-dc53ba95a9f2")] + public static extern HRESULT PropVariantGetDoubleElem([In] PROPVARIANT propvar, uint iElem, out double pnVal); + + /// Retrieves the element count of a structure. + /// Reference to the source structure. + /// + /// Returns the element count of a VT_VECTOR or VT_ARRAY value: for single values, returns 1; for empty structures, returns 0. + /// [DllImport(Lib.PropSys, ExactSpelling = true, PreserveSig = true)] [return: MarshalAs(UnmanagedType.I4)] [PInvokeData("Propvarutil.h", MSDNShortId = "bb776522")] public static extern int PropVariantGetElementCount([In] PROPVARIANT propVar); - /// Extracts a Boolean property value of a structure. If no value can be extracted, then a default value is assigned. - /// Reference to the source structure. + /// + /// + /// Extracts a single FILETIME element from a PROPVARIANT structure of type VT_FILETIME, VT_VECTOR | VT_FILETIME, or VT_ARRAY | VT_FILETIME. + /// + /// + /// + /// Type: REFPROPVARIANT + /// The source PROPVARIANT structure. + /// + /// + /// Type: ULONG + /// Specifies vector or array index; otherwise, this value must be 0. + /// + /// + /// Type: FILETIME* + /// When this function returns, contains the extracted filetime value. + /// + /// + /// Type: HRESULT + /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. + /// + /// + /// + /// If the source PROPVARIANT has type VT_FILETIME, iElem must be 0; otherwise, iElem must be less than the number of elements in the + /// vector or array. You can use PropVariantGetElementCount to obtain the number of elements in the vector or array. + /// + /// Examples + /// + /// The following code example, to be included as part of a larger program, demonstrates how to use PropVariantGetFileTimeElem in an + /// iteration statement to access the values in PROPVARIANT. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propvarutil/nf-propvarutil-propvariantgetfiletimeelem PSSTDAPI + // PropVariantGetFileTimeElem( REFPROPVARIANT propvar, ULONG iElem, FILETIME *pftVal ); + [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] + [PInvokeData("propvarutil.h", MSDNShortId = "e38b16ed-84cb-4444-bfbd-1165595bc9b5")] + public static extern HRESULT PropVariantGetFileTimeElem([In] PROPVARIANT propvar, uint iElem, out FILETIME pftVal); + + /// + /// Extracts a single Int16 element from a PROPVARIANT structure of type VT_I2, VT_VECTOR | VT_I2, or VT_ARRAY | VT_I2. + /// + /// + /// Type: REFPROPVARIANT + /// Reference to the source PROPVARIANT structure. + /// + /// + /// Type: ULONG + /// The vector or array index; otherwise, this value must be 0. + /// + /// + /// Type: SHORT* + /// When this function returns, contains the extracted Int32 element value. + /// + /// + /// Type: HRESULT + /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. + /// + /// + /// This helper function works for PROPVARIANT structures of the following types. + /// + /// + /// VT_I2 + /// + /// + /// VT_VECTOR | VT_I2 + /// + /// + /// VT_ARRAY | VT_I2 + /// + /// + /// + /// If the source PROPVARIANT has type VT_I2, iElem must be 0. Otherwise, iElem must be less than the number of elements in the + /// vector or array. You can use PropVariantGetElementCount to obtain the number of elements in the vector or array. + /// + /// Examples + /// + /// The following example, to be included as part of a larger program, demonstrates how to use PropVariantGetInt16Elem with an + /// iteration statement to access the values in a PROPVARIANT. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propvarutil/nf-propvarutil-propvariantgetint16elem PSSTDAPI + // PropVariantGetInt16Elem( REFPROPVARIANT propvar, ULONG iElem, SHORT *pnVal ); + [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] + [PInvokeData("propvarutil.h", MSDNShortId = "1dbb6887-81c9-411d-9fce-c9e2f3479a43")] + public static extern HRESULT PropVariantGetInt16Elem([In] PROPVARIANT propvar, uint iElem, out short pnVal); + + /// + /// Extracts a single Int32 element from a PROPVARIANT of type VT_I4, VT_VECTOR | VT_I4, or VT_ARRAY | VT_I4. + /// + /// + /// Type: REFPROPVARIANT + /// Reference to the source PROPVARIANT structure. + /// + /// + /// Type: ULONG + /// The vector or array index; otherwise, iElem must be 0. + /// + /// + /// Type: LONG* + /// When this function, contains the extracted Int32 value. + /// + /// + /// Type: HRESULT + /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. + /// + /// + /// This helper function works for PROPVARIANT structures of the following types: + /// + /// + /// VT_I4 + /// + /// + /// VT_VECTTOR | VT_I4 + /// + /// + /// VT_ARRAY | VT_I4 + /// + /// + /// + /// If the source PROPVARIANT has type VT_I4, iElem must be 0. Otherwise, iElem must be less than the number of elements in the + /// vector or array. You can use PropVariantGetElementCount to obtain the number of elements in the vector or array. + /// + /// Examples + /// + /// The following example uses this PropVariantGetInt32Elem with an interation statement to access the values in a PROPVARIANT structure. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propvarutil/nf-propvarutil-propvariantgetint32elem PSSTDAPI + // PropVariantGetInt32Elem( REFPROPVARIANT propvar, ULONG iElem, LONG *pnVal ); + [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] + [PInvokeData("propvarutil.h", MSDNShortId = "de7dc6d4-d85a-44cb-8af7-840fd6e68d5c")] + public static extern HRESULT PropVariantGetInt32Elem([In] PROPVARIANT propvar, uint iElem, out int pnVal); + + /// + /// Extracts a single Int64 element from a PROPVARIANT structure of type VT_I8, VT_VECTOR | VT_I8, or VT_ARRAY | VT_I8. + /// + /// + /// Type: REFPROPVARIANT + /// Reference to the source PROPVARIANT structure. + /// + /// + /// Type: ULONG + /// The vector or array index; otherwise, iElem must be 0. + /// + /// + /// Type: LONGLONG* + /// When this function returns, contains the extracted Int64 value. + /// + /// + /// Type: HRESULT + /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. + /// + /// + /// This helper function works forPROPVARIANTstructures of the following types: + /// + /// + /// VT_I8 + /// + /// + /// VT_VECTOR | VT_I8 + /// + /// + /// VT_ARRAY | VT_I8 + /// + /// + /// + /// If the source PROPVARIANT has type VT_I8, iElem must be 0. Otherwise, iElem must be less than the number of elements in the + /// vector or array. You can use PropVariantGetElementCount to obtain the number of elements in the vector or array. + /// + /// Examples + /// + /// The following example, to be included as part of a larger program, demonstrates how to use PropVariantGetInt64Elem with an + /// iteration statement to access the values in a PROPVARIANT. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propvarutil/nf-propvarutil-propvariantgetint64elem PSSTDAPI + // PropVariantGetInt64Elem( REFPROPVARIANT propvar, ULONG iElem, LONGLONG *pnVal ); + [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] + [PInvokeData("propvarutil.h", MSDNShortId = "6dd7212a-587f-4f9e-a2e5-dbd2a9c15a5b")] + public static extern HRESULT PropVariantGetInt64Elem([In] PROPVARIANT propvar, uint iElem, out long pnVal); + + /// + /// + /// Extracts a single Unicode string element from a PROPVARIANT structure of type VT_LPWSTR, VT_BSTR, VT_VECTOR | VT_LPWSTR, + /// VT_VECTOR | VT_BSTR, or VT_ARRAY | VT_BSTR. + /// + /// + /// + /// Type: REFPROPVARIANT + /// Reference to a source PROPVARIANT structure. + /// + /// + /// Type: ULONG + /// The vector or array index; otherwise, iElem must be 0. + /// + /// + /// Type: PWSTR* + /// + /// When this function returns, contains the extracted string value. The calling application is responsible for freeing this string + /// by calling CoTaskMemFree when it is no longer needed. + /// + /// + /// + /// Type: HRESULT + /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. + /// + /// + /// This helper function works for PROPVARIANT structures of the following types: + /// + /// + /// VT_LPWSTR + /// + /// + /// VT_BSTR + /// + /// + /// VT_VECTOR | VT_LPWSTR + /// + /// + /// VT_VECTOR | VT_BSTR + /// + /// + /// VT_ARRAY | VT_BSTR + /// + /// + /// + /// If the source PROPVARIANT has type VT_LPWSTR or VT_BSTR, iElem must be 0. Otherwise iElem must be less than the number of + /// elements in the vector or array. You can use PropVariantGetElementCount to obtain the number of elements in the vector or array. + /// + /// If a BSTR element has a NULL pointer, this function allocates an empty string. + /// Examples + /// + /// The following code example, to be included as part of a larger program, demonstrates how to use PropVariantGetStringElem with an + /// iteration statement to access the values in a PROPVARIANT. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propvarutil/nf-propvarutil-propvariantgetstringelem PSSTDAPI + // PropVariantGetStringElem( REFPROPVARIANT propvar, ULONG iElem, PWSTR *ppszVal ); + [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] + [PInvokeData("propvarutil.h", MSDNShortId = "6e803d93-5b55-4b73-8e23-a584f5f91969")] + public static extern HRESULT PropVariantGetStringElem([In] PROPVARIANT propvar, uint iElem, [MarshalAs(UnmanagedType.CustomMarshaler, MarshalTypeRef = typeof(CoTaskMemStringMarshaler))] out string ppszVal); + + /// + /// + /// Extracts a single unsigned Int16 element from a PROPVARIANT structure of type VT_U12, VT_VECTOR | VT_U12, or VT_ARRAY | VT_U12. + /// + /// + /// + /// Type: REFPROPVARIANT + /// Reference to the source PROPVARIANT structure. + /// + /// + /// Type: ULONG + /// The vector or array index; otherwise, iElem must be 0. + /// + /// + /// Type: USHORT* + /// When this function returns, contains the extracted element value. + /// + /// + /// Type: HRESULT + /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. + /// + /// + /// This helper function works for PROPVARIANT structures of the following types: + /// + /// + /// VT_UI2 + /// + /// + /// VT_VECTOR | VT_UI2 + /// + /// + /// VT_ARRAY | VT_UI2 + /// + /// + /// + /// If the source PROPVARIANT has type VT_UI2, iElem must be 0. Otherwise iElem must be less than the number of elements in the + /// vector or array. You can use PropVariantGetElementCount to obtain the number of elements in the vector or array. + /// + /// Examples + /// + /// The following example, to be included as part of a larger program, demonstrates how to use PropVariantGetUInt16Elem with an + /// iteration statement to access the values in a PROPVARIANT. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propvarutil/nf-propvarutil-propvariantgetuint16elem PSSTDAPI + // PropVariantGetUInt16Elem( REFPROPVARIANT propvar, ULONG iElem, USHORT *pnVal ); + [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] + [PInvokeData("propvarutil.h", MSDNShortId = "da50e35b-f17f-4de6-b2e7-5a885e2149e5")] + public static extern HRESULT PropVariantGetUInt16Elem([In] PROPVARIANT propvar, uint iElem, out ushort pnVal); + + /// + /// + /// Extracts a single unsigned Int32 element from a PROPVARIANT structure of type VT_UI4, VT_VECTOR | VT_UI4, or VT_ARRAY | VT_UI4. + /// + /// + /// + /// Type: REFPROPVARIANT + /// The source PROPVARIANT structure. + /// + /// + /// Type: ULONG + /// A vector or array index; otherwise, iElem must be 0. + /// + /// + /// Type: ULONG* + /// When this function returns, contains the extracted unsigned Int32 value. + /// + /// + /// Type: HRESULT + /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. + /// + /// + /// This helper function works for PROPVARIANT structures of the following types: + /// + /// + /// VT_UI4 + /// + /// + /// VT_VECTOR | VT_UI4 + /// + /// + /// VT_ARRAY | VT_UI4 + /// + /// + /// + /// If the source PROPVARIANT has type VT_UI4, iElem must be 0. Otherwise, iElem must be less than the number of elements in the + /// vector or array. You can use PropVariantGetElementCount to obtain the number of elements in the vector or array. + /// + /// Examples + /// + /// The following example, to be included as part of a larger program, demonstrates how to use PropVariantGetUInt32Elem with an + /// iteration statement to access the values in a PROPVARIANT. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propvarutil/nf-propvarutil-propvariantgetuint32elem PSSTDAPI + // PropVariantGetUInt32Elem( REFPROPVARIANT propvar, ULONG iElem, ULONG *pnVal ); + [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] + [PInvokeData("propvarutil.h", MSDNShortId = "b31975b6-d717-4e8d-bf5a-2ade96034031")] + public static extern HRESULT PropVariantGetUInt32Elem([In] PROPVARIANT propvar, uint iElem, out uint pnVal); + + /// + /// + /// Extracts a single unsigned Int64 element from a PROPVARIANT structure of type VT_UI8, VT_VECTOR | VT_UI8, or VT_ARRAY | VT_UI8. + /// + /// + /// + /// Type: REFPROPVARIANT + /// The source PROPVARIANT structure. + /// + /// + /// Type: ULONG + /// The vector or array index; otherwise, iElem must be 0. + /// + /// + /// Type: ULONGLONG* + /// When this function returns, contains the extracted Int64 value. + /// + /// + /// Type: HRESULT + /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. + /// + /// + /// This helper function works for PROPVARIANT structures of the following types: + /// + /// + /// VT_UI8 + /// + /// + /// VT_VECTOR | VT_UI8 + /// + /// + /// VT_ARRAY | VT_UI8 + /// + /// + /// + /// If the source PROPVARIANT has type VT_UI8, iElem must be 0. Otherwise iElem must be less than the number of elements in the + /// vector or array. You can use PropVariantGetElementCount to obtain the number of elements in the vector or array. + /// + /// Examples + /// + /// The following example, to be included as part of a larger program, demonstrates how to use PropVariantGetUInt64Elem with an + /// iteration statement to access the values in a PROPVARIANT. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propvarutil/nf-propvarutil-propvariantgetuint64elem PSSTDAPI + // PropVariantGetUInt64Elem( REFPROPVARIANT propvar, ULONG iElem, ULONGLONG *pnVal ); + [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] + [PInvokeData("propvarutil.h", MSDNShortId = "35955104-b567-4c4f-850a-0a4778673ce8")] + public static extern HRESULT PropVariantGetUInt64Elem([In] PROPVARIANT propvar, uint iElem, out ulong pnVal); + + /// + /// Extracts a Boolean property value of a structure. If no value can be extracted, then a default value is assigned. + /// + /// Reference to the source structure. /// When this function returns, contains the extracted property value if one exists; otherwise, contains FALSE. /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. [DllImport(Lib.PropSys, ExactSpelling = true)] [PInvokeData("Propvarutil.h", MSDNShortId = "bb776531")] public static extern HRESULT PropVariantToBoolean([In] PROPVARIANT propVar, [MarshalAs(UnmanagedType.Bool)] out bool pfRet); - /// Extracts data from a structure into a newly allocated Boolean vector. - /// Reference to the source structure. - /// When this function returns, contains a pointer to a vector of Boolean values extracted from the source structure. - /// When this function returns, contains the count of Boolean elements extracted from the source structure. - /// Returns S_OK if successful, or an error value otherwise. E_INVALIDARG indicates that the was not of the appropriate type. + /// + /// Extracts a Boolean vector from a PROPVARIANT structure. + /// + /// + /// Type: REFPROPVARIANT + /// Reference to a source PROPVARIANT structure. + /// + /// + /// Type: BOOL* + /// + /// Points to a buffer that contains crgf BOOL values. When this function returns, the buffer has been initialized with pcElem + /// Boolean elements extracted from the source PROPVARIANT structure. + /// + /// + /// + /// Type: ULONG + /// Number of elements in the buffer pointed to by prgf. + /// + /// + /// Type: ULONG* + /// When this function returns, contains the count of Boolean elements extracted from source PROPVARIANT structure. + /// + /// + /// Type: HRESULT + /// This function can return one of these values. + /// + /// + /// Return code + /// Description + /// + /// + /// S_OK + /// Returns S_OK if successful, or an error value otherwise. + /// + /// + /// TYPE_E_BUFFERTOOSMALL + /// The source PROPVARIANT contained more than crgf values. The buffer pointed to by prgf. + /// + /// + /// E_INVALIDARG + /// The PROPVARIANT was not of the appropriate type. + /// + /// + /// + /// + /// + /// This helper function is used when the calling application expects a PROPVARIANT to hold a Boolean vector value with a fixed + /// number of elements. + /// + /// + /// If the source PROPVARIANT has type VT_VECTOR | VT_BOOL or VT_ARRAY | VT_BOOL, this helper function extracts up to crgf Boolean + /// values an places them into the buffer pointed to by prgf. If the PROPVARIANT contains more elements than will fit into the + /// prgf buffer, this function returns an error and sets pcElem to 0. + /// + /// Examples + /// + /// The following example, to be included as part of a larger program, demonstrates how to use PropVariantToBooleanVector to access a + /// Boolean vector stored in a PROPVARIANT. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propvarutil/nf-propvarutil-propvarianttobooleanvector PSSTDAPI + // PropVariantToBooleanVector( REFPROPVARIANT propvar, BOOL *prgf, ULONG crgf, ULONG *pcElem ); + [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] + [PInvokeData("propvarutil.h", MSDNShortId = "93ccd129-4fa4-40f3-96f3-b87b50414b0a")] + public static extern HRESULT PropVariantToBooleanVector([In] PROPVARIANT propvar, [In, Out, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 2, ArraySubType = UnmanagedType.Bool)] bool[] prgf, uint crgf, out uint pcElem); + + /// Extracts data from a structure into a newly allocated Boolean vector. + /// Reference to the source structure. + /// + /// When this function returns, contains a pointer to a vector of Boolean values extracted from the source structure. + /// + /// + /// When this function returns, contains the count of Boolean elements extracted from the source structure. + /// + /// + /// Returns S_OK if successful, or an error value otherwise. E_INVALIDARG indicates that the was not of the + /// appropriate type. + /// [DllImport(Lib.PropSys, ExactSpelling = true)] [PInvokeData("Propvarutil.h", MSDNShortId = "bb776533")] public static extern HRESULT PropVariantToBooleanVectorAlloc([In] PROPVARIANT propVar, out SafeCoTaskMemHandle pprgf, out uint pcElem); - /// Extracts the BSTR property value of a structure. - /// Reference to the source structure. + /// + /// + /// Extracts the Boolean property value of a PROPVARIANT structure. If no value exists, then the specified default value is returned. + /// + /// + /// + /// Type: REFPROPVARIANT + /// Reference to a source PROPVARIANT structure. + /// + /// + /// Type: BOOL + /// Specifies the default property value, for use where no value currently exists. + /// + /// + /// Type: BOOL + /// The extracted Boolean value or the default value. + /// + /// + /// + /// This helper function is used in places where the calling application expects a PROPVARIANT to hold a Boolean value and would like + /// to use a default value if it does not. For instance, an application that obtains values from a property store can use this to + /// safely extract the Boolean value for Boolean properties. + /// + /// + /// If the source PROPVARIANT has type VT_BOOL, this helper function extracts the Boolean value. Otherwise, it attempts to + /// convert the value in the PROPVARIANT structure into a Boolean. If the source PROPVARIANT has type VT_EMPTY + /// or a conversion is not possible, then PropVariantToBooleanWithDefault returns the default provided by fDefault. See + /// PropVariantChangeType for a list of possible conversions. + /// + /// Examples + /// + /// The following example, to be included as part of a larger program, demonstrates how to use PropVariantToBooleanWithDefault to + /// access a Boolean value in a PROPVARIANT. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propvarutil/nf-propvarutil-propvarianttobooleanwithdefault PSSTDAPI_(BOOL) + // PropVariantToBooleanWithDefault( REFPROPVARIANT propvarIn, BOOL fDefault ); + [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] + [PInvokeData("propvarutil.h", MSDNShortId = "223767a7-a4de-4e7e-ad8b-2a6bdcea0a47")] + [return: MarshalAs(UnmanagedType.Bool)] + public static extern bool PropVariantToBooleanWithDefault([In] PROPVARIANT propvarIn, [MarshalAs(UnmanagedType.Bool)] bool fDefault); + + /// Extracts the BSTR property value of a structure. + /// Reference to the source structure. /// Pointer to the extracted property value if one exists; otherwise, contains an empty string. /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. [DllImport(Lib.PropSys, ExactSpelling = true)] [PInvokeData("Propvarutil.h", MSDNShortId = "bb776535")] public static extern HRESULT PropVariantToBSTR([In] PROPVARIANT propVar, [MarshalAs(UnmanagedType.BStr)] out string pbstrOut); - /// Extracts the buffer value from a structure of type VT_VECTOR | VT_UI1 or VT_ARRRAY | VT_UI1. - /// Reference to the source structure. - /// Pointer to a buffer of length cb bytes. When this function returns, contains the first cb bytes of the extracted buffer value. + /// Extracts the buffer value from a structure of type VT_VECTOR | VT_UI1 or VT_ARRRAY | VT_UI1. + /// Reference to the source structure. + /// + /// Pointer to a buffer of length cb bytes. When this function returns, contains the first cb bytes of the extracted buffer value. + /// /// The buffer length, in bytes. /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. [DllImport(Lib.PropSys, ExactSpelling = true)] [PInvokeData("Propvarutil.h", MSDNShortId = "bb776536")] public static extern HRESULT PropVariantToBuffer([In] PROPVARIANT propVar, [In, Out, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 2)] byte[] pv, uint cb); - /// Extracts double value from a structure. - /// Reference to the source structure. - /// When this function returns, contains the extracted property value if one exists; otherwise, contains 0.0. + /// Extracts double value from a structure. + /// Reference to the source structure. + /// + /// When this function returns, contains the extracted property value if one exists; otherwise, contains 0.0. + /// /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. [DllImport(Lib.PropSys, ExactSpelling = true)] [PInvokeData("Propvarutil.h", MSDNShortId = "bb776538")] public static extern HRESULT PropVariantToDouble([In] PROPVARIANT propVar, [MarshalAs(UnmanagedType.R8)] out double pdblRet); - /// Extracts data from a structure into a newly-allocated double vector. - /// Reference to the source structure. - /// When this function returns, contains a pointer to a vector of double values extracted from the source structure. - /// When this function returns, contains the count of double elements extracted from the source structure. + /// + /// Extracts a vector of doubles from a PROPVARIANT structure. + /// + /// + /// Type: REFPROPVARIANT + /// Reference to a source PROPVARIANT structure. + /// + /// + /// Type: DOUBLE* + /// + /// Points to a buffer containing crgn DOUBLE values. When this function returns, the buffer has been initialized with pcElem double + /// elements extracted from the source PROPVARIANT structure. + /// + /// + /// + /// Type: ULONG + /// Size in elements of the buffer pointed to by prgn. + /// + /// + /// Type: ULONG* + /// When this function returns, contains the count of double elements extracted from the source PROPVARIANT structure. + /// + /// + /// Type: HRESULT + /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. + /// + /// + /// + /// This helper function is used in places where the calling application expects a PROPVARIANT to hold a double vector value with a + /// fixed number of elements. + /// + /// + /// If the source PROPVARIANT has type VT_VECTOR | VT_R8 or VT_ARRAY | VT_R8, this helper function extracts up to crgn double values + /// and places them into the buffer pointed to by prgn. If the PROPVARIANT contains more elements than will fit into the prgn + /// buffer, this function returns an error and sets pcElem to 0. + /// + /// Examples + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propvarutil/nf-propvarutil-propvarianttodoublevector PSSTDAPI + // PropVariantToDoubleVector( REFPROPVARIANT propvar, DOUBLE *prgn, ULONG crgn, ULONG *pcElem ); + [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] + [PInvokeData("propvarutil.h", MSDNShortId = "2d90bf96-8a3f-4949-8480-bb75f0deeb2e")] + public static extern HRESULT PropVariantToDoubleVector([In] PROPVARIANT propvar, [In, Out, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 2)] double[] prgn, uint crgn, out uint pcElem); + + /// Extracts data from a structure into a newly-allocated double vector. + /// Reference to the source structure. + /// + /// When this function returns, contains a pointer to a vector of double values extracted from the source structure. + /// + /// + /// When this function returns, contains the count of double elements extracted from the source structure. + /// /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. [DllImport(Lib.PropSys, ExactSpelling = true)] [PInvokeData("Propvarutil.h", MSDNShortId = "bb776540")] public static extern HRESULT PropVariantToDoubleVectorAlloc([In] PROPVARIANT propVar, out SafeCoTaskMemHandle pprgf, out uint pcElem); - /// Extracts the structure from a structure. - /// Reference to the source structure. + /// + /// Extracts a double property value of a PROPVARIANT structure. If no value exists, then the specified default value is returned. + /// + /// + /// Type: REFPROPVARIANT + /// Reference to a source PROPVARIANT structure. + /// + /// + /// Type: DOUBLE + /// Specifies default property value, for use where no value currently exists. + /// + /// + /// Type: DOUBLE + /// Returns extracted double value, or default. + /// + /// + /// + /// This helper function is used in places where the calling application expects a PROPVARIANT to hold a double value and would like + /// to use a default value if it does not. For instance, an application obtaining values from a property store can use this to safely + /// extract the double value for double properties. + /// + /// + /// If the source PROPVARIANT has type VT_R8, this helper function extracts the double value. Otherwise, it attempts to + /// convert the value in the PROPVARIANT structure into a double. If the source PROPVARIANT has type VT_EMPTY or + /// a conversion is not possible, then PropVariantToDoubleWithDefault will return the default provided by dblDefault. See + /// PropVariantChangeType for a list of possible conversions. + /// + /// Examples + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propvarutil/nf-propvarutil-propvarianttodoublewithdefault PSSTDAPI_(DOUBLE) + // PropVariantToDoubleWithDefault( REFPROPVARIANT propvarIn, DOUBLE dblDefault ); + [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] + [PInvokeData("propvarutil.h", MSDNShortId = "81584e13-0ef7-47ce-b78f-b4a79712ff1e")] + public static extern double PropVariantToDoubleWithDefault([In] PROPVARIANT propvarIn, double dblDefault); + + /// Extracts the structure from a structure. + /// Reference to the source structure. /// Specifies one of the time flags. - /// When this function returns, contains the extracted structure. + /// When this function returns, contains the extracted structure. /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. [DllImport(Lib.PropSys, ExactSpelling = true)] [PInvokeData("Propvarutil.h", MSDNShortId = "bb776542")] public static extern HRESULT PropVariantToFileTime([In] PROPVARIANT propVar, PSTIME_FLAGS pstfOut, out FILETIME pftOut); - /// Extracts data from a structure into a newly-allocated vector. - /// Reference to the source structure. - /// When this function returns, contains a pointer to a vector of values extracted from the source structure. - /// When this function returns, contains the count of elements extracted from source structure. + /// + /// Extracts data from a PROPVARIANT structure into a FILETIME vector. + /// + /// + /// Type: REFPROPVARIANT + /// Reference to a source PROPVARIANT structure. + /// + /// + /// Type: FILETIME* + /// + /// Points to a buffer containing crgft FILETIME values. When this function returns, the buffer has been initialized with pcElem + /// FILETIME elements extracted from the source PROPVARIANT structure. + /// + /// + /// + /// Type: ULONG + /// Size in elements of the buffer pointed to by prgft. + /// + /// + /// Type: ULONG* + /// When this function returns, contains the count of FILETIME elements extracted from the source PROPVARIANT structure. + /// + /// + /// Type: HRESULT + /// Returns one of the following values. + /// + /// + /// Return code + /// Description + /// + /// + /// S_OK + /// Returns S_OK if successful, or an error value otherwise. + /// + /// + /// TYPE_E_BUFFERTOOSMALL + /// The source PROPVARIANT contained more than crgn values. The buffer pointed to by prgft. + /// + /// + /// E_INVALIDARG + /// The PROPVARIANT was not of the appropriate type. + /// + /// + /// + /// + /// + /// This helper function is used in places where the calling application expects a PROPVARIANT to hold a filetime vector value with a + /// fixed number of elements. + /// + /// + /// If the source PROPVARIANT has type VT_VECTOR | VT_FILETIME, this helper function extracts up to crgft FILETIME values and places + /// them into the buffer pointed to by prgft. If the PROPVARIANT contains more elements than will fit into the prgft buffer, + /// this function returns an error and sets pcElem to 0. + /// + /// The output FILETIMEs will use the same time zone as the source FILETIMEs. + /// Examples + /// + /// The following example, to be included as part of a larger program, demonstrates how to use PropVariantToFileTimeVector to access + /// a FILETIME vector value in a PROPVARIANT. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propvarutil/nf-propvarutil-propvarianttofiletimevector PSSTDAPI + // PropVariantToFileTimeVector( REFPROPVARIANT propvar, FILETIME *prgft, ULONG crgft, ULONG *pcElem ); + [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] + [PInvokeData("propvarutil.h", MSDNShortId = "ef665f50-3f3b-47db-9133-490305da5341")] + public static extern HRESULT PropVariantToFileTimeVector([In] PROPVARIANT propvar, [In, Out, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 2)] FILETIME[] prgft, uint crgft, out uint pcElem); + + /// Extracts data from a structure into a newly-allocated vector. + /// Reference to the source structure. + /// + /// When this function returns, contains a pointer to a vector of values extracted from the source structure. + /// + /// + /// When this function returns, contains the count of elements extracted from source structure. + /// /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. [DllImport(Lib.PropSys, ExactSpelling = true)] [PInvokeData("Propvarutil.h", MSDNShortId = "bb776544")] public static extern HRESULT PropVariantToFileTimeVectorAlloc([In] PROPVARIANT propVar, out SafeCoTaskMemHandle pprgf, out uint pcElem); - /// Extracts a GUID value from a structure. - /// Reference to the source structure. + /// Extracts a GUID value from a structure. + /// Reference to the source structure. /// When this function returns, contains the extracted property value if one exists. /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. [DllImport(Lib.PropSys, ExactSpelling = true)] [PInvokeData("Propvarutil.h", MSDNShortId = "bb776545")] public static extern HRESULT PropVariantToGUID([In] PROPVARIANT propVar, out Guid pguid); - /// Extracts an Int16 property value of a structure. - /// Reference to the source structure. + /// Extracts an Int16 property value of a structure. + /// Reference to the source structure. /// When this function returns, contains the extracted property value if one exists; otherwise, 0. /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. [DllImport(Lib.PropSys, ExactSpelling = true)] [PInvokeData("Propvarutil.h", MSDNShortId = "bb776546")] public static extern HRESULT PropVariantToInt16([In] PROPVARIANT propVar, [MarshalAs(UnmanagedType.I2)] out short piRet); - /// Extracts data from a structure into a newly allocated Int16 vector. - /// Reference to the source structure. - /// When this function returns, contains a pointer to a vector of Int16 values extracted from the source structure. - /// When this function returns, contains the count of Int16 elements extracted from source structure. + /// + /// Extracts a vector of Int16 values from a PROPVARIANT structure. + /// + /// + /// Type: REFPROPVARIANT + /// Reference to a source PROPVARIANT structure. + /// + /// + /// Type: SHORT* + /// + /// Points to a buffer containing crgn SHORT values. When this function returns, the buffer has been initialized with pcElem SHORT + /// elements extracted from the source PROPVARIANT structure. + /// + /// + /// + /// Type: ULONG + /// Size of the buffer pointed to by prgn in elements. + /// + /// + /// Type: ULONG* + /// When this function returns, contains the count of Int16 elements extracted from source PROPVARIANT structure. + /// + /// + /// Type: HRESULT + /// This function can return one of these values. + /// + /// + /// Return code + /// Description + /// + /// + /// S_OK + /// Returns S_OK if successful, or an error value otherwise. + /// + /// + /// TYPE_E_BUFFERTOOSMALL + /// The source PROPVARIANT contained more than crgn values. The buffer pointed to by prgn. + /// + /// + /// E_INVALIDARG + /// ThePROPVARIANTwas not of the appropriate type. + /// + /// + /// + /// + /// + /// This helper function is used in places where the calling application expects a PROPVARIANT to hold an Int16 vector value + /// with a fixed number of elements. + /// + /// + /// If the source PROPVARIANT has type VT_VECTOR | VT_I2 or VT_ARRAY | VT_I2, this helper function extracts up to crgn Int16 values + /// and places them into the buffer pointed to by prgn. If the PROPVARIANT contains more elements than will fit into the prgn + /// buffer, this function returns an error and sets pcElem to 0. + /// + /// Examples + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propvarutil/nf-propvarutil-propvarianttoint16vector PSSTDAPI + // PropVariantToInt16Vector( REFPROPVARIANT propvar, SHORT *prgn, ULONG crgn, ULONG *pcElem ); + [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] + [PInvokeData("propvarutil.h", MSDNShortId = "33240552-7caa-4114-aad6-7341551b1fbe")] + public static extern HRESULT PropVariantToInt16Vector([In] PROPVARIANT propvar, [In, Out, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 2)] short[] prgn, uint crgn, out uint pcElem); + + /// Extracts data from a structure into a newly allocated Int16 vector. + /// Reference to the source structure. + /// + /// When this function returns, contains a pointer to a vector of Int16 values extracted from the source structure. + /// + /// + /// When this function returns, contains the count of Int16 elements extracted from source structure. + /// /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. [DllImport(Lib.PropSys, ExactSpelling = true)] [PInvokeData("Propvarutil.h", MSDNShortId = "bb776548")] public static extern HRESULT PropVariantToInt16VectorAlloc([In] PROPVARIANT propVar, out SafeCoTaskMemHandle pprgf, out uint pcElem); - /// Extracts an Int32 property value of a structure. - /// Reference to the source structure. + /// + /// + /// Extracts the Int16 property value of a PROPVARIANT structure. If no value currently exists, then specified default value is returned. + /// + /// + /// + /// Type: REFPROPVARIANT + /// Reference to a source PROPVARIANT structure. + /// + /// + /// Type: SHORT + /// Specifies default property value, for use where no value currently exists. + /// + /// + /// Type: SHORT + /// Returns the extracted short value, or default. + /// + /// + /// + /// This helper function is used in places where the calling application expects a PROPVARIANT to hold an Int16 value and + /// would like to use a default value if it does not. For instance, an application obtaining values from a property store can use + /// this to safely extract the SHORT value for Int16 properties. + /// + /// + /// If the source PROPVARIANT has type VT_I2, this helper function extracts the Int16 value. Otherwise, it attempts to + /// convert the value in the PROPVARIANT structure into a SHORT. If the source PROPVARIANT has type + /// VT_EMPTY or a conversion is not possible, then PropVariantToInt16WithDefault will return the default provided by iDefault. + /// See PropVariantChangeType for a list of possible conversions. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propvarutil/nf-propvarutil-propvarianttoint16withdefault PSSTDAPI_(SHORT) + // PropVariantToInt16WithDefault( REFPROPVARIANT propvarIn, SHORT iDefault ); + [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] + [PInvokeData("propvarutil.h", MSDNShortId = "51221281-6e06-49f4-83c0-7330f2a6d67e")] + public static extern short PropVariantToInt16WithDefault([In] PROPVARIANT propvarIn, short iDefault); + + /// Extracts an Int32 property value of a structure. + /// Reference to the source structure. /// When this function returns, contains the extracted property value if one exists; otherwise, 0. /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. [DllImport(Lib.PropSys, ExactSpelling = true)] [PInvokeData("Propvarutil.h", MSDNShortId = "bb776550")] public static extern HRESULT PropVariantToInt32([In] PROPVARIANT propVar, [MarshalAs(UnmanagedType.I4)] out int plRet); - /// Extracts data from a structure into a newly allocated Int32 vector. - /// Reference to the source structure. - /// When this function returns, contains a pointer to a vector of Int32 values extracted from the source structure. - /// When this function returns, contains the count of Int32 elements extracted from source structure. + /// + /// Extracts a vector of long values from a PROPVARIANT structure. + /// + /// + /// Type: REFPROPVARIANT + /// Reference to a source PROPVARIANT structure. + /// + /// + /// Type: LONG* + /// + /// Points to a buffer containing crgn LONG values. When this function returns, the buffer has been initialized with pcElem + /// LONG elements extracted from the source PROPVARIANT. + /// + /// + /// + /// Type: ULONG + /// Size of the buffer pointed to by prgn in elements. + /// + /// + /// Type: ULONG* + /// When this function returns, contains the count of LONG elements extracted from source PROPVARIANT structure. + /// + /// + /// Type: HRESULT + /// This function can return one of these values. + /// + /// + /// Return code + /// Description + /// + /// + /// S_OK + /// Returns S_OK if successful, or an error value otherwise. + /// + /// + /// TYPE_E_BUFFERTOOSMALL + /// The source PROPVARIANT contained more than crgn values. The buffer pointed to by prgn. + /// + /// + /// E_INVALIDARG + /// The PROPVARIANT was not of the appropriate type. + /// + /// + /// + /// + /// + /// This helper function is used in places where the calling application expects a PROPVARIANT to hold an vector of LONG + /// values with a fixed number of elements. + /// + /// + /// If the source PROPVARIANT has type VT_VECTOR | VT_I4 or VT_ARRAY | VT_I4, this helper function + /// extracts up to crgn LONG values and places them into the buffer pointed to by prgn. If the PROPVARIANT contains + /// more elements than will fit into the prgn buffer, this function returns an error and sets pcElem to 0. + /// + /// Examples + /// + /// The following example, to be included as part of a larger program, demonstrates how to use PropVariantToInt32Vector to access an + /// Int32 vector value in a PROPVARIANT. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propvarutil/nf-propvarutil-propvarianttoint32vector PSSTDAPI + // PropVariantToInt32Vector( REFPROPVARIANT propvar, LONG *prgn, ULONG crgn, ULONG *pcElem ); + [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] + [PInvokeData("propvarutil.h", MSDNShortId = "771fa1d7-c648-49d4-a6a2-5aa23f8c20b7")] + public static extern HRESULT PropVariantToInt32Vector([In] PROPVARIANT propvar, [In, Out, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 2)] int[] prgn, uint crgn, out uint pcElem); + + /// Extracts data from a structure into a newly allocated Int32 vector. + /// Reference to the source structure. + /// + /// When this function returns, contains a pointer to a vector of Int32 values extracted from the source structure. + /// + /// + /// When this function returns, contains the count of Int32 elements extracted from source structure. + /// /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. [DllImport(Lib.PropSys, ExactSpelling = true)] [PInvokeData("Propvarutil.h", MSDNShortId = "bb776552")] public static extern HRESULT PropVariantToInt32VectorAlloc([In] PROPVARIANT propVar, out SafeCoTaskMemHandle pprgf, out uint pcElem); - /// Extracts an Int64 property value of a structure. - /// Reference to the source structure. + /// + /// + /// Extracts an Int32 value from a PROPVARIANT structure. If no value currently exists, then the specified default value is returned. + /// + /// + /// + /// Type: REFPROPVARIANT + /// Reference to a source PROPVARIANT structure. + /// + /// + /// Type: LONG + /// Specifies a default property value, for use where no value currently exists. + /// + /// + /// Type: LONG + /// Returns extracted LONG value, or default. + /// + /// + /// + /// This helper function is used in places where the calling application expects a PROPVARIANT to hold a LONG value and would + /// like to use a default value if it does not. For instance, an application obtaining values from a property store can use this to + /// safely extract the LONG value for Int32 properties. + /// + /// + /// If the source PROPVARIANT has type VT_I4, this helper function extracts the LONG value. Otherwise, it attempts to + /// convert the value in the PROPVARIANT structure into a LONG. If the source PROPVARIANT has type + /// VT_EMPTY or a conversion is not possible, then PropVariantToInt32WithDefault will return the default provided by lDefault. + /// See PropVariantChangeType for a list of possible conversions. + /// + /// Examples + /// + /// The following example, to be included as part of a larger program, demonstrates how to use PropVariantToInt32WithDefault to + /// access a LONG value in a PROPVARIANT. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propvarutil/nf-propvarutil-propvarianttoint32withdefault PSSTDAPI_(LONG) + // PropVariantToInt32WithDefault( REFPROPVARIANT propvarIn, LONG lDefault ); + [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] + [PInvokeData("propvarutil.h", MSDNShortId = "1d014cad-a9a5-4a58-855e-21c6d3ba6dcd")] + public static extern int PropVariantToInt32WithDefault([In] PROPVARIANT propvarIn, int lDefault); + + /// Extracts an Int64 property value of a structure. + /// Reference to the source structure. /// When this function returns, contains the extracted property value if one exists; otherwise, 0. /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. [DllImport(Lib.PropSys, ExactSpelling = true)] [PInvokeData("Propvarutil.h", MSDNShortId = "bb776554")] public static extern HRESULT PropVariantToInt64([In] PROPVARIANT propVar, [MarshalAs(UnmanagedType.I8)] out long pllRet); - /// Extracts data from a structure into a newly allocated Int64 vector. - /// Reference to the source structure. - /// When this function returns, contains a pointer to a vector of Int64 values extracted from the source structure. - /// When this function returns, contains the count of Int64 elements extracted from source structure. + /// + /// Extracts data from a PROPVARIANT structure into an Int64 vector. + /// + /// + /// Type: REFPROPVARIANT + /// Reference to a source PROPVARIANT structure. + /// + /// + /// Type: LONGLONG* + /// + /// Points to a buffer containing crgn LONGLONG values. When this function returns, the buffer has been initialized with + /// pcElem LONGLONG elements extracted from the source PROPVARIANT. + /// + /// + /// + /// Type: ULONG + /// Size of the buffer pointed to by prgn in elements. + /// + /// + /// Type: ULONG* + /// When this function returns, contains the count of LONGLONG values extracted from the source PROPVARIANT structure. + /// + /// + /// Type: HRESULT + /// This function can return one of these values. + /// + /// + /// Return code + /// Description + /// + /// + /// S_OK + /// Returns S_OK if successful, or an error value otherwise. + /// + /// + /// TYPE_E_BUFFERTOOSMALL + /// The source PROPVARIANT contained more than crgn values. The buffer pointed to by prgn. + /// + /// + /// E_INVALIDARG + /// The PROPVARIANT was not of the appropriate type + /// + /// + /// + /// + /// + /// This helper function is used in places where the calling application expects a PROPVARIANT to hold an vector of LONGLONG + /// values with a fixed number of elements. + /// + /// + /// If the source PROPVARIANT has type VT_VECTOR | VT_I8 or VT_ARRAY | VT_I8, this helper function + /// extracts up to crgn LONGLONG values and places them into the buffer pointed to by prgn. If the PROPVARIANT contains + /// more elements than will fit into the prgn buffer, this function returns an error and sets pcElem to 0. + /// + /// Examples + /// + /// The following example, to be included as part of a larger program, demonstrates how to use PropVariantToInt64Vector to access an + /// Int64 vector value in a PROPVARIANT. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propvarutil/nf-propvarutil-propvarianttoint64vector PSSTDAPI + // PropVariantToInt64Vector( REFPROPVARIANT propvar, LONGLONG *prgn, ULONG crgn, ULONG *pcElem ); + [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] + [PInvokeData("propvarutil.h", MSDNShortId = "cda5589a-726f-4e43-aec4-bb7a7ca62b1a")] + public static extern HRESULT PropVariantToInt64Vector([In] PROPVARIANT propvar, [In, Out, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 2)] long[] prgn, uint crgn, out uint pcElem); + + /// Extracts data from a structure into a newly allocated Int64 vector. + /// Reference to the source structure. + /// + /// When this function returns, contains a pointer to a vector of Int64 values extracted from the source structure. + /// + /// + /// When this function returns, contains the count of Int64 elements extracted from source structure. + /// /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. [DllImport(Lib.PropSys, ExactSpelling = true)] [PInvokeData("Propvarutil.h", MSDNShortId = "bb776557")] public static extern HRESULT PropVariantToInt64VectorAlloc([In] PROPVARIANT propVar, out SafeCoTaskMemHandle pprgf, out uint pcElem); - /// Extracts a string property value from a structure. - /// Reference to the source structure. + /// + /// + /// Extracts the Int64 property value of a PROPVARIANT structure. If no value exists, then specified default value is returned. + /// + /// + /// + /// Type: REFPROPVARIANT + /// Reference to a source PROPVARIANT structure. + /// + /// + /// Type: LONGLONG + /// Specifies a default property value, for use where no value currently exists. + /// + /// + /// Type: LONGLONG + /// Returns the extracted LONGLONG value, or default. + /// + /// + /// + /// This helper function is used in places where the calling application expects a PROPVARIANT to hold a LONGLONG value and + /// would like to use a default value if it does not. For instance, an application obtaining values from a property store can use + /// this to safely extract the LONGLONG value for Int64 properties. + /// + /// + /// If the source PROPVARIANT has type VT_I8, this helper function extracts the LONGLONG value. Otherwise, it attempts + /// to convert the value in the PROPVARIANT structure into a LONGLONG. If the source PROPVARIANT has type + /// VT_EMPTY or a conversion is not possible, then PropVariantToInt64WithDefault will return the default provided by + /// llDefault. See PropVariantChangeType for a list of possible conversions. + /// + /// Examples + /// + /// The following example, to be included as part of a larger program, demonstrates how to use PropVariantToInt64WithDefault to + /// access a LONGLONG value in a PROPVARIANT. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propvarutil/nf-propvarutil-propvarianttoint64withdefault PSSTDAPI_(LONGLONG) + // PropVariantToInt64WithDefault( REFPROPVARIANT propvarIn, LONGLONG llDefault ); + [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] + [PInvokeData("propvarutil.h", MSDNShortId = "6a051235-3e32-40d3-a17e-efc571592dae")] + public static extern long PropVariantToInt64WithDefault([In] PROPVARIANT propvarIn, long llDefault); + + /// + /// Extracts a string value from a PROPVARIANT structure. + /// + /// + /// Type: REFPROPVARIANT + /// Reference to a source PROPVARIANT structure. + /// + /// + /// Type: PWSTR + /// + /// Points to a string buffer. When this function returns, the buffer is initialized with a NULL terminated Unicode string value. + /// + /// + /// + /// Type: UINT + /// Size of the buffer pointed to by psz, in characters. + /// + /// + /// Type: HRESULT + /// This function can return one of these values. + /// + /// + /// Return code + /// Description + /// + /// + /// S_OK + /// The value was extracted and the result buffer was NULL terminated. + /// + /// + /// STRSAFE_E_INSUFFICIENT_BUFFER + /// + /// The copy operation failed due to insufficient buffer space. The destination buffer contains a truncated, null-terminated version + /// of the intended result. In situations where truncation is acceptable, this may not necessarily be seen as a failure condition. + /// + /// + /// + /// Some other error value + /// The extraction failed for some other reason. + /// + /// + /// + /// + /// + /// This helper function is used in places where the calling application expects a PROPVARIANT to hold a string value. For instance, + /// an application obtaining values from a property store can use this to safely extract a string value for string properties. + /// + /// + /// If the source PROPVARIANT has type VT_LPWSTR or VT_BSTR, this function extracts the string and places it into the provided + /// buffer. Otherwise, it attempts to convert the value in the PROPVARIANT structure into a string. If a conversion is not + /// possible, PropVariantToString will return a failure code and set psz to '\0'. See PropVariantChangeType for a list of possible + /// conversions. Of note, VT_EMPTY is successfully converted to "". + /// + /// + /// In addition to the terminating NULL, at most cch-1 characters are written into the buffer pointed to by psz. If the value + /// in the source PROPVARIANT is longer than will fit into the buffer, a truncated NULL Terminated copy of the string is + /// written to the buffer and this function returns STRSAFE_E_INSUFFICIENT_BUFFER. The resulting string will always be + /// NULL terminated. + /// + /// In addition to the conversions provided by PropVariantChangeType, the following special cases apply to PropVariantToString. + /// + /// + /// + /// Vector-valued PROPVARIANTs are converted to strings by separating each element with using "; ". For example, PropVariantToString + /// converts a vector of 3 integers, {3, 1, 4}, to the string "3; 1; 4". The semicolon is independent of the current locale. + /// + /// + /// + /// + /// VT_BLOB, VT_STREAM, VT_STREAMED_OBJECT, and VT_UNKNOWN values are converted to strings using an unsupported encoding. It is not + /// possible to decode strings created in this way and the format may change in the future. + /// + /// + /// + /// Examples + /// + /// The following example, to be included as part of a larger program, demonstrates how to use PropVariantToString to access a string + /// value in a PROPVARIANT. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propvarutil/nf-propvarutil-propvarianttostring PSSTDAPI PropVariantToString( + // REFPROPVARIANT propvar, PWSTR psz, UINT cch ); + [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] + [PInvokeData("propvarutil.h", MSDNShortId = "d545dc12-a780-4d95-8660-13b3f65725f9")] + public static extern HRESULT PropVariantToString([In] PROPVARIANT propvar, [MarshalAs(UnmanagedType.LPWStr)] StringBuilder psz, uint cch); + + /// Extracts a string property value from a structure. + /// Reference to the source structure. /// When this function returns, contains a pointer to the extracted property value if one exists. /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. [DllImport(Lib.PropSys, ExactSpelling = true)] [PInvokeData("Propvarutil.h", MSDNShortId = "bb776560")] public static extern HRESULT PropVariantToStringAlloc([In] PROPVARIANT propVar, [MarshalAs(UnmanagedType.CustomMarshaler, MarshalTypeRef = typeof(CoTaskMemStringMarshaler))] out string ppszOut); - /// Extracts data from a structure into a newly allocated strings in a newly allocated vector. - /// Reference to the source structure. - /// When this function returns, contains a pointer to a vector of strings extracted from source structure. - /// When this function returns, contains the count of string elements extracted from source structure. + /// + /// Extracts a vector of strings from a PROPVARIANT structure. + /// + /// + /// Type: REFPROPVARIANT + /// Reference to a source PROPVARIANT structure. + /// + /// + /// Type: PWSTR* + /// + /// Pointer to a vector of string pointers. When this function returns, the buffer has been initialized with pcElem elements pointing + /// to newly allocated strings containing the data extracted from the source PROPVARIANT. + /// + /// + /// + /// Type: ULONG + /// Size of the buffer pointed to by prgsz, in elements. + /// + /// + /// Type: ULONG* + /// When this function returns, contains the count of strings extracted from source PROPVARIANT structure. + /// + /// + /// Type: HRESULT + /// This function can return one of these values. + /// + /// + /// Return code + /// Description + /// + /// + /// S_OK + /// Returns S_OK if successful, or an error value otherwise. + /// + /// + /// TYPE_E_BUFFERTOOSMALL + /// The sourcePROPVARIANTcontained more than crgsz values. The buffer pointed to by prgsz. + /// + /// + /// E_INVALIDARG + /// ThePROPVARIANTwas not of the appropriate type. + /// + /// + /// + /// + /// + /// This helper function is used in places where the calling application expects a PROPVARIANT to hold an vector of string values + /// with a fixed number of elements. + /// + /// This function works for the following PROPVARIANT types: + /// + /// + /// VT_VECTOR | VT_LPWSTR + /// + /// + /// VT_VECTOR | VT_BSTR + /// + /// + /// VT_ARRAY | VT_BSTR + /// + /// + /// + /// If the source PROPVARIANT has a supported type, this helper function extracts up to crgsz string values and places an allocated + /// copy of each into the buffer pointed to by prgsz. If the PROPVARIANT contains more elements than will fit into the prgsz + /// buffer, this function returns an error and sets pcElem to 0. + /// + /// + /// Since each string in pointed to by the output buffer has been newly allocated, the calling application is responsible for using + /// CoTaskMemFree to free each string in the output buffer when they are no longer needed. + /// + /// + /// If a BSTR in the source PROPVARIANT is NULL, it is converted to a newly allocated string containing "" in the output. + /// + /// Examples + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propvarutil/nf-propvarutil-propvarianttostringvector PSSTDAPI + // PropVariantToStringVector( REFPROPVARIANT propvar, PWSTR *prgsz, ULONG crgsz, ULONG *pcElem ); + [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] + [PInvokeData("propvarutil.h", MSDNShortId = "6618ee02-1939-4c9c-8690-a8cd5d668cdb")] + public static extern HRESULT PropVariantToStringVector([In] PROPVARIANT propvar, IntPtr prgsz, uint crgsz, out uint pcElem); + + /// + /// Extracts a vector of strings from a PROPVARIANT structure. + /// + /// + /// Type: REFPROPVARIANT + /// Reference to a source PROPVARIANT structure. + /// + /// + /// Type: ULONG + /// The number of strings requested. + /// + /// + /// Type: PWSTR* + /// When this function returns, the array of strings containing the data extracted from the source PROPVARIANT. + /// + /// + /// Type: HRESULT + /// This function can return one of these values. + /// + /// + /// Return code + /// Description + /// + /// + /// S_OK + /// Returns S_OK if successful, or an error value otherwise. + /// + /// + /// TYPE_E_BUFFERTOOSMALL + /// The sourcePROPVARIANTcontained more than crgsz values. The buffer pointed to by prgsz. + /// + /// + /// E_INVALIDARG + /// ThePROPVARIANTwas not of the appropriate type. + /// + /// + /// + /// + /// + /// This helper function is used in places where the calling application expects a PROPVARIANT to hold an vector of string values + /// with a fixed number of elements. + /// + /// This function works for the following PROPVARIANT types: + /// + /// + /// VT_VECTOR | VT_LPWSTR + /// + /// + /// VT_VECTOR | VT_BSTR + /// + /// + /// VT_ARRAY | VT_BSTR + /// + /// + /// + /// If the source PROPVARIANT has a supported type, this helper function extracts up to crgsz string values and places an allocated + /// copy of each into the buffer pointed to by prgsz. If the PROPVARIANT contains more elements than will fit into the prgsz + /// buffer, this function returns an error and sets pcElem to 0. + /// + /// + /// Since each string in pointed to by the output buffer has been newly allocated, the calling application is responsible for using + /// CoTaskMemFree to free each string in the output buffer when they are no longer needed. + /// + /// + /// If a BSTR in the source PROPVARIANT is NULL, it is converted to a newly allocated string containing "" in the output. + /// + /// Examples + /// + public static HRESULT PropVariantToStringVector([In] PROPVARIANT propvar, uint crgsz, out string[] prgsz) + { + SafeCoTaskMemHandle ptr = new SafeCoTaskMemHandle(IntPtr.Size * (int)crgsz); + HRESULT hr = PropVariantToStringVector(propvar, (IntPtr)ptr, crgsz, out uint cnt); + prgsz = new string[0]; + if (hr.Failed) + { + return hr; + } + + prgsz = ptr.ToEnumerable((int)cnt).Select(p => ((SafeCoTaskMemHandle)p).ToString(-1)).ToArray(); + return hr; + } + + /// Extracts data from a structure into a newly allocated strings in a newly allocated vector. + /// Reference to the source structure. + /// + /// When this function returns, contains a pointer to a vector of strings extracted from source structure. + /// + /// + /// When this function returns, contains the count of string elements extracted from source structure. + /// /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. [DllImport(Lib.PropSys, ExactSpelling = true)] [PInvokeData("Propvarutil.h", MSDNShortId = "bb776562")] public static extern HRESULT PropVariantToStringVectorAlloc([In] PROPVARIANT propVar, out SafeCoTaskMemHandle pprgf, out uint pcElem); - /// Extracts the string property value of a structure. If no value exists, then the specified default value is returned. - /// Reference to a source structure. + /// + /// Extracts the string property value of a structure. If no value exists, then the specified default value + /// is returned. + /// + /// Reference to a source structure. /// Pointer to a default Unicode string value, for use where no value currently exists. May be NULL. /// Returns string value or the default. [DllImport(Lib.PropSys, ExactSpelling = true)] @@ -442,71 +1951,543 @@ namespace Vanara.PInvoke [PInvokeData("Propvarutil.h", MSDNShortId = "bb776563")] public static extern string PropVariantToStringWithDefault([In] PROPVARIANT propvarIn, [In, MarshalAs(UnmanagedType.LPWStr)] string pszDefault); - /// Extracts a UInt16 property value of a structure. - /// Reference to the source structure. + /// + /// Extracts a string from a PROPVARIANT structure and places it into a STRRET structure. + /// + /// + /// Type: REFPROPVARIANT + /// Reference to a source PROPVARIANT structure. + /// + /// + /// Type: STRRET* + /// + /// Points to the STRRET structure. When this function returns, the structure has been initialized to contain a copy of the extracted string. + /// + /// + /// + /// Type: HRESULT + /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. + /// + /// + /// + /// This helper function is used in applications that wish to convert a string value in a PROPVARIANT structure into a STRRET + /// structure. For instance, an application implementing IShellFolder::GetDisplayNameOf may find this function useful. + /// + /// + /// If the source PROPVARIANT has type VT_LPWSTR or VT_BSTR, this function extracts the string and places it into the STRRET + /// structure. Otherwise, it attempts to convert the value in the PROPVARIANT structure into a string. If a conversion is not + /// possible, PropVariantToString will return a failure code. See PropVariantChangeType for a list of possible conversions. Of note, + /// VT_EMPTY is successfully converted to "". + /// + /// In addition to the conversions provided by PropVariantChangeType, the following special cases apply to PropVariantToString. + /// + /// + /// + /// Vector-valued PROPVARIANTs are converted to strings by separating each element with using "; ". For example, PropVariantToString + /// converts a vector of 3 integers, {3, 1, 4}, to the string "3; 1; 4". The semicolon is independent of the current locale. + /// + /// + /// + /// + /// VT_BLOB, VT_STREAM, VT_STREAMED_OBJECT, and VT_UNKNOWN values are converted to strings using an unsupported encoding. It is not + /// possible to decode strings created in this way and the format may change in the future. + /// + /// + /// + /// + /// If the extraction is successful, the function will initialize uType member of the STRRET structure with STRRET_WSTR and set the + /// pOleStr member of that structure to point to an allocated copy of the string. The calling application is responsible for using + /// CoTaskMemFree or StrRetToStr to free this string when it is no longer needed. + /// + /// Examples + /// + /// The following example, to be included as part of a larger program, demonstrates how to use PropVariantToString to access a string + /// value in a PROPVARIANT. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propvarutil/nf-propvarutil-propvarianttostrret PSSTDAPI PropVariantToStrRet( + // REFPROPVARIANT propvar, STRRET *pstrret ); + [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] + [PInvokeData("propvarutil.h", MSDNShortId = "a1a33606-172d-4ee7-98c9-ffec8eed98bf")] + public static extern HRESULT PropVariantToStrRet([In] PROPVARIANT propvar, IntPtr pstrret); + + /// Extracts a UInt16 property value of a structure. + /// Reference to the source structure. /// When this function returns, contains the extracted property value if one exists; otherwise, 0. /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. [DllImport(Lib.PropSys, ExactSpelling = true)] [PInvokeData("Propvarutil.h", MSDNShortId = "bb776565")] public static extern HRESULT PropVariantToUInt16([In] PROPVARIANT propVar, [MarshalAs(UnmanagedType.U2)] out ushort puiRet); - /// Extracts data from a structure into a newly allocated UInt16 vector. - /// Reference to the source structure. - /// When this function returns, contains a pointer to a vector of UInt16 values extracted from the source structure. - /// When this function returns, contains the count of UInt16 elements extracted from source structure. + /// + /// Extracts data from a PROPVARIANT structure into an unsigned short vector. + /// + /// + /// Type: REFPROPVARIANT + /// Reference to a source PROPVARIANT structure. + /// + /// + /// Type: USHORT* + /// + /// Points to a buffer containing crgn unsigned short values. When this function returns, the buffer has been initialized with + /// pcElem unsigned short elements extracted from the source PROPVARIANT. + /// + /// + /// + /// Type: ULONG + /// Size of the buffer pointed to by prgn in elements. + /// + /// + /// Type: ULONG* + /// When this function returns, contains the count of unsigned short values extracted from the source PROPVARIANT structure. + /// + /// + /// Type: HRESULT + /// This function can return one of these values. + /// + /// + /// Return code + /// Description + /// + /// + /// S_OK + /// Returns S_OK if successful, or an error value otherwise. + /// + /// + /// TYPE_E_BUFFERTOOSMALL + /// The source PROPVARIANT contained more than crgn values. The buffer pointed to by prgn. + /// + /// + /// E_INVALIDARG + /// The PROPVARIANT was not of the appropriate type. + /// + /// + /// + /// + /// + /// This helper function is used in places where the calling application expects a PROPVARIANT to hold an vector of unsigned + /// short values with a fixed number of elements. + /// + /// + /// If the source PROPVARIANT has type VT_VECTOR | VT_UI2 or VT_ARRAY | VT_UI2, this helper function + /// extracts up to crgn unsigned short values and places them into the buffer pointed to by prgn. If the PROPVARIANT + /// contains more elements than will fit into the prgn buffer, this function returns an error and sets pcElem to 0. + /// + /// Examples + /// + /// The following example, to be included as part of a larger program, demonstrates how to use PropVariantToUInt16Vector to access an + /// unsigned short vector value in a PROPVARIANT. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propvarutil/nf-propvarutil-propvarianttouint16vector PSSTDAPI + // PropVariantToUInt16Vector( REFPROPVARIANT propvar, USHORT *prgn, ULONG crgn, ULONG *pcElem ); + [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] + [PInvokeData("propvarutil.h", MSDNShortId = "34fe404c-cef6-47d9-9eaf-8ab151bd4726")] + public static extern HRESULT PropVariantToUInt16Vector([In] PROPVARIANT propvar, [In, Out, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 2)] ushort[] prgn, uint crgn, out uint pcElem); + + /// Extracts data from a structure into a newly allocated UInt16 vector. + /// Reference to the source structure. + /// + /// When this function returns, contains a pointer to a vector of UInt16 values extracted from the source structure. + /// + /// + /// When this function returns, contains the count of UInt16 elements extracted from source structure. + /// /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. [DllImport(Lib.PropSys, ExactSpelling = true)] [PInvokeData("Propvarutil.h", MSDNShortId = "bb776567")] public static extern HRESULT PropVariantToUInt16VectorAlloc([In] PROPVARIANT propVar, out SafeCoTaskMemHandle pprgf, out uint pcElem); - /// Extracts a UInt32 property value of a structure. - /// Reference to the source structure. + /// + /// + /// Extracts an unsigned short value from a PROPVARIANT structure. If no value exists, then the specified default value is returned. + /// + /// + /// + /// Type: REFPROPVARIANT + /// Reference to a source PROPVARIANT structure. + /// + /// + /// Type: USHORT + /// Specifies a default property value, for use where no value currently exists. + /// + /// + /// Type: unsigned short + /// Returns extracted unsigned short value, or default. + /// + /// + /// + /// This helper function is used in places where the calling application expects a PROPVARIANT to hold a unsigned short value. + /// For instance, an application obtaining values from a property store can use this to safely extract the unsigned short + /// value for UInt16 properties. + /// + /// + /// If the source PROPVARIANT has type VT_UI2, this helper function extracts the unsigned short value. Otherwise, it + /// attempts to convert the value in the PROPVARIANT structure into a unsigned short. If a conversion is not possible, + /// PropVariantToUInt16 will return a failure code and set puiRet to 0. See PropVariantChangeType for a list of possible conversions. + /// Of note, VT_EMPTY is successfully converted to 0. + /// + /// Examples + /// + /// The following example, to be included as part of a larger program, demonstrates how to use PropVariantToUInt16 to access a + /// unsigned short value in a PROPVARIANT. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propvarutil/nf-propvarutil-propvarianttouint16withdefault PSSTDAPI_(USHORT) + // PropVariantToUInt16WithDefault( REFPROPVARIANT propvarIn, USHORT uiDefault ); + [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] + [PInvokeData("propvarutil.h", MSDNShortId = "4346cef2-5e43-47bf-9bfb-0ede923872fd")] + public static extern ushort PropVariantToUInt16WithDefault([In] PROPVARIANT propvarIn, ushort uiDefault); + + /// Extracts a UInt32 property value of a structure. + /// Reference to the source structure. /// When this function returns, contains the extracted property value if one exists; otherwise, 0. /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. [DllImport(Lib.PropSys, ExactSpelling = true)] [PInvokeData("Propvarutil.h", MSDNShortId = "bb776569")] public static extern HRESULT PropVariantToUInt32([In] PROPVARIANT propVar, [MarshalAs(UnmanagedType.U4)] out uint pulRet); - /// Extracts data from a structure into a newly allocated UInt32 vector. - /// Reference to the source structure. - /// When this function returns, contains a pointer to a vector of UInt32 values extracted from the source structure. - /// When this function returns, contains the count of UInt32 elements extracted from source structure. + /// + /// Extracts data from a PROPVARIANT structure into an ULONG vector. + /// + /// + /// Type: REFPROPVARIANT + /// Reference to a source PROPVARIANT structure. + /// + /// + /// Type: ULONG* + /// + /// Points to a buffer containing crgn ULONG values. When this function returns, the buffer has been initialized with pcElem + /// ULONG elements extracted from the source PROPVARIANT. + /// + /// + /// + /// Type: ULONG + /// Size of the buffer pointed to by prgn, in elements. + /// + /// + /// Type: ULONG* + /// When this function returns, contains the count of ULONG values extracted from the source PROPVARIANT structure. + /// + /// + /// Type: HRESULT + /// This function can return one of these values. + /// + /// + /// Return code + /// Description + /// + /// + /// S_OK + /// Returns S_OK if successful, or an error value otherwise. + /// + /// + /// TYPE_E_BUFFERTOOSMALL + /// The source PROPVARIANT contained more than crgn values. The buffer pointed to by prgn is too small. + /// + /// + /// E_INVALIDARG + /// The PROPVARIANT was not of the appropriate type. + /// + /// + /// + /// + /// + /// This helper function is used in places where the calling application expects a PROPVARIANT to hold an vector of ULONG + /// values with a fixed number of elements. + /// + /// + /// If the source PROPVARIANT has type VT_VECTOR | VT_UI4 or VT_ARRAY | VT_UI4, this helper function + /// extracts up to crgn ULONG values and places them into the buffer pointed to by prgn. If the PROPVARIANT contains + /// more elements than will fit into the prgn buffer, this function returns an error and sets pcElem to 0. + /// + /// Examples + /// + /// The following example, to be included as part of a larger program, demonstrates how to use PropVariantToUInt32Vector to access a + /// ULONG vector value in a PROPVARIANT. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propvarutil/nf-propvarutil-propvarianttouint32vector PSSTDAPI + // PropVariantToUInt32Vector( REFPROPVARIANT propvar, ULONG *prgn, ULONG crgn, ULONG *pcElem ); + [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] + [PInvokeData("propvarutil.h", MSDNShortId = "721a2f67-dfd1-4d95-8290-4457b8954a02")] + public static extern HRESULT PropVariantToUInt32Vector([In] PROPVARIANT propvar, [In, Out, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 2)] uint[] prgn, uint crgn, out uint pcElem); + + /// Extracts data from a structure into a newly allocated UInt32 vector. + /// Reference to the source structure. + /// + /// When this function returns, contains a pointer to a vector of UInt32 values extracted from the source structure. + /// + /// + /// When this function returns, contains the count of UInt32 elements extracted from source structure. + /// /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. [DllImport(Lib.PropSys, ExactSpelling = true)] [PInvokeData("Propvarutil.h", MSDNShortId = "bb776571")] public static extern HRESULT PropVariantToUInt32VectorAlloc([In] PROPVARIANT propVar, out SafeCoTaskMemHandle pprgf, out uint pcElem); - /// Extracts a UInt64 property value of a structure. - /// Reference to the source structure. + /// + /// Extracts a ULONG value from a PROPVARIANT structure. If no value exists, then a specified default value is returned. + /// + /// + /// Type: REFPROPVARIANT + /// Reference to a source PROPVARIANT structure. + /// + /// + /// Type: ULONG + /// Specifies a default property value, for use where no value currently exists. + /// + /// + /// Type: ULONG + /// Returns extracted ULONG value, or default. + /// + /// + /// + /// This helper function is used in places where the calling application expects a PROPVARIANT to hold a ULONG value and would + /// like to use a default value if it does not. For instance, an application obtaining values from a property store can use this to + /// safely extract the ULONG value for UInt32 properties. + /// + /// + /// If the source PROPVARIANT has type VT_UI4, this helper function extracts the ULONG value. Otherwise, it attempts to + /// convert the value in the PROPVARIANT structure into a ULONG. If the source PROPVARIANT has type + /// VT_EMPTY or a conversion is not possible, then PropVariantToUInt32WithDefault will return the default provided by + /// ulDefault. See PropVariantChangeType for a list of possible conversions. + /// + /// Examples + /// + /// The following example, to be included as part of a larger program, demonstrates how to use PropVariantToUInt32WithDefault to + /// access a ULONG value in a PROPVARIANT. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propvarutil/nf-propvarutil-propvarianttouint32withdefault PSSTDAPI_(ULONG) + // PropVariantToUInt32WithDefault( REFPROPVARIANT propvarIn, ULONG ulDefault ); + [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] + [PInvokeData("propvarutil.h", MSDNShortId = "8ace8c3f-fea2-4b20-9e0b-3abfbd569b54")] + public static extern uint PropVariantToUInt32WithDefault([In] PROPVARIANT propvarIn, uint ulDefault); + + /// Extracts a UInt64 property value of a structure. + /// Reference to the source structure. /// When this function returns, contains the extracted property value if one exists; otherwise, 0. /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. [DllImport(Lib.PropSys, ExactSpelling = true)] [PInvokeData("Propvarutil.h", MSDNShortId = "bb776573")] public static extern HRESULT PropVariantToUInt64([In] PROPVARIANT propVar, [MarshalAs(UnmanagedType.U8)] out ulong pullRet); - /// Extracts data from a structure into a newly allocated UInt64 vector. - /// Reference to the source structure. - /// When this function returns, contains a pointer to a vector of UInt64 values extracted from the source structure. - /// When this function returns, contains the count of UInt64 elements extracted from source structure. + /// + /// Extracts data from a PROPVARIANT structure into a ULONGLONG vector. + /// + /// + /// Type: REFPROPVARIANT + /// Reference to a source PROPVARIANT structure. + /// + /// + /// Type: ULONGLONG* + /// + /// Points to a buffer containing crgn ULONGLONG values. When this function returns, the buffer has been initialized with + /// pcElem ULONGLONG elements extracted from the source PROPVARIANT. + /// + /// + /// + /// Type: ULONG + /// Size of the buffer pointed to by prgn, in elements. + /// + /// + /// Type: ULONG* + /// When this function returns, contains the count of ULONGLONG values extracted from the source PROPVARIANT structure. + /// + /// + /// Type: HRESULT + /// This function can return one of these values. + /// + /// + /// Return code + /// Description + /// + /// + /// S_OK + /// Returns S_OK if successful, or an error value otherwise. + /// + /// + /// TYPE_E_BUFFERTOOSMALL + /// The source PROPVARIANT contained more than crgn values. The buffer pointed to by prgn. + /// + /// + /// E_INVALIDARG + /// The PROPVARIANT was not of the appropriate type. + /// + /// + /// + /// + /// + /// This helper function is used in places where the calling application expects a PROPVARIANT to hold an vector of ULONGLONG + /// values with a fixed number of elements. + /// + /// + /// If the source PROPVARIANT has type VT_VECTOR | VT_UI8 or VT_ARRAY | VT_UI8, this helper function + /// extracts up to crgn ULONGLONG values and places them into the buffer pointed to by prgn. If the PROPVARIANT + /// contains more elements than will fit into the prgn buffer, this function returns an error and sets pcElem to 0. + /// + /// Examples + /// + /// The following example, to be included as part of a larger program, demonstrates how to use PropVariantToUInt64Vector to access a + /// ULONGLONG vector value in a PROPVARIANT. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propvarutil/nf-propvarutil-propvarianttouint64vector PSSTDAPI + // PropVariantToUInt64Vector( REFPROPVARIANT propvar, ULONGLONG *prgn, ULONG crgn, ULONG *pcElem ); + [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] + [PInvokeData("propvarutil.h", MSDNShortId = "596c7a35-6645-4f66-b924-b71278778776")] + public static extern HRESULT PropVariantToUInt64Vector([In] PROPVARIANT propvar, [In, Out, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 2)] ulong[] prgn, uint crgn, out uint pcElem); + + /// Extracts data from a structure into a newly allocated UInt64 vector. + /// Reference to the source structure. + /// + /// When this function returns, contains a pointer to a vector of UInt64 values extracted from the source structure. + /// + /// + /// When this function returns, contains the count of UInt64 elements extracted from source structure. + /// /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. [DllImport(Lib.PropSys, ExactSpelling = true)] [PInvokeData("Propvarutil.h", MSDNShortId = "bb776575")] public static extern HRESULT PropVariantToUInt64VectorAlloc([In] PROPVARIANT propVar, out SafeCoTaskMemHandle pprgf, out uint pcElem); - /// Converts the contents of a structure to a VARIANT structure. - /// Reference to the source structure. + /// + /// + /// Extracts ULONGLONG value from a PROPVARIANT structure. If no value exists, then the specified default value is returned. + /// + /// + /// + /// Type: REFPROPVARIANT + /// Reference to a source PROPVARIANT structure. + /// + /// + /// Type: ULONGLONG + /// Specifies a default property value, for use where no value currently exists. + /// + /// + /// Type: ULONGLONG + /// Returns the extracted unsigned LONGLONG value, or a default. + /// + /// + /// + /// This helper function is used in places where the calling application expects a PROPVARIANT to hold a ULONGLONG value and + /// would like to use a default value if it does not. For instance, an application obtaining values from a property store can use + /// this to safely extract the ULONGLONG value for UInt64 properties. + /// + /// + /// If the source PROPVARIANT has type VT_UI8, this helper function extracts the ULONGLONG value. Otherwise, it + /// attempts to convert the value in the PROPVARIANT structure into a ULONGLONG. If the source PROPVARIANT has + /// type VT_EMPTY or a conversion is not possible, then PropVariantToUInt64WithDefault will return the default provided by + /// ullDefault. See PropVariantChangeType for a list of possible conversions. + /// + /// Examples + /// + /// The following example, to be included as part of a larger program, demonstrates how to use PropVariantToUInt64WithDefault to + /// access a ULONGLONG value in a PROPVARIANT. + /// + /// + // https://docs.microsoft.com/en-us/windows/desktop/api/propvarutil/nf-propvarutil-propvarianttouint64withdefault + // PSSTDAPI_(ULONGLONG) PropVariantToUInt64WithDefault( REFPROPVARIANT propvarIn, ULONGLONG ullDefault ); + [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] + [PInvokeData("propvarutil.h", MSDNShortId = "8ca0e25e-6a3f-41ff-9a4a-7cca9a02d07c")] + public static extern ulong PropVariantToUInt64WithDefault([In] PROPVARIANT propvarIn, ulong ullDefault); + + /// Converts the contents of a structure to a VARIANT structure. + /// Reference to the source structure. /// Pointer to a VARIANT structure. When this function returns, the VARIANT contains the converted information. /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. [DllImport(Lib.PropSys, ExactSpelling = true)] [PInvokeData("Propvarutil.h", MSDNShortId = "bb776577")] public static extern HRESULT PropVariantToVariant([In] PROPVARIANT pPropVar, IntPtr pVar); - /// Copies the contents of a VARIANT structure to a structure. + /// + /// + /// Extracts data from a PROPVARIANT structure into a Windows Runtime property value. Note that in some cases more than one + /// PROPVARIANT type maps to a single Windows Runtime property type. + /// + /// + /// + /// Reference to a source PROPVARIANT structure. + /// + /// + /// A reference to the IID of the interface to retrieve through ppv, typically IID_IPropertyValue (defined in Windows.Foundation.h). + /// + /// + /// + /// When this method returns successfully, contains the interface pointer requested in riid. This is typically an IPropertyValue + /// pointer. If the call fails, this value is NULL. + /// + /// + /// + /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. + /// + /// + /// + /// 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-propvarianttowinrtpropertyvalue PSSTDAPI + // PropVariantToWinRTPropertyValue( REFPROPVARIANT propvar, REFIID riid, void **ppv ); + [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] + [PInvokeData("propsys.h", MSDNShortId = "38DD3673-17FD-4F2A-BA58-A1A9983B92BF")] + public static extern HRESULT PropVariantToWinRTPropertyValue([In] PROPVARIANT propvar, [In, MarshalAs(UnmanagedType.LPStruct)] Guid riid, [MarshalAs(UnmanagedType.IUnknown)] out object ppv); + + /// Deserializes a specified SERIALIZEDPROPERTYVALUE structure, creating a PROPVARIANT structure. + /// + /// Type: const SERIALIZEDPROPERTYVALUE* + /// Pointer to a SERIALIZEDPROPERTYVALUE structure. + /// + /// + /// Type: ULONG + /// The size of the SERIALIZEDPROPERTYVALUE structure, in bytes. + /// + /// + /// Type: PROPVARIANT* + /// Pointer to the resulting PROPVARIANT structure. + /// + /// + /// Type: HRESULT + /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. + /// + // HRESULT StgDeserializePropVariant( _In_ const SERIALIZEDPROPERTYVALUE *pprop, _In_ ULONG cbMax, _Out_ PROPVARIANT *ppropvar); https://msdn.microsoft.com/en-us/library/windows/desktop/bb776578(v=vs.85).aspx + [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] + [PInvokeData("Propvarutil.h", MSDNShortId = "bb776578")] + public static extern HRESULT StgDeserializePropVariant([In] IntPtr pprop, [In] uint cbMax, [In, Out] PROPVARIANT ppropvar); + + /// Serializes a specified PROPVARIANT structure, creating a SERIALIZEDPROPERTYVALUE structure. + /// + /// Type: const PROPVARIANT* + /// A constant pointer to the source PROPVARIANT structure. + /// + /// + /// Type: SERIALIZEDPROPERTYVALUE** + /// The address of a pointer to the SERIALIZEDPROPERTYVALUE structure. + /// + /// + /// Type: ULONG* + /// A pointer to the value representing the size of the SERIALIZEDPROPERTYVALUE structure. + /// + /// + /// Type: HRESULT + /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. + /// + // HRESULT StgSerializePropVariant( _In_ const PROPVARIANT *ppropvar, _Out_ SERIALIZEDPROPERTYVALUE **ppProp, _Out_ ULONG *pcb); https://msdn.microsoft.com/en-us/library/windows/desktop/bb776579(v=vs.85).aspx + [DllImport(Lib.PropSys, SetLastError = false, ExactSpelling = true)] + [PInvokeData("Propvarutil.h", MSDNShortId = "bb776579")] + public static extern HRESULT StgSerializePropVariant([In] PROPVARIANT ppropvar, out SafeCoTaskMemHandle ppProp, out uint pcb); + + /// Copies the contents of a VARIANT structure to a structure. /// Pointer to a source VARIANT structure. - /// Pointer to a structure. When this function returns, the contains the converted information. + /// + /// Pointer to a structure. When this function returns, the contains the + /// converted information. + /// /// If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code. [DllImport(Lib.PropSys, ExactSpelling = true)] [PInvokeData("Propvarutil.h", MSDNShortId = "bb776616")] public static extern HRESULT VariantToPropVariant([In] IntPtr pVar, [In, Out] PROPVARIANT pPropVar); } -} +} \ No newline at end of file